次の方法で共有

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

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

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

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

    サンプル 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 要求が失敗した場合でも、コパイロットが運用を継続するシナリオで役立ちます。

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

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

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

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

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

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

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

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