Share via

カスタム関数でデータを受信して​​処理する

  • [アーティクル]

カスタム関数が Excel の機能を強化する方法の 1 つは、( WebSocket を介して) Web やサーバーなどのブック以外の場所からデータを受信することです。 外部データは、(XHR) などの Fetch API を使用してXmlHttpRequest要求できます。これは、サーバーと対話するための HTTP 要求を発行する標準の Web API です。

重要

Excel カスタム関数は、次のプラットフォームで使用できます。

  • Office on the web
  • Windows での Office
    • Microsoft 365 サブスクリプション
    • retail 永久 Office 2016 以降
    • ボリューム ライセンスの永続的なOffice 2021以降
  • Office on Mac

Excel カスタム関数は現在、次ではサポートされていません。

  • Office on iPad
  • Windows での Office 2019 以前のボリューム ライセンスの永続的バージョン

API から時間をストリーミングするカスタム関数の GIF。

外部ソースからデータを返す関数

カスタム関数が外部ソースからデータを取得する場合には、以下のことを実行する必要があります。

  1. JavaScript Promise を Excel に返します。
  2. コールバック関数を Promise 使用して、 を最終的な値で解決します。

Fetch の使用例

次のコード サンプルでは、関数は webRequest 、現在国際宇宙ステーションにいるユーザーの数を追跡する架空の外部 API に到達します。 関数は JavaScript Promise を返し、 を使用 fetch して架空の API から情報を要求します。 結果のデータは JSON に変換され、 names プロパティは文字列に変換され、promise を解決するために使用されます。

独自の機能を開発するときに、Web 要求が時間内に完了しない場合は、アクションを実行するか、複数の API 要求をバッチ処理することを検討してください。

/**
 * Requests the names of the people currently on the International Space Station.
 * Note: This function requests data from a hypothetical URL. In practice, replace the URL with a data source for your scenario.
 * @customfunction
 */
function webRequest() {
  let url = "https://www.contoso.com/NumberOfPeopleInSpace"; // This is a hypothetical URL.
  return new Promise(function (resolve, reject) {
    fetch(url)
      .then(function (response){
        return response.json();
        }
      )
      .then(function (json) {
        resolve(JSON.stringify(json.names));
      })
  })
}

注:

fetchを使用すると、コールバックのネストが回避され、場合によっては XHR に適している場合があります。

XHR の使用例

次のコード サンプルでは、関数は getStarCount Github API を呼び出して、特定のユーザーのリポジトリに与えられた星の量を検出します。 これは、JavaScript Promiseを返す非同期関数です。 Web 呼び出しからデータが取得されると、データをセルに返す promise が解決されます。

/**
 * Gets the star count for a given Github organization or user and repository.
 * @customfunction
 * @param userName string name of organization or user.
 * @param repoName string name of the repository.
 * @return number of stars.
 */
async function getStarCount(userName: string, repoName: string) {

  const url = "https://api.github.com/repos/" + userName + "/" + repoName;

  let xhttp = new XMLHttpRequest();

  return new Promise(function(resolve, reject) {
    xhttp.onreadystatechange = function() {
      if (xhttp.readyState !== 4) return;

      if (xhttp.status == 200) {
        resolve(JSON.parse(xhttp.responseText).watchers_count);
      } else {
        reject({
          status: xhttp.status,

          statusText: xhttp.statusText
        });
      }
    };

    xhttp.open("GET", url, true);

    xhttp.send();
  });
}

ストリーミング関数を作成する

ストリーム カスタム関数を使用すると、繰り返し更新されるセルにデータを出力でき、ユーザーが明示的に何かを更新する必要ありません。 これは、カスタム関数のチュートリアルの関数のように、サービス オンラインのライブ データを確認する際に便利です。

ストリーミング関数を宣言するには、次の 2 つのオプションのいずれかを使用できます。

  • @streaming JSDoc タグ。
  • CustomFunctions.StreamingInvocation呼び出しパラメーター。

以下のコード サンプルは、毎秒ごとに結果に数値を追加するカスタム関数です。 このコードについては、次の点に注意してください。

  • Excel は、setResult メソッドを使用して自動的に新しい値を表示します。
  • 2 番目の入力パラメーターの invocation は、[オートコンプリート] メニューから関数が選択された場合、Excel のエンドユーザーに表示されません。
  • コールバックは onCanceled 、関数が取り消されたときに実行される関数を定義します。
  • ストリーミングは、必ずしも Web 要求の作成に関連付けられているわけではありません。 この場合、関数は Web 要求を行いませんが、設定された間隔でデータを取得するため、ストリーミング invocation パラメーターを使用する必要があります。
/**
 * Increments a value once a second.
 * @customfunction INC increment
 * @param {number} incrementBy Amount to increment
 * @param {CustomFunctions.StreamingInvocation<number>} invocation
 */
function increment(incrementBy, invocation) {
  let result = 0;
  const timer = setInterval(() => {
    result += incrementBy;
    invocation.setResult(result);
  }, 1000);

  invocation.onCanceled = () => {
    clearInterval(timer);
  };
}

注:

ストリーミング関数から動的スピル配列を返す方法の例については、「 カスタム関数から複数の結果を返す: コード サンプル」を参照してください。

関数を取り消す

Excel は、次の状況で関数の実行を取り消します。

  • ユーザーが、関数を参照するセルを編集または削除した場合。
  • 関数の引数 (入力) の 1 つが変更されたとき。 この場合、キャンセルに続いて、関数の新しい呼び出しがトリガーされます。
  • ユーザーが手動で再計算をトリガーしたとき。 この場合、キャンセルに続いて、関数の新しい呼び出しがトリガーされます。

また、要求が発生したときに、オフラインの場合でも、ケースを処理する既定のストリーミング値を設定することもできます。

注:

JSDoc タグを使用する取り消し可能関数と呼ばれる関数の @cancelable カテゴリもあります。 取り消し可能な関数を使用すると、要求の途中で Web 要求を終了できます。

ストリーミング関数ではタグを @cancelable 使用できませんが、ストリーミング関数にはコールバック関数を onCanceled 含めることができます。 JSDoc タグを使用できるのは、1 つの値を @cancelable 返す非同期カスタム関数のみです。 タグの詳細については、こちらをご@cancelable覧Autogenerate JSON metadata: @cancelableください。

呼び出しパラメーターを使用する

invocation パラメーターは、既定ではカスタム関数の最後のパラメーターです。 パラメーターはinvocation、セルに関するコンテキスト (アドレスや内容など) を提供し、メソッドとonCanceledイベントをsetResult使用して、関数がストリーム処理 () または取り消し時onCanceled () に何を行うかをsetResult定義できます。

呼び出しハンドラーは、型 CustomFunctions.StreamingInvocation であるか、または CustomFunctions.CancelableInvocation Web 要求を処理する必要があります。

引数のその他のinvocation潜在的な使用方法と、それが Invocation オブジェクトとどのように対応するかについては、「呼び出しパラメーター」を参照してください。

WebSocket 経由のデータ受信

カスタム関数内で、WebSocket を使用して、サーバーとの固定接続経由でデータを交換することができます。 WebSocket を使用すると、カスタム関数はサーバーとの接続を開き、特定のイベントが発生したときにサーバーからメッセージを自動的に受信できます。サーバーでデータを明示的にポーリングする必要はありません。

WebSocket の使用例

以下のコード サンプルは、WebSocket 接続を確立し、サーバーからの各受信メッセージを記録します。

let ws = new WebSocket('wss://bundles.office.com');

ws.onmessage(message) {
    console.log(`Received: ${message}`);
}

ws.onerror(error){
    console.err(`Failed: ${error}`);
}

次の手順

関連項目