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

Excel カスタム関数が 共有ランタイムを使用しない場合は、 JavaScript 専用ランタイムで実行されます。 そのランタイムでは、認証には通常、ダイアログ フローと作業ウィンドウとのトークン共有が必要です。

OfficeRuntime.displayWebDialog を使用してサインインし、OfficeRuntime.storage を使用してランタイム間でトークンをキャッシュおよび共有します。

認証ワークフロー

次のワークフローは、共有ランタイムを使用しないカスタム関数の場合に一般的です。

1. ユーザーは Excel セルでカスタム関数を実行します。
2. カスタム関数は OfficeRuntime.displayWebDialog を呼び出して、ユーザーが資格情報を入力するダイアログでサインイン ページを開きます。
3. サインイン ページは、ダイアログへのアクセス トークンを返します。
4. ダイアログで Office.ui.messageParent が呼び出され、アクセス トークンがカスタム関数に送信されます。 詳細については、「 ダイアログ ボックスからホスト ページに情報を送信する」を参照してください。
5. カスタム関数は、アクセス トークンを OfficeRuntime.storageに格納します。
6. アドインの作業ウィンドウは、 OfficeRuntime.storageからトークンを取得します。

サンプルで試す

カスタム関数と作業ウィンドウの間でトークンの格納と取得をテストするには、 カスタム関数での OfficeRuntime.storage の使用 サンプルを使用します。

ダイアログ API

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

ダイアログ ボックス 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);
      });
    }
  });
}

OfficeRuntime.storage オブジェクト

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

おすすめの使用法

共有ランタイムを使用しないカスタム関数アドインから認証する必要がある場合、コードはアクセス トークンが既に取得されているかどうかを確認するためにチェック OfficeRuntime.storageする必要があります。 そうでない場合は、 OfficeRuntime.displayWebDialog を使用してユーザーを認証し、アクセス トークンを取得し、後で使用するためにトークンを 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 認証手法を使用できます。 カスタム関数に必要な認証パターンは 1 つありません。 最初に、デザイン パターンとトレードオフについて Office アドインの外部サービスに対する承認 を行います。

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

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

次の手順

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

関連項目

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