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

[アーティクル]
10/16/2024

適用対象: 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 ロジックアプリ用のカスタム組み込みコネクタを作成する」を参照してください。

重要

ユーザー名やパスワードを含む接続文字列などの機密情報がある場合は必ず、利用可能な最も安全な認証フローを使用してください。たとえば Microsoft では、サポートを利用できる場合はマネージド ID を使って Azure リソースへのアクセスを認証し、必要最小限の特権を持つロールを割り当てることをお勧めします。

この機能を使用できない場合は必ず、Azure Key Vault など、アプリ設定で使用できる他の手段を使用して接続文字列をセキュリティで保護してください。これで、接続文字列やキーなど、セキュリティで保護された文字列を直接参照できます。デプロイ時に環境変数を定義できる ARM テンプレートと同様に、ロジックアプリのワークフロー定義内でアプリ設定を定義できます。その後、動的に生成されたインフラストラクチャ値 (接続エンドポイント、ストレージ文字列など) を取得できます。詳細については、「Microsoft ID プラットフォームのアプリケーションの種類」を参照してください。

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()

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

次の手順

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

シングルテナントの Azure Logic Apps で Standard ロジックアプリ用のカスタム組み込みコネクタを作成する

次の方法で共有

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

従量課金ロジックアプリ

Standard ロジックアプリ

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

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

IServiceOperationsProvider

IServiceOperationsTriggerProvider

実装するメソッド

GetService()

GetOperations()

GetBindingConnectionInformation()

InvokeOperation()

GetFunctionTriggerType()

GetFunctionTriggerDefinition()

次の手順

フィードバック

その他のリソース

次の方法で共有

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

従量課金ロジック アプリ

Standard ロジック アプリ

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

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

IServiceOperationsProvider

IServiceOperationsTriggerProvider

実装するメソッド

GetService()

GetOperations()

GetBindingConnectionInformation()

InvokeOperation()

GetFunctionTriggerType()

GetFunctionTriggerDefinition()

次の手順

フィードバック

その他のリソース

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

従量課金ロジックアプリ

Standard ロジックアプリ

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