HTTP 要求を行う

  • [アーティクル]

重要

Power Virtual Agents 機能は、生成 AI への多大な投資と Microsoft Copilot 全体の統合の強化により、現在 Microsoft Copilot Studio の一部となっています。

ドキュメントやトレーニング コンテンツが更新される間、一部の記事やスクリーンショットで Power Virtual Agents が参照される場合があります。

Copilot Studioでは、HTTP 要求 ノードを使用して、外部 REST API を呼び出すことで、コパイロットの機能を拡張できます。 これは、外部システムからデータを取得する必要がある場合や、そのシステム上のデータを操作する必要がある場合に役立ちます。

前提条件

HTTP 要求ノードを使用する

  1. ノードの追加 (+) を選択し、詳細 サブメニューを開き、HTTP 要求の送信 を選択します。

    詳細メニューの HTTP 要求送信オプションのスクリーンショット。

  2. URL ボックスで、呼び出す API エンドポイントの URL を入力します。

  3. ドロップダウンから適切な要求の 方法 を選択します。 GET、POST、PATCH、PUT、DELETE のメソッドがサポートされています。

    完成した API URL とメソッドのドロップダウンのスクリーンショット

  4. ノードの ヘッダーと本文 で、編集 ボタンをクリックします。 これにより、HTTP 要求のプロパティ ペインが開きます。

  5. オプションで 1 つ以上のヘッダーを HTTP 要求に追加できます。 追加 ボタンをクリックして、各ヘッダーのキーと値を追加します。

    HTTP ノードのヘッダーのキーと値のペアのリストのスクリーンショット。

  6. 既定では、HTTP 要求の本文ではコンテンツは送信されませんが、本文で送信するコンテンツを指定します。

  7. ノードで、使用可能なオプションから 応答データ タイプ を選択します。

    JSON 応答の例 (通常、呼び出す API のドキュメントに記載されています) を提供すると、厳密に型指定された Power FX 変数が生成され、Power FX エディターのインテリセンス サポートを使用して、作成キャンバスの他の場所で使用することができます。 これを行うには、サンプル データから を選択し、 サンプル JSON からスキーマを取得 をクリックし、サンプル応答を表示されたエディターで、 確認 を選択します。

    サンプル JSON エディターからのスキーマの取得のスクリーンショット。

  8. 名前を付けて応答を保存 で、HTTP 要求の応答を保存する場所を選択し、新しい変数を作成するか、既存の変数を選択します。

HTTP 要求本文でコンテンツを送信する

  1. ノードの ヘッダーと本文 で、編集 ボタンをクリックします。 これにより、HTTP 要求のプロパティ ペインが開きます。

  2. 本文 で、適切な コンテンツ タイプ を選択します。 既定では、これは コンテンツなしに設定されており、リクエスト本文内にコンテンツが存在すべきではありません。これは、GET リクエストで最も一般的に使用されます。 本文にコンテンツを追加するには、利用可能なオプションのいずれかを選択します。

    本文コンテンツ オプションのドロップダウンのスクリーンショット

    • JSON コンテンツ: JSON コンテンツを使用すると、要求本文に JSON オブジェクトを指定できます。 これは、POST または PUT リクエストを行うときによく使用されます。 このオプションを選択すると、JSON コンテンツを入力できるエディターが表示されます。

      Power FX を使用して JSONコ ンテンツを指定することもでき、動的な値や参照変数を含めることができます。 これを行うには、JSON の編集 ボタンを選択し、式 を選択して、Power FX オブジェクト (既存の任意のオブジェクト) を入力します。すでに入力されている JSONはPower FX オブジェクトに変換されます。これは、HTTP 要求が行われるときに JSON に変換されます。

      本文 コンテンツ タイプ に選択された JSON コンテンツのスクリーンショット。

    • Raw コンテンツ: Raw コンテンツを使用すると、データの文字列をリクエスト本文に挿入できます。この文字列は、指定した任意の コンテンツ タイプ にすることができます。 以下の例に示す文字列コンテンツなど、生のコンテンツは Power FX 式を使用して入力されます。

      本文 コンテンツ タイプ に選択された RAW コンテンツのスクリーンショット。

エラー処理とタイムアウト

HTTP 要求 ノードには、HTTP 要求が失敗したりエラーを返したりする状況を処理するための複数のオプションがあります。

既定では、この機能は「エラーを発生させます」となります。 つまり、HTTP 要求がエラーを返した場合、または実行に失敗した場合、コパイロットは運用を停止し、 エラー システム トピックをトリガーして、エラー メッセージを表示します。

ただし、エラー システム トピック をトリガーしないようにエラー処理を設定し、代わりに HTTP ステータス コードとエラー応答本文を指定した変数に代入することができます。これにより、必要に応じてこれらの変数を問い合わせることができ、トピック が実行を継続できるようになります。 これは、特定の HTTP 要求が失敗した場合でも、コパイロットが運用を継続するシナリオで役立ちます。

エラー処理動作を構成します。

  1. ノードの ヘッダーと本文 で、編集 ボタンをクリックします。 これにより、HTTP 要求のプロパティ ペインが開きます。

  2. エラー処理 ドロップダウンから希望の動作を選択します。

  3. エラー時に続行 を選択した場合は、状態コード と エラー応答本文 の変数を設定します。新しい変数を作成するか、ピッカーから既存の変数を選択します。

    状態コードとエラー応答本文に変数を指定して、エラー時に続行するように構成されたエラー処理のスクリーンショット。

このコード サンプルでは、HTTP 要求が失敗した場合、コパイロットは HTTP 状態コードを Topic.StatusCode 変数に格納し、応答本文を Topic.ErrorResponse 変数に格納します。 その後、コパイロットはトピックの次のステップに進みます。

エラー応答 変数のタイプは 任意になります。 値の解析ノード を使用して、これを Power Fx レコードに変換できます。

プロパティ ペインには、ミリ秒単位の値を受け入れる リクエスト タイムアウト プロパティも含まれています。 既定値は 30 秒ですが、必要に応じてこの値を変更できます。