Azure Logic Apps のカスタム コネクタ

  • [アーティクル]

適用対象: Azure Logic Apps (従量課金 + Standard)

Azure Logic Apps で事前構築済みのコネクタ操作を使用すると、コードを記述することなく、自動化された統合ワークフローをすばやく作成できます。 コネクタは、ワークフローから、他のアプリ、サービス、システム、プロトコル、プラットフォーム間でデータ、イベント、アクションに接続およびアクセスするのに役立ちます。 各コネクタから、ワークフローに追加できる操作がトリガー、アクション、またはその両方として提供されます。 これらの操作を使用すると、クラウド アプリとオンプレミス アプリの機能を拡張して、新規および既存のデータを処理できます。

Azure Logic Apps のコネクタは、"組み込み" または "マネージド" のいずれかです。 "組み込み" コネクタは、Azure Logic Apps ランタイムでネイティブに実行されます。つまり、ランタイムと同じプロセスでホストされ、高スループット、低待機時間、ローカル接続が提供されます。 "マネージド コネクタ" は、Office 365 や Salesforce などの API のプロキシまたはラッパーであり、基盤となるサービスから Azure Logic Apps に通信できるようにします。 マネージド コネクタは、Azure のコネクタ インフラストラクチャを利用し、Microsoft によってデプロイ、ホスト、実行、および管理されます。 数百のマネージド コネクタから選択して、Azure Logic Apps のワークフローで使用できます。

ワークフローで初めてコネクタ操作を使用する場合、最初に接続を作成する必要がないコネクタもありますが、多くのコネクタではこの手順が必要です。 作成する各接続は、実際には、ターゲット アプリ、サービス、システム、プロトコル、またはプラットフォームへのアクセスを提供する個別の Azure リソースです。

しかし、事前構築済みのコネクタとして利用できない REST API を呼び出したい場合もあります。 よりカスタマイズされたシナリオをサポートするために、独自の "カスタム コネクタ" を作成して、事前構築済み操作として利用できないトリガーとアクションを提供できます。

この記事では、従量課金ロジック アプリのワークフローと Standard ロジック アプリのワークフロー用のカスタム コネクタの概要について説明します。 ロジック アプリの種類ごとに、それぞれ、マルチテナント Azure とシングルテナント Azure でホストされる異なる Azure Logic Apps ランタイムが利用されます。 Azure Logic Apps のコネクタの詳細については、次のドキュメントを参照してください。

従量課金ロジック アプリ

マルチテナントの Azure Logic Apps では、Swagger ベースまたは SOAP ベースの API から、従量課金ロジック アプリのワークフローで使用するための特定の制限までカスタム コネクタを作成できます。 コネクタのドキュメントには、従量課金ロジック アプリ用のカスタム コネクタを作成する方法について、基本から応用までの完全なチュートリアルを含む、追加の概要情報が記載されています。 また、次の一覧に、従量課金ロジック アプリのカスタム コネクタに関する情報への直接のリンクを示します。

Standard ロジック アプリ

シングルテナントの Azure Logic Apps では、再設計された Azure Logic Apps ランタイムによって、Standard ロジック アプリ ワークフローが強化されています。 このランタイムは、従量課金プランロジック アプリのワークフローを強化しているマルチテナントの Azure Logic Apps ランタイムとは異なります。 シングルテナントのランタイムでは、Azure Functions 拡張性モデルを使用しており、Standard ワークフローでだれでも使用できる独自の組み込みコネクタを作成するための主要な機能が提供されています。 ほとんどの場合、組み込みのバージョンの方がパフォーマンス、機能、価格などに優れています。

シングルテナントの Azure Logic Apps が正式にリリースされたとき、新しい組み込みコネクタとして Azure Blob Storage、Azure Event Hubs、Azure Service Bus、SQL Server が追加されました。 この組み込みコネクタのリストは徐々に増え続けています。 ただし、Standard ロジック アプリのワークフローでは使用できないコネクタを必要とする場合は、Standard ワークフローのサービス プロバイダーベースの組み込みコネクタで使用されるのと同じ拡張性モデルを使用して、独自の組み込みコネクタを作成できます。

サービス プロバイダーベースの組み込みコネクタ

シングルテナントの Azure Logic Apps では、特定の属性を持つ組み込みコネクタは非公式に "サービス プロバイダー" と呼ばれます。 たとえば、これらのコネクタは Azure Functions 拡張性モデルに基づいており、Standard ロジック アプリのワークフローで使用する独自のカスタム組み込みコネクタを作成する機能を提供します。

これに対し、サービス プロバイダー以外の組み込みコネクタには、次の属性があります。

  • Azure Functions 拡張性モデルに基づいていません。

  • スケジュール、HTTP、要求、XML 操作など、Azure Logic Apps ランタイム内のジョブとして直接実装されます。

現在、サービス プロバイダー以外の組み込みコネクタや、Azure Logic Apps ランタイムで直接実行される新しいジョブの種類を作成するための機能はありません。 ただし、サービス プロバイダー インフラストラクチャを使用して、独自の組み込みコネクタを作成することはできます。

次のセクションでは、カスタム組み込みコネクタに対する拡張性モデルの動作について詳しく説明します。

組み込みコネクタ拡張性モデル

Azure Functions 拡張性モデルに基づいて、シングルテナントの Azure Logic Apps の組み込みコネクタ拡張性モデルには、Standard ワークフローでだれでも使用できる Azure Functions 拡張機能として独自の組み込みコネクタを作成、パッケージ化、登録、インストールするために使用できるサービス プロバイダー インフラストラクチャがあります。 このモデルには、カスタム組み込みコネクタで Azure Functions トリガーまたはアクションをサービス プロバイダー トリガーとして公開することをサポートするカスタム組み込みトリガー機能が含まれています。

次の図は、Azure Logic Apps デザイナーおよびランタイムで、Azure Functions ベースのトリガーがあるカスタム組み込みコネクタに対して想定されるメソッド実装を示しています。

Azure Functions ベースのサービス プロバイダー インフラストラクチャを示す概念図。

以降のセクションで、ご自分のコネクタで実装する必要があるインターフェイスの詳細について説明します。

IServiceOperationsProvider

このインターフェイスには、カスタム組み込みコネクタの操作マニフェストを提供するメソッドが含まれます。

  • 操作マニフェスト

    操作マニフェストには、カスタム組み込みコネクタに実装された操作に関するメタデータが含まれます。 Azure Logic Apps デザイナーでは、主にこのメタデータを使用して、コネクタの操作の作成と監視のエクスペリエンスを促進します。 たとえば、デザイナーでは、操作メタデータを使用して、特定の操作に必要な入力パラメーターを解釈し、操作の出力のスキーマに基づいて、出力のプロパティ トークンを生成しやすくします。

    デザイナーで、GetService() メソッドと GetOperations() メソッドを使用して、コネクタが提供し、デザイナー画面に表示する操作に対してクエリを実行します。 GetService() メソッドは、デザイナーで必要とされる接続の入力パラメーターも指定します。

    これらのメソッドとその実装の詳細については、この記事で後述する「実装するメソッド」セクションを確認してください。

  • 操作の呼び出し

    操作の呼び出しは、ワークフロー定義で指定した操作が呼び出されるように、Azure Logic Apps ランタイムによってワークフローの実行中に使用されるメソッドの実装です。

    • トリガーが Azure Functions ベースのトリガーの種類である場合、GetBindingConnectionInformation() メソッドが、必要な接続パラメーター情報を Azure Functions トリガー バインドに提供するために Azure Logic Apps のランタイムによって使用されます。

    • コネクタにアクションがある場合、InvokeOperation() メソッドが、コネクタ内で、ワークフロー実行中に実行される各アクションを呼び出すためにランタイムによって使用されます。 それ以外の場合は、このメソッドを実装する必要はありません。

これらのメソッドとその実装の詳細については、この記事で後述する「実装するメソッド」セクションを確認してください。

IServiceOperationsTriggerProvider

カスタム組み込みトリガー機能は、カスタム組み込みコネクタのサービス プロバイダー トリガーとして Azure Functions トリガーまたはアクションを追加また公開することをサポートします。 Azure Functions ベースのトリガーの種類と、Azure マネージド コネクタ トリガーと同じ Azure Functions バインドを使用するには、次のメソッドを実装して、Azure Functions の必要に応じて接続情報とトリガー バインドを提供します。

  • GetFunctionTriggerType() メソッドは、Azure Functions トリガー バインドのtype パラメーターと同じ文字列を返すために必要です。

  • GetFunctionTriggerDefinition() には既定の実装があるため、このメソッドを明示的に実装する必要はありません。 ただし、デザイナーが公開しない追加のパラメーターを指定するなど、トリガーの既定の動作を更新する場合は、このメソッドを実装し、既定の動作をオーバーライドできます。

実装するメソッド

以降のセクションで、ご自分のコネクタで実装する必要があるメソッドの詳細について説明します。 完全なサンプルについては、CosmosDbServiceOperationProvider.cs サンプルと「シングルテナントの Azure Logic Apps で Standard ロジック アプリ用のカスタム組み込みコネクタを作成する」を参照してください。

GetService()

デザイナーでは、サービスの説明、接続入力パラメーター、機能、ブランドの色、アイコンの URL など、サービスの高レベルのメタデータを取得するために、このメソッドが必要です。

public ServiceOperationApi GetService()
{
   return this.{custom-service-name-apis}.ServiceOperationServiceApi();
}

詳細については、CosmosDbServiceOperationProvider.cs サンプルを参照してください。

GetOperations()

デザイナーでは、サービスによって実装された操作を取得するために、このメソッドが必要です。 操作リストは Swagger スキーマに基づきます。 また、デザイナーでは、操作メタデータを使用して、特定の操作の入力パラメーターを解釈し、操作の出力のスキーマに基づいて、出力をプロパティ トークンとして生成します。

public IEnumerable<ServiceOperation> GetOperations(bool expandManifest)
{
   return expandManifest ? serviceOperationsList : GetApiOperations();
}

詳細については、CosmosDbServiceOperationProvider.cs サンプルを参照してください。

GetBindingConnectionInformation()

Azure Functions ベースのトリガーの種類を使用する場合、このメソッドを使用して、Azure Functions トリガー バインドに必要な接続パラメーター情報を取得します。

public string GetBindingConnectionInformation(string operationId, InsensitiveDictionary<JToken> connectionParameters)
{
   return ServiceOperationsProviderUtilities
      .GetRequiredParameterValue(
         serviceId: ServiceId,
         operationId: operationID,
         parameterName: "connectionString",
         parameters: connectionParameters)?
      .ToValue<string>();
}

詳細については、CosmosDbServiceOperationProvider.cs サンプルを参照してください。

InvokeOperation()

カスタム組み込みコネクタにトリガーしかない場合は、このメソッドを実装する必要はありません。 一方、コネクタに、実装するアクションがある場合は、コネクタ内で、ワークフロー実行中に実行されるアクションごとに呼び出される InvokeOperation() メソッドを実装する必要があります。 コネクタのアクションの必要に応じて、FTPClient、HTTPClient などの任意のクライアントを使用できます。 この例では、HTTPClient を使用します。

public Task<ServiceOperationResponse> InvokeOperation(string operationId, InsensitiveDictionary<JToken> connectionParameters, ServiceOperationRequest serviceOperationRequest)
{
   using (var client = new HttpClient())
   {
      response = client.SendAsync(httpRequestMessage).ConfigureAwait(false).ToJObject();
   }
   return new ServiceOperationResponse(body: response);
}

詳細については、CosmosDbServiceOperationProvider.cs サンプルを参照してください。

GetFunctionTriggerType()

コネクタでトリガーとして Azure Functions ベースのトリガーを使用するには、Azure Functions トリガー バインドの型パラメーターと同じ文字列を返す必要があります。

次の例では、そのまま使える組み込みの Azure Cosmos DB トリガーの文字列である "type": "cosmosDBTrigger" が返ります。

public string GetFunctionTriggerType()
{
   return "CosmosDBTrigger";
}

詳細については、CosmosDbServiceOperationProvider.cs サンプルを参照してください。

GetFunctionTriggerDefinition()

このメソッドには既定の実装があるため、このメソッドを明示的に実装する必要はありません。 ただし、デザイナーで公開されない追加のパラメーターを指定するなど、トリガーの既定の動作を更新する場合は、このメソッドを実装し、既定の動作をオーバーライドできます。

次の手順

実装手順を開始する準備ができたら、次の記事に進んでください。