次の方法で共有

HTTP 要求を行う

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 ノードのヘッダーのキーと値のペアのリストのスクリーンショット。

    headers セクションを使用して、認証トークン、コンテンツ タイプ、または呼び出す API に必要なその他のヘッダーを渡すことができます。 たとえば、要求を認証する Authorization: Bearer <your_token> などのヘッダーを追加できます。

  6. デフォルトでは、HTTP リクエストの本文にコンテンツは送信されませんが、本文にコンテンツを指定することができます。

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

    呼び出している API のドキュメントで通常見つけることができるサンプル JSON 応答を提供できます。 これにより、Power Fx 変数が生成され、Power Fx エディターのインテリセンス サポートを使用して、作成キャンバスの他の場所で使用できるようになります。 サンプル データから を選択し、サンプル JSON からスキーマを取得するを選択します。 サンプル応答をエディターに貼り付けて、確認を選択します。

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

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

  1. ノードの ヘッダーと本文 の下にある 編集 ボタンを選択すると、HTTP 要求のプロパティ パネルが開きます。

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

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

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

      また、Power Fx を使用して JSON コンテンツを指定することもでき、動的な値や参照変数を含めることができます。 EditJSON ボタンを選択し、Formula を選択し、Power Fx オブジェクトを入力します (入力された既存の JSON は Power Fx オブジェクトに変換されます)。

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

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

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

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

HTTP リクエスト ノードには、HTTP リクエストが失敗したり、エラーが返される可能性がある状況を処理するための複数のオプションがあります。

既定では、この機能はエラーを発生させます。 つまり、HTTP 要求がエラーを返すか、実行に失敗すると、エージェントは操作を停止し、エラー発生時 システム トピックをトリガーして、エラー メッセージを表示します。

ただし、エラー処理を構成して エラー発生時 システム トピックをトリガーしないようにすることができます。 代わりに、HTTP 状態コードとエラー応答本文を、指定した変数に格納できます。 必要に応じてこれらの変数を調べることができ、トピックは実行を続行できます。 この構成は、特定の HTTP 要求が失敗した場合でも、エージェントが操作を続行するシナリオで役立ちます。

HTTP 要求 ノードのエラー処理動作を構成するには、次のようにします:

  1. ヘッダーと本文で、編集を選択します。 HTTP 要求プロパティ パネルが表示されます。

  2. エラー処理で、目的の動作を選択します: エラーを発生させるまたは エラー発生時に続行する。

  3. エラー発生時に続行するを選択した場合は、状態コードとエラー応答本文の変数を構成します。

    'HTTP 要求' ノードの 'HTTP 要求のプロパティ' パネルのスクリーンショット。エラー時に続行するためのエラー処理構成が表示されています。状態コードとエラー応答本文の変数が選択されます。

この例では、HTTP 要求が失敗した場合、エージェントは HTTP ステータス コードを Topic.StatusCode 変数に格納し、応答本文を Topic.ErrorResponse 変数に格納します。 エージェントは、トピックの次のステップに進みます。

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

HTTP 要求プロパティ パネルでは、要求タイムアウト プロパティをミリ秒単位で設定することもできます。 既定値は 30 秒です。