Office スクリプトでの外部 API 呼び出しのサポート

  • [アーティクル]

スクリプトでは、外部サービスへの呼び出しがサポートされます。 これらのサービスを使用して、ブックにデータやその他の情報を提供します。

注意

外部呼び出しにより、機密データが望ましくないエンドポイントに公開される可能性があります。 管理者は、そのような呼び出しに対して Information Rights Management (IRM) またはファイアウォール保護を確立できます。

重要

外部 API の呼び出しは、 通常の状況では Power Automate ではなく、Excel アプリケーションを介してのみ行うことができます。 外部呼び出しは、SharePoint サイトに格納されているスクリプトではサポートされていません。

外部呼び出し用にスクリプトを構成する

外部呼び出しは 非同期 であり、スクリプトが として asyncマークされている必要があります。 次に async 示すように、プレフィックスを main 関数に追加し、 を Promise返します。

async function main(workbook: ExcelScript.Workbook) : Promise <void>

注:

他の情報を返すスクリプトは、その型の を Promise 返すことができます。 たとえば、スクリプトがオブジェクトを返す Employee 必要がある場合、戻り値のシグネチャは : Promise <Employee>

そのサービスを呼び出すには、外部サービスのインターフェイスを学習する必要があります。 または REST API を使用fetchしている場合は、返されるデータの JSON 構造を決定する必要があります。 スクリプトへの入力とスクリプトからの出力の両方で、必要な JSON 構造に一致するように を作成 interface することを検討してください。 これにより、スクリプトの型安全性が向上します。 この例については、「 Office スクリプトからのフェッチの使用」を参照してください。

Office スクリプトからの外部呼び出しに関する制限事項

  • OAuth2 タイプの認証フローをサインインまたは使用する方法はありません。 すべてのキーと資格情報をハードコーディングする (または別のソースから読み取る) 必要があります。
  • API の資格情報とキーを格納するインフラストラクチャはありません。 これはユーザーが管理する必要があります。
  • ドキュメント Cookie、、 localStorageおよび sessionStorage オブジェクトはサポートされていません。
  • 外部呼び出しにより、機密データが望ましくないエンドポイントに公開されたり、外部データが内部ブックに取り込まれる可能性があります。 管理者は、このような呼び出しに対してファイアウォール保護を確立できます。 外部呼び出しに依存する前に、ローカル ポリシーを使用してチェックしてください。
  • 依存関係を取得する前に、データ スループットの量を必ずチェックしてください。 たとえば、外部データセット全体をプルダウンするのが最適なオプションではない場合があり、代わりに改ページ処理を使用してチャンク内のデータを取得する必要があります。

を使用して情報を取得する fetch

フェッチ API は、外部サービスから情報を取得します。 これは async API であるため、スクリプトの署名を調整する main 必要があります。 関数 asyncを作成しますmain。 呼び出しと取得も必ずawaitfetch行jsonう必要があります。 これにより、スクリプトが終了する前にこれらの操作が完了します。

によって fetch 取得される JSON データは、スクリプトで定義されているインターフェイスと一致する必要があります。 Office スクリプトでは型がサポートされていないため、返される値を特定の型にany割り当てる必要があります。 返されるプロパティの名前と型を確認するには、サービスのドキュメントを参照する必要があります。 次に、一致するインターフェイスまたはインターフェイスをスクリプトに追加します。

次のスクリプトでは、 を使用 fetch して、指定された URL 内のテスト サーバーから JSON データを取得します。 一致する JSONData 型としてデータを格納するインターフェイスに注意してください。

async function main(workbook: ExcelScript.Workbook) {
  // Retrieve sample JSON data from a test server.
  let fetchResult = await fetch('https://jsonplaceholder.typicode.com/todos/1');

  // Convert the returned data to the expected JSON structure.
  let json : JSONData = await fetchResult.json();

  // Display the content in a readable format.
  console.log(JSON.stringify(json));
}

/**
 * An interface that matches the returned JSON structure.
 * The property names match exactly.
 */
interface JSONData {
  userId: number;
  id: number;
  title: string;
  completed: boolean;
}

その他の fetch サンプル

Information Rights Management (IRM) を使用して外部呼び出しを制限する

IRM 設定をブックに適用して、スクリプトによって外部呼び出しが行われるのを防ぐことができます。 この動作を回避するには、 COPY/EXTRACT ポリシー を無効にします。

Power Automate からの外部呼び出し

スクリプトが Power Automate を介して実行されると、外部 API 呼び出しは失敗します。 fetch呼び出しでは、"ランタイム エラー: 行 X: フェッチが定義されていません" というエラー メッセージが表示されます。 このような参照のスクリプトをフローに組み込む前に、必ずスクリプトをチェックしてください。

Azure AD またはその他の同等のアクション で HTTP を使用して、データを外部サービスからプルまたはプッシュする必要があります。

警告

Power Automate Excel Online コネクタ を介して行われた外部呼び出しは、既存のデータ損失防止ポリシーを維持するために失敗します。 ただし、Power Automate を介して実行されるスクリプトは、organizationの外部、およびorganizationのファイアウォールの外部で実行されます。 この外部環境の悪意のあるユーザーからの保護を強化するために、管理者は Office スクリプトの使用を制御できます。 管理者は、Power Automate で Excel Online コネクタを無効にするか、Office スクリプト管理者コントロールを使用して Office スクリプト for Excel をオフにすることができます。

関連項目