共有ランタイムのないカスタム関数の認証

一部のシナリオでは、 共有ランタイム を使用しないカスタム関数は、保護されたリソースにアクセスするためにユーザーを認証する必要があります。 共有ランタイムを使用しないカスタム関数は、 JavaScript 専用ランタイムで実行されます。 このため、アドインに作業ウィンドウがある場合は、JavaScript 専用ランタイムと作業ウィンドウで使用される HTML サポート ランタイムの間でデータをやり取りする必要があります。 これを行うには、 OfficeRuntime.storage オブジェクトと特別な Dialog API を使用します。

OfficeRuntime.storage オブジェクト

JavaScript 専用ランタイムには、通常、データを格納するグローバル ウィンドウで使用できる localStorage オブジェクトがありません。 代わりに、 OfficeRuntime.storage を使用してデータを設定および取得することで、コードでカスタム関数と作業ウィンドウ間でデータを共有する必要があります。

おすすめの使用法

共有ランタイムを使用しないカスタム関数アドインから認証する必要がある場合、コードはアクセス トークンが既に取得されているかどうかを確認するためにチェック OfficeRuntime.storageする必要があります。 そうでない場合は、 OfficeRuntime.displayWebDialog を使用してユーザーを認証し、アクセス トークンを取得し、後で使用するためにトークンを OfficeRuntime.storage に格納します。

ダイアログ API

トークンが存在しない場合は、 OfficeRuntime.dialog API を使用して、ユーザーにサインインを求める必要があります。 ユーザーが資格情報を入力すると、結果のアクセス トークンをアイテムとして OfficeRuntime.storageに格納できます。

この基本的な手順を次の図に示します。 点線は、カスタム関数とアドインの作業ウィンドウがアドイン全体の一部であることを示しますが、これらは別々のランタイムを使用します。

1. Excel ワークブックのセルからカスタム関数を発行します。
2. カスタム関数は、ユーザーの資格情報を web サイトに渡すために OfficeRuntime.dialog を使用します。
3. この Web サイトは、ダイアログのページにアクセス トークンを返します。
4. ダイアログの JavaScript で Office.ui.messageParent 関数を呼び出して、アクセス トークンをカスタム関数に送信します。 この関数の詳細については、「 ダイアログ ボックスからホスト ページに情報を送信する」を参照してください。
5. カスタム関数は、このアクセス トークンを OfficeRuntime.storage内の項目に設定します。
6. アドインの作業ウィンドウは、OfficeRuntime.storage からトークンにアクセスします。

トークンの格納

次の例は、カスタム関数の OfficeRuntime.storage を使用 したコードサンプルです。 カスタム関数と、共有ランタイムを使用しないアドインの作業ウィンドウ間でデータを共有する完全な例については、このコード サンプルを参照してください。

カスタム関数が認証されたら、アクセストークンを受け取り、OfficeRuntime.storageに保存する必要があります。 次のコードサンプルは、storage.setItemメソッドを呼び出して値を格納する方法を示します。 storeValue関数は、ユーザーからの値を格納するカスタム関数です。 必要なトークン値を格納するように変更できます。

/**
 * Stores a key-value pair into OfficeRuntime.storage.
 * @customfunction
 * @param {string} key Key of item to put into storage.
 * @param {*} value Value of item to put into storage.
 */
function storeValue(key, value) {
  return OfficeRuntime.storage.setItem(key, value).then(function (result) {
      return "Success: Item with key '" + key + "' saved to storage.";
  }, function (error) {
      return "Error: Unable to save item with key '" + key + "' to storage. " + error;
  });
}

作業ウィンドウでアクセス トークンが必要な場合は、 OfficeRuntime.storage 項目からトークンを取得できます。 次のコードサンプルは、storage.getItemメソッドを使用してトークンを取得する方法を示します。

/**
 * Read a token from storage.
 * @customfunction GETTOKEN
 */
function receiveTokenFromCustomFunction() {
  const key = "token";
  const tokenSendStatus = document.getElementById('tokenSendStatus');
  OfficeRuntime.storage.getItem(key).then(function (result) {
     tokenSendStatus.value = "Success: Item with key '" + key + "' read from storage.";
     document.getElementById('tokenTextBox2').value = result;
  }, function (error) {
     tokenSendStatus.value = "Error: Unable to read item with key '" + key + "' from storage. " + error;
  });
}

一般的なガイダンス

Office アドインは web ベースで、あらゆる web 認証技術を使用できます。 カスタム関数を使用して独自の認証を実装するのに、特定のパターンやメソッドはありません。 さまざまな認証パターンに関するドキュメントを参照してください。 この記事では、外部サービスによる認証について説明します。

カスタム関数を開発するときに、次の場所にデータを格納しないようにします。

• localStorage: 共有ランタイムを使用しないカスタム関数は、グローバル window オブジェクトにアクセスできないため、 localStorageに格納されているデータにアクセスできません。
• Office.context.document.settings: この場所は安全ではなく、アドインを使用して誰でも情報を抽出できます。

ダイアログ ボックス API の例

次のコード サンプルでは、 getTokenViaDialog 関数は OfficeRuntime.displayWebDialog 関数を使用してダイアログ ボックスを表示します。 このサンプルは、認証方法を示すのではなく、 メソッドの機能を示すために提供されます。

/**
 * Function retrieves a cached token or opens a dialog box if there is no saved token. Note that this isn't a sufficient example of authentication but is intended to show the capabilities of the displayWebDialog method.
 * @param {string} url URL for a stored token.
 */
function getTokenViaDialog(url) {
  return new Promise (function (resolve, reject) {
    if (_dialogOpen) {
      // Can only have one dialog box open at once. Wait for previous dialog box's token.
      let timeout = 5;
      let count = 0;
      const intervalId = setInterval(function () {
        count++;
        if(_cachedToken) {
          resolve(_cachedToken);
          clearInterval(intervalId);
        }
        if(count >= timeout) {
          reject("Timeout while waiting for token");
          clearInterval(intervalId);
        }
      }, 1000);
    } else {
      _dialogOpen = true;
      OfficeRuntime.displayWebDialog(url, {
        height: '50%',
        width: '50%',
        onMessage: function (message, dialog) {
          _cachedToken = message;
          resolve(message);
          dialog.close();
          return;
        },
        onRuntimeError: function(error, dialog) {
          reject(error);
        },
      }).catch(function (e) {
        reject(e);
      });
    }
  });
}

次の手順

カスタム関数をデバッグする方法について説明します。

関連項目

• カスタム関数のための JavaScript 専用ランタイム
• Excel カスタム関数のチュートリアル
• JavaScript 専用ランタイム