次の方法で共有

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>

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

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

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

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

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

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

注:

クロスオリジン リソース共有 (CORS) ポリシーで fetch を使用して外部リソースを呼び出す場合は、その外部リソースの Access-Control-Allow-Origin ヘッダーで * ディレクティブが使用されていることを確認します。 Access-Control-Allow-Origin ヘッダーが特定の <origin> ディレクティブを使用している場合、Office スクリプトからのfetch呼び出しが失敗する可能性があります。 Office Scripts ランタイムの配信元は、予告なく変更される場合があります。

次のスクリプトでは、 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 をオフにすることができます。

関連項目