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

[アーティクル]
08/06/2024

適用対象: Azure Logic Apps (Standard)

Standard ロジックアプリワークフローで使用できないコネクタが必要な場合は、シングルテナント Azure Logic Apps の Standard ワークフローで使用できるサービスプロバイダーベースの組み込みコネクタで使用されるものと同じ拡張性モデルを使用して、独自の組み込みコネクタを作成できます。この拡張性モデルは、Azure Functions 機能拡張モデルに基づいています。

この記事では、1 つの Azure Functions ベースのトリガーとアクションがないカスタム組み込み Azure Cosmos DB コネクタのサンプルを作成する方法について説明します。トリガーは、新しいドキュメントが Azure Cosmos DB のリースコレクションまたはコンテナーに追加された後、Azure Cosmos DB ドキュメントとして入力ペイロードを使用するワークフローが実行されたときに発生します。

操作	操作の詳細	説明
トリガー	ドキュメントを受け取ったとき	このトリガー操作は、指定した Azure Cosmos DB データベースとコレクションで挿入操作が行われるときに実行されます。
アクション	なし	このコネクタでは、アクション操作は定義されません。

このサンプルコネクタでは、Azure Functions 用の Azure Cosmos DB トリガーと同じ機能を使用します。これは、Azure Functions のトリガーとバインドに基づいています。完全なサンプルについては、サンプルカスタム組み込み Azure Cosmos DB コネクタ - Azure Logic Apps コネクタ拡張機能に関するページを参照してください。

詳細については、次のドキュメントを確認してください。

前提条件

Azure アカウントとサブスクリプション。サブスクリプションをお持ちでない場合には、無料の Azure アカウントにサインアップしてください。
シングルテナント Azure Logic Apps、Standard ロジックアプリワークフロー、コネクタ、シングルテナントベースのワークフローを作成するために Visual Studio Code を使用する方法に関する基本的な知識。詳細については、次のドキュメントを確認してください。
- Azure Logic Apps でのシングルテナントとマルチテナント
- シングルテナント Azure Logic Apps (Standard) を使用して統合ワークフローを作成する - Azure portal
Azure Logic Apps (Standard) 拡張機能とその他前提条件がインストールされた Visual Studio Code。インストールには、Microsoft.Azure.Workflows.WebJobs.Extension の NuGet パッケージが既に含まれている必要があります。

注意

この作成機能は現在 Visual Studio Code でのみ使用できます。
Azure Cosmos DB アカウント、データベース、およびコンテナーまたはコレクション。詳細については、「クイックスタート: Azure portal を使用して Azure Cosmos DB のアカウント、データベース、コンテナー、および項目を作成する」を確認してください。

手順の概要

次のアウトラインでは、コネクタの例をビルドする手順の概要について説明します。

クラスライブラリプロジェクトを作成します。
プロジェクトで、Microsoft.Azure.Workflows.WebJobs.Extension NuGet パッケージを NuGet 参照として追加します。
NuGet パッケージを使用して、IServiceOperationsProvider および IServiceOperationsTriggerProvider という名前のインターフェイスのメソッドを実装することで、組み込みコネクタの操作を提供します。
カスタムの組み込みコネクタを Azure Functions ランタイム拡張機能に登録します。
使用できるようコネクタをインストールします。

クラスライブラリプロジェクトを作成する

Visual Studio Code で、.NET Core 3.1 クラスライブラリプロジェクトを作成します。
プロジェクトで、Microsoft.Azure.Workflows.WebJobs.Extension という名前の NuGet パッケージを NuGet 参照として追加します。

サービスプロバイダーインターフェイスを実装する

サンプルの組み込みコネクタの操作を提供するには、Microsoft.Azure.Workflows.WebJobs.Extension NuGet パッケージで、次のインターフェイスのメソッドを実装します。次の図は、Azure Logic Apps デザイナーとランタイムで、Azure Functions ベースのトリガーを持つカスタム組み込みコネクタに対して想定されるメソッド実装とのインターフェイスを示しています。

サンプル Azure Cosmos DB カスタム組み込みコネクタのメソッド実装を示す概念クラス図。

IServiceOperationsProvider

このインターフェイスには、操作マニフェストを提供し、カスタム組み込みコネクタでサービスプロバイダーの特定のタスクまたは実際のビジネスロジックを実行する次のメソッドが含まれています。詳細については、「IServiceOperationsProvider」を参照してください。

GetService()

Azure Logic Apps のデザイナーでは、GetService() メソッドを使用して、サービスの説明、デザイナーに必要な接続入力パラメーター、機能、ブランドの色、アイコン URL など、カスタムサービスの高度なメタデータを取得する必要があります。
GetOperations()

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

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

コネクタにアクションがある場合、Azure Logic Apps のランタイムでは、ワークフロー実行中に実行されるコネクタ内の各アクションを InvokeOperation() メソッドで呼び出す必要があります。コネクタにアクションがない場合は、InvokeOperation() メソッドを実装する必要はありません。

この例では、Azure Cosmos DB カスタム組み込みコネクタにアクションはありません。ただし、このメソッドは完全性のためにこの例に含まれています。

これらのメソッドとその実装の詳細については、この記事の後半でこれらのメソッドを確認してください。

IServiceOperationsTriggerProvider

カスタム組み込みコネクタでは、Azure Functions トリガーまたはアクションをサービスプロバイダートリガーとして追加または公開できます。 Azure Functions ベースのトリガーの種類と、Azure マネージドコネクタトリガーと同じ Azure Functions バインドを使用するには、次のメソッドを実装して、Azure Functions で必要に応じて接続情報とトリガーバインドを提供します。詳細については、「IServiceOperationsTriggerProvider」を確認してください。

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

実装するメソッド

次のセクションでは、コネクタの例で実装するメソッドについて説明します。完全なサンプルについては、サンプル CosmosDbServiceOperationProvider.cs を確認してください。

重要

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

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

GetService()

デザイナーでは、サービスの概要説明を取得するには、次のメソッドが必要です。

public ServiceOperationApi GetService()
{
   return this.CosmosDBApis.ServiceOperationServiceApi();
}

GetOperations()

デザイナーでは、サービスによって実装される操作を取得するには、次のメソッドが必要です。この操作リストは Swagger スキーマに基づいています。

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

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

InvokeOperation()

Azure Cosmos DB カスタム組み込みコネクタの例にはアクションはありませんが、完全性のために次のメソッドが含まれています。

public Task<ServiceOperationResponse> InvokeOperation(string operationId, InsensitiveDictionary<JToken> connectionParameters, ServiceOperationRequest serviceOperationRequest)
{
   throw new NotImplementedException();
}

GetFunctionTriggerType()

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

次の例では、既定の組み込み Azure Cosmos DB トリガー "type": "cosmosDBTrigger" の文字列を返します。

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

GetFunctionTriggerDefinition()

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

コネクタを登録する

Azure Functions ランタイム開始プロセス中にカスタムの組み込みコネクタ拡張機能を読み込むには、Azure Functions 拡張機能の登録をスタートアップジョブとして追加し、コネクタをサービスプロバイダーの一覧にサービスプロバイダーとして登録する必要があります。組み込みトリガーが入力として必要とするデータの種類に基づいて、必要に応じてコンバーターを追加します。次の例では、Azure Cosmos DB ドキュメントの Document データ型を JObject 配列に変換します。

次のセクションでは、カスタム組み込みコネクタを Azure Functions 拡張機能として登録する方法について説明します。

スタートアップジョブを作成する

[assembly:WebJobsStartup] という名前のアセンブリ属性を使用してスタートアップクラスを作成します。

IWebJobsStartup インターフェイスを実装します。 Configure() メソッドで、拡張機能を登録し、サービスプロバイダーを挿入します。

たとえば、次のコードスニペットは、サンプルカスタム組み込み Azure Cosmos DB コネクタのスタートアップクラスの実装を示しています。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Hosting;
using Microsoft.Extensions.DependencyInjection.Extensions;

[assembly: Microsoft.Azure.WebJobs.Hosting.WebJobsStartup(typeof(ServiceProviders.CosmosDb.Extensions.CosmosDbTriggerStartup))]

namespace ServiceProviders.CosmosDb.Extensions
{
   public class CosmosDbServiceProviderStartup : IWebJobsStartup
   {
      // Initialize the workflow service.
      public void Configure(IWebJobsBuilder builder)
      {
            // Register the extension.
            builder.AddExtension<CosmosDbServiceProvider>)();

            // Use dependency injection (DI) for the trigger service operation provider.
            builder.Services.TryAddSingleton<CosmosDbTriggerServiceOperationsProvider>();
      }
   }
}

詳細については、サービスの登録 - .NET Azure Functions での依存関係の挿入の使用に関するページを確認してください。

サービスプロバイダーを登録する

次に、サービスプロバイダーの実装を Azure Logic Apps エンジンに Azure Functions 拡張機能として登録します。この例では、Azure Functions 用の組み込みの Azure Cosmos DB トリガーを新しいトリガーとして使用します。この例では、新しい Azure Cosmos DB サービスプロバイダーを、既に Azure Logic Apps 拡張機能の一部になっているサービスプロバイダーの既存の一覧に登録します。詳細については、「Azure Functions バインド拡張機能を登録する」を確認してください。

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs.Description;
using Microsoft.Azure.WebJobs.Host.Config;
using Microsoft.Azure.Workflows.ServiceProviders.Abstractions;
using Microsoft.WindowsAzure.ResourceStack.Common.Extensions;
using Microsoft.WindowsAzure.ResourceStack.Common.Json;
using Microsoft.WindowsAzure.ResourceStack.Common.Storage.Cosmos;
using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;

namespace ServiceProviders.CosmosDb.Extensions
{
   [Extension("CosmosDbServiceProvider", configurationSection: "CosmosDbServiceProvider")]
   public class CosmosDbServiceProvider : IExtensionConfigProvider
   {
      // Initialize a new instance for the CosmosDbServiceProvider class.
      public CosmosDbServiceProvider(ServiceOperationsProvider serviceOperationsProvider, CosmosDbTriggerServiceOperationsProvider operationsProvider)
      {
         serviceOperationsProvider.RegisterService(serviceName: CosmosDBServiceOperationsProvider.ServiceName, serviceOperationsProviderId: CosmosDBServiceOperationsProvider.ServiceId, serviceOperationsProviderInstance: operationsProvider);
      }

      // Convert the Azure Cosmos DB Document array to a generic JObject array.
      public static JObject[] ConvertDocumentToJObject(IReadOnlyList<Document> data)
      {
         List<JObject> jobjects = new List<JObject>();

         foreach(var doc in data)
         {
            jobjects.Add((JObject)doc.ToJToken());
         }

         return jobjects.ToArray();
      }

      // In the Initialize method, you can add any custom implementation.
      public void Initialize(ExtensionConfigContext context)
      {
         // Convert the Azure Cosmos DB Document list to a JObject array.
         context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);
      }
   }
}

コンバーターを追加する

Azure Logic Apps には、JObject 配列を使用して Azure Functions 組み込みトリガーを処理する一般的な方法があります。ただし、Azure Cosmos DB ドキュメントの読み取り専用リストを JObject 配列に変換する場合は、コンバーターを追加できます。コンバーターの準備ができたら、この例で前述したように、コンバーターを ExtensionConfigContext の一部として登録します。

// Convert the Azure Cosmos DB  document list to a JObject array.
context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);

実装されたクラスのクラスライブラリ図

完了したら、Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll 拡張バンドル内のすべてのクラスの実装を示す次のクラス図を確認します。

CosmosDbServiceOperationsProvider
CosmosDbServiceProvider
CosmosDbServiceProviderStartup

完全なクラス実装を示す概念コードマップ図。

コネクタをインストールする

前のセクションの NuGet 参照を追加するには、Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll という名前の拡張機能バンドルで extensions.json ファイルを更新します。詳細については、Azure/logicapps-connector-extensions リポジトリに移動し、add-extension.ps1 という名前の PowerShell スクリプトを確認してください。

カスタム組み込みコネクタを含むように拡張機能バンドルを更新します。

Visual Studio Code 拡張機能の Azure Logic Apps (Standard) がインストールされている Visual Studio Code で、ロジックアプリプロジェクトを作成し、次の PowerShell コマンドを使用して拡張機能パッケージをインストールします。

PowerShell

dotnet add package "Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB" --version 1.0.0  --source $extensionPath

または、PowerShell プロンプトを使用してロジックアプリプロジェクトのディレクトリから、add-extension.ps1 という名前の PowerShell スクリプトを実行します。

.\add-extension.ps1 {Cosmos-DB-output-bin-NuGet-folder-path} CosmosDB

Bash

代わりに Bash を使用するには、ロジックアプリプロジェクトのディレクトリから、次のコマンドを使用して PowerShell スクリプトを実行します。

powershell -file add-extension.ps1 {Cosmos-DB-output-bin-NuGet-folder-path} CosmosDB

カスタム組み込みコネクタの拡張機能が正常にインストールされた場合は、次の例のような出力が表示されます。

C:\Users\{your-user-name}\Desktop\demoproj\cdbproj>powershell - file C:\myrepo\github\logicapps-connector-extensions\src\Common\tools\add-extension.ps1 C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\CosmosDB

Nuget extension path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\
Extension dll path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\netcoreapp3.1\Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll
Extension bundle module path is C:\Users\{your-user-name}\.azure-functions-core-tools\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle.Workflows1.1.9
EXTENSION PATH is C:\Users\{your-user-name}\.azure-functions-core-tools\Functions\ExtensionBundles\Microsoft.Azure.Functions.ExtensionBundle.Workflows\1.1.9\bin\extensions.json and dll Path is C:\myrepo\github\logicapps-connector-extensions\src\CosmosDB\bin\Debug\netcoreapp3.1\Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll
SUCCESS: The process "func.exe" with PID 26692 has been terminated.
   Determining projects to restore...
   Writing C:\Users\{your-user-name}\AppData\Local\Temp\tmpD343.tmp`<br>
info : Adding PackageReference for package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' into project 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
info : Restoring packages for C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj...
info : Package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' is compatible with all the specified frameworks in project 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
info : PackageReference for package 'Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB' version '1.0.0' updated in file 'C:\Users\{your-user-name}\Desktop\demoproj\cdbproj.csproj'.
info : Committing restore...
info : Generating MSBuild file C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\cdbproj.csproj.nuget.g.props.
info : Generating MSBuild file C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\cdbproj.csproj.nuget.g.targets.
info : Writing assets file to disk. Path: C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\obj\project.assets.json.
log : Restored C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\cdbproj.csproj (in 1.5 sec).
Extension CosmosDB is successfully added.

C:\Users\{your-user-name}\Desktop\demoproj\cdbproj\>

func.exe プロセスが実行されている場合は、次の手順に進む前に、そのプロセスを閉じるか終了してください。

コネクタをテストする

Visual Studio Code で、Standard ロジックアプリと空のワークフローをデザイナーで開きます。
デザイナー画面で、[操作の選択] を選択してコネクタ操作ピッカーを開きます。
操作検索ボックスで、[組み込み] を選択します。検索ボックスに「cosmos db」と入力します。

操作ピッカーには、カスタム組み込みコネクタとトリガーが表示されます。次に例を示します。
[トリガー] の一覧から、カスタムの組み込みトリガーを選択してワークフローを開始します。

接続ペインで、次のプロパティ値を指定して接続を作成します。次に例を示します。

プロパティ	必要	値	説明
接続名	はい	<Azure-Cosmos-DB-connection-name>	作成する Azure Cosmos DB 接続の名前
接続文字列	はい	<Azure Cosmos DB-DB-connection-string>	新しく受信した各ドキュメントを追加する Azure Cosmos DB データベースコレクションまたはリースコレクションの接続文字列。

コネクタを初めて使用するときの接続ウィンドウを示すスクリーンショット。

完了したら [作成] を選択します。

トリガーのプロパティペインで、トリガーに次のプロパティ値を指定します。次に例を示します。

プロパティ	必要	値	説明
データベース名	はい	<Azure-Cosmos-DB-database-name>	使用する Azure Cosmos DB データベースの名前
[コレクション名]	Yes	<Azure-Cosmos-DB-collection-name>	新しく受信した各ドキュメントを追加する Azure Cosmos DB コレクションの名前。

トリガーのプロパティウィンドウを示すスクリーンショット。

この例では、コードビューのワークフロー定義 (workflow.json ファイル内) には、次のサンプルのような triggers JSON オブジェクトが含まれています。

{
   "definition": {
      "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#",
      "actions": {},
      "contentVersion": "1.0.0.0",
      "outputs": {},
      "triggers": {
         "When_a_document_is_received": {
            "inputs":{
               "parameters": {
                  "collectionName": "States",
                  "databaseName": "SampleCosmosDB"
               },
               "serviceProviderConfiguration": {
                  "connectionName": "cosmosDb",
                  "operationId": "whenADocumentIsReceived",
                  "serviceProviderId": "/serviceProviders/CosmosDb"
               },
               "splitOn": "@triggerOutputs()?['body']",
               "type": "ServiceProvider"
            }
         }
      }
   },
   "kind": "Stateful"
}

接続定義 (connections.json ファイル内) には、次のサンプルのような serviceProviderConnections JSON オブジェクトが含まれています。

{
   "serviceProviderConnections": {
      "cosmosDb": {
         "parameterValues": {
            "connectionString": "@appsetting('cosmosDb_connectionString')"
         },
         "serviceProvider": {
            "id": "/serviceProviders/CosmosDb"
         },
         "displayName": "myCosmosDbConnection"
      }
   },
   "managedApiConnections": {}
}

Visual Studio Code で、[実行] メニューの [デバッグの開始] を選択します。 (F5 キーを押す)
ワークフローをトリガーするには、Azure portal で Azure Cosmos DB アカウントを開きます。アカウントメニューの [Data Explorer] を選択します。トリガーで指定したデータベースとコレクションを参照します。コレクションに項目を追加します。

次の方法で共有

シングルテナント 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 ロジックアプリ用のカスタム組み込みコネクタを作成する

クラスライブラリプロジェクトを作成する

サービスプロバイダーインターフェイスを実装する

スタートアップジョブを作成する

サービスプロバイダーを登録する

実装されたクラスのクラスライブラリ図