為單一租用戶 Azure Logic Apps 的標準邏輯應用程式建立自訂內建連接器

適用於：Azure Logic Apps (標準)

如果您需要標準邏輯應用程式工作流程中無法使用的連接器，您可以使用單一租用戶 Azure Logic Apps 標準工作流程中，服務提供者型內建連接器使用的相同擴充性模型，來建立自己的內建連接器。 此擴充性模型以 Azure Functions 擴充性模型為基礎。

本文顯示如何建立自訂內建 Azure Cosmos DB 連接器範例，其具有單一 Azure Functions 型觸發程序，且沒有任何動作。 該觸發程序會在將新文件新增至 Azure Cosmos DB 中的租用集合或容器時引發，然後執行使用輸入承載作為 Azure Cosmos DB 文件的工作流程。

作業	作業詳細資料	描述
觸發程序	收到文件時	當指定的 Azure Cosmos DB 資料庫與集合中發生插入作業時，此觸發程序作業就會執行。
動作	無	此連接器不會定義任何動作作業。

此連接器範例使用的功能與適用於 Azure Functions 的 Azure Cosmos DB 觸發程序相同，都是以 Azure Functions 觸發程序和繫結為基礎。 如需完整的範例，請檢閱自訂內建 Azure Cosmos DB 連接器範例 - Azure Logic Apps 連接器延伸模組。

如需詳細資訊，請參閱下列文件：

• 標準邏輯應用程式的自訂連接器
• 服務提供者型內建連接器
• 單一租用戶 Azure Logic Apps

必要條件

• Azure 帳戶和訂用帳戶。 如果您沒有訂用帳戶，請註冊一個免費的 Azure 帳戶。

• 關於單一租用戶 Azure Logic Apps、標準邏輯應用程式工作流程、連接器，以及如何使用 Visual Studio Code 來建立單一租用戶型工作流程的基本知識。 如需詳細資訊，請參閱下列文件：

  • Azure Logic Apps 中的單一租使用者與多租使用者

  • 使用單一租用戶 Azure Logic Apps (標準) 建立整合工作流程 - Azure 入口網站

• 已安裝 Azure Logic Apps (標準) 延伸模組和其他必要條件的 Visual Studio Code。 您的安裝應該已經包含 Microsoft.Azure.Workflows.WebJobs.Extension 的 NuGet 套件。

  注意

  目前只有 Visual Studio Code 中提供這個製作功能。

• Azure Cosmos DB 帳戶、資料庫，以及容器或集合。 如需詳細資訊，請檢閱快速入門：從 Azure 入口網站建立 Azure Cosmos DB 帳戶、資料庫、容器與項目。

高階步驟

下列大綱說明建置連接器範例的大致步驟：

1. 建立類別庫 (Class Library) 專案。

2. 在您的專案中，將 Microsoft.Azure.Workflows.WebJobs.Extension NuGet 套件新增為 NuGet 參考。

3. 使用 NuGet 套件為內建連接器提供作業，實作 IServiceOperationsProvider 和 IServiceOperationsTriggerProvider 介面的方法。

4. 使用 Azure Functions 執行階段延伸模組註冊您的自訂內建連接器。

5. 安裝要使用的連接器。

建立您的類別庫專案

1. 在 Visual Studio Code 中，建立 .NET Core 3.1 類別庫專案。

2. 在您的專案中，將名為 Microsoft.Azure.Workflows.WebJobs.Extension 的 NuGet 套件新增為 NuGet 參考。

實作服務提供者介面

若要為內建連接器範例提供作業，請在 Microsoft.Azure.Workflows.WebJobs.Extension NuGet 套件中，實作下列介面的方法。 下圖顯示具有方法實作的介面，Azure Logic Apps 設計工具與執行階段預期在具有 Azure Functions 型觸發程序的自訂內建連接器中會有此方法實作：

IServiceOperationsProvider

此介面包含可提供作業資訊清單的下列方法，並會在自訂內建連接器中執行服務提供者的特定工作或實際商務邏輯。 如需詳細資訊，請參閱 IServiceOperationsProvider。

• GetService()

  Azure Logic Apps 中的設計工具需要 GetService() 方法來擷取自訂服務的大致中繼資料，包括服務描述、設計工具上所需的連線輸入參數、功能、品牌色彩、圖示 URL 等。

• GetOperations()

  Azure Logic Apps 中的設計工具需要 GetOperations()方法來擷取自訂服務所實作的作業。 作業清單是以 Swagger 結構描述為基礎。 設計工具也會使用作業中繼資料來理解特定作業的輸入參數，並根據作業輸出的結構描述產生輸出作為屬性標記。

• GetBindingConnectionInformation()

  如果您的觸發程序是以 Azure Functions 為基礎的觸發程序類型，則 Azure Logic Apps 中的執行階段需要 GetBindingConnectionInformation() 方法，將必要的連接參數資訊提供給 Azure Functions 觸發程序繫結。

• InvokeOperation()

  如果您的連接器具有動作，Azure Logic Apps 中的執行階段會需要 InvokeOperation() 方法來呼叫連接器中在工作流程執行期間執行的每個動作。 如果您的連接器沒有動作，則不需要實作 InvokeOperation() 方法。

  在此範例中，Azure Cosmos DB 自訂內建連接器沒有任何動作。 不過，為了完整性，此範例會包含該方法。

如需這有關些方法及其實作的詳細資訊，請在本文稍後檢閱這些方法。

IServiceOperationsTriggerProvider

您可以在自訂內建連接器中，將 Azure Functions 觸發程序或動作新增或公開為服務提供者觸發程序。 若要使用以 Azure Functions 為基礎的觸發程序類型以及相同的 Azure Functions 繫結作為 Azure 受控連接器觸發程序，請實作下列方法來提供 Azure Functions 所需的連線資訊和觸發程序繫結。 如需詳細資訊，請參閱 IServiceOperationsTriggerProvider。

• 需要有 GetFunctionTriggerType() 方法，才能傳回與 Azure Functions 觸發程序繫結中 type 參數相同的字串。

• GetFunctionTriggerDefinition() 具有預設實作，因此您不需要明確實作此方法。 不過，如果您想要更新觸發程序的預設行為，例如提供設計工具未公開的額外參數，您可以實作此方法並覆寫預設行為。

要實作的方法

下列各節說明連接器範例實作的方法。 如需完整的範例，請檢閱 CosmosDbServiceOperationProvider.cs 範例。

重要

當您有敏感性資訊時，例如包含使用者名稱和密碼的連接字串，請務必使用最安全的驗證流程。 例如，Microsoft 建議您在支援可用時，使用受控識別來驗證 Azure 資源的存取權，並指派具有最低必要許可權的角色。

如果無法使用這項功能，請務必透過其他方法來保護連接字串，例如 Azure Key Vault，您可以透過應用程式設定使用。 然後您可以直接參考安全字串，例如連接字串和金鑰。 類似於您可以於部署期間定義環境變數的 ARM 範本，您可以在邏輯應用程式工作流程定義中定義應用程式設定。 然後，您可以擷取動態產生的基礎結構值，例如連線端點、儲存體字串等等。 如需詳細資訊，請參閱 Microsoft 身分識別平台的應用程式類型。

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 觸發程序繫結中 type 參數相同的字串。

下列範例會傳回現成內建 Azure Cosmos DB 觸發程序 ("type": "cosmosDBTrigger") 的字串：

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

GetFunctionTriggerDefinition()

此方法具有預設實作，因此您不需要明確實作此方法。 不過，如果您想要更新觸發程序的預設行為，例如提供設計工具未公開的額外參數，您可以實作此方法並覆寫預設行為。

註冊您的連接器

若要在 Azure Functions 執行階段啟動程序期間載入自訂的內建連接器延伸模組，您必須將 Azure Functions 延伸模組註冊新增為啟動作業，並將連接器註冊為服務提供者清單中的服務提供者。 根據內建觸發程序作為輸入所需的資料類型，選擇性地新增轉換器。 此範例會將 Azure Cosmos DB 文件的 Document 資料類型轉換成 JObject 陣列。

下列各節說明如何將自訂內建連接器註冊為 Azure Functions 延伸模組。

建立啟動作業

1. 使用名為 [assembly:WebJobsStartup] 的元件屬性建立啟動類別。

2. 實作 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 指令碼。

1. 更新延伸模組組合以包含自訂內建連接器。

2. 在 Visual Studio Code 中 (其中應該已安裝適用於 Visual Studio Code 的 Azure Logic Apps (標準) 延伸模組)，建立邏輯應用程式專案，以及使用下列 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\>
   

3. 如果有任何 func.exe 程序正在執行，請務必先關閉或結束該程序，再繼續進行下一個步驟。

測試您的連接器

1. 在 Visual Studio Code 中，開啟您的標準邏輯應用程式，並在設計工具中開啟空白工作流程。

2. 在設計工具介面上，選取 [選擇作業] 以開啟連接器作業選擇器。

3. 在 [作業搜尋] 方塊底下，選取 [內建]。 在搜尋方塊中，輸入 cosmos db。

   作業選擇器會顯示您的自訂內建連接器和觸發程序，例如：

   

4. 從觸發程序清單中，選取您的自訂內建觸發程序以啟動工作流程。

5. 在連線窗格上，提供下列屬性值來建立連線，例如：

   屬性	必填	值	Description
   連線名稱	Yes	<Azure-Cosmos-DB-connection-name>	要建立的 Azure Cosmos DB 連線名稱
   連接字串	Yes	<Azure Cosmos DB-DB-connection-string>	Azure Cosmos DB 資料庫集合或租用集合 (用來新增每個新接收文件) 的連接字串。

   

6. 完成時，選取建立。

7. 在觸發程序屬性窗格中，為您的觸發程序提供下列屬性值，例如：

   屬性	必填	值	Description
   資料庫名稱	Yes	<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": {}
   }
   

8. 在 Visual Studio Code 中的 [執行] 功能表上，選取 [開始偵錯]。 (按 F5)

9. 若要觸發工作流程，請在 Azure 入口網站中開啟 Azure Cosmos DB 帳戶。 在帳戶功能表上，選取 [資料總管]。 瀏覽至您在觸發程序中指定的資料庫和集合。 將項目新增至集合。

   

下一步

• 自訂內建 Azure Cosmos DB 連接器範例的來源 - Azure Logic Apps 連接器延伸模組

• 內建服務匯流排觸發程序：批次處理和工作階段處理