導入

  • 6 分

カスタム コネクタを使用すると、Microsoft Power Platform の事前構築済みコネクタで使用できないサービス用のコネクタを実装できます。 開発者は、カスタム コードを使用して、コネクタ アクションの入出力の高度な変換を実装できます。

基本的なカスタム コネクタ定義では、コネクタを使用する作成者が使用できるトリガーとアクションが定義されます。 作成者がアプリまたはフローからアクションを使用すると、API の操作が呼び出され、カスタム コネクタ定義で定義された要求ペイロードが渡されます。 サービスからの応答のデータは、カスタム コネクタ アクションの応答定義と一致することが予想されます。 要求および応答ペイロードに対する変換は行われません。

ポリシー テンプレート

コネクタ アクション定義では、カスタム コネクタのポリシー テンプレートを適用することにより、サービスに対する要求と応答のノーコード基本変換を実装できます。 たとえば、ポリシー テンプレートは、次の種類の変換を実行できます。

  • 要求または応答データをオブジェクトから配列に変換する。

  • 要求または応答データを配列からオブジェクトに変換する。

  • 要求のホスト URL を設定する。

  • 要求の HTTP ヘッダー値を設定する。

  • 要求または応答でプロパティ値を設定する。

  • 要求クエリ文字列のパラメーターを設定する。

複数のポリシー テンプレートを同時に使用することで、要求と応答を変換できます。 複数のテンプレートを設定するときは、順序を編集してポリシーの適用順序を制御することもできます。

開発者は、カスタム コードを実装して、ポリシー テンプレートの機能を拡張できます。 実際、カスタム コードを実装するとき、基になるサービスの操作を呼び出すタスクなど、要求と応答の変換をロジックによって十分に制御することができます。

カスタム コードの実装

カスタム コードを実装するには、抽象基本クラス ScriptBase から継承する必要がある Script という名前のクラスを作成する 必要があります。 ScriptBase クラスは、コネクタでカスタム コードを正しく実装するために Script クラスに実装する必要がある、1 つの抽象メソッド ExecuteAsync を定義します。 ExecuteAsync メソッドは、あらゆる変換と、基になるサービスの呼び出しの高度な実装となることが予想されます。

次の例は、必要な要素を実装するクラスを示しています。

public class Script : ScriptBase
{
    public override Task<HttpResponseMessage> ExecuteAsync()
    {
        // Your code here
    }
}

ExecuteAsync メソッドは、あらゆる変換と、基になるサービスの呼び出しの高度な実装を提供する必要があります。 次の例では、基になるサービスが呼び出されていないため、すべての応答が、"Hello World!" に設定された greeting プロパティを含むオブジェクトとなります。

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    // Create a new response
    var response = new HttpResponseMessage();

    // Set the content
    // Initialize a new JObject and call .ToString() to get the serialized JSON
    response.Content = CreateJsonContent(new JObject
    {
        ["greeting"] = "Hello World!",
    }.ToString());

    return response;
}

基になるサービスを呼び出すには、context オブジェクトで SendAsync メソッドを使用します。 次の ExecAsync メソッドは、変換を実行しませんが、基になるサービスに要求を転送した後、応答を変更しないまま返します。

public override async Task<HttpResponseMessage> ExecuteAsync()
{
    HttpResponseMessage response = await this.Context.SendAsync(this.Context.Request, this.CancellationToken).ConfigureAwait(continueOnCapturedContext: false);
    return response;
}

カスタム コードの最も一般的な用途は、SendAsync メソッド呼び出しの前に要求の変換を提供することです。 または、ExecuteAsync メソッドから返す前に、SendAsync メソッドから応答を変換できます。

操作のカスタム コードの作成

コネクタのカスタム コードを有効にした後、そのコードを含む有効な .cs または .csx ファイルをアップロードできます。 コネクタにスクリプト クラスを 1 つだけ指定でき、そのクラスはそのコネクタに対して設定されたアクションを処理する必要があります。 これを行うには、Context オブジェクトから OperationId をチェックし、コードを基になるサービスに変換するか転送するかを決定します。 次の例は、この手順の実例を示しています。

  if (this.Context.OperationId != "CreateProduct")
  {
     return await this.HandleForwardOperation().ConfigureAwait(false);
  }

この例では、CreateProduct 以外のアクションはすべて変換されずに転送されます。 このアプローチにより、予期しないアクションがコードを実行するよう設定されている場合、そのアクションは転送され、変換されません。

さらに、カスタム コードを特定の操作に対して実行するよう設定することにより、カスタム コードが実行される操作を制御することもできます。 既定では、コードが有効になると、すべての操作がカスタム コードを実行します。 次の図は、AddInvoice と GetInvoice のみがカスタム コードを実行することを示しています。

アクションが選択されているコードの詳細のスクリーンショット。

エクスポートされたコネクタ内でこれらの値を検索した場合、apiProperties.json ファイルに格納されていることがわかります。

"scriptOperations": [
      "AddInvoice”,
      "GetInvoice”
    ],

カスタム コードを実行する操作の選択内容が、コードに示されている条件付きチェックの期待値と一致していることを確認します。 一致していない場合、通常はカスタム コードが実行されないか、予期しないエラーが発生します。 コネクタでエラーが発生した場合、コネクタ定義をチェックします。スクリプト コードは、同じ操作が処理されることを期待します。

このモジュールの残りの部分では、カスタム コネクタを使用して実装できるカスタム コード変換を作成する方法について詳しく説明します。