단일 테넌트 Azure Logic Apps에서 표준 논리 앱에 대한 사용자 지정 기본 제공 커넥터 만들기

아티클
01/04/2024

적용 대상: Azure Logic Apps(표준)

표준 논리 앱 워크플로에서 사용할 수 없는 커넥터가 필요한 경우 단일 테넌트 Azure Logic Apps의 표준 워크플로에 사용할 수 있는 서비스 공급자 기반 기본 제공 커넥터에서 사용하는 것과 동일한 확장성 모델을 사용하여 사용자 고유의 기본 제공 커넥터를 만들 수 있습니다. 이 확장성 모델은 Azure Functions 확장성 모델을 기반으로 합니다.

이 문서에서는 단일 Azure Functions 기반 트리거가 있고 작업이 없는 사용자 지정 기본 제공 Azure Cosmos DB 커넥터 예제를 만드는 방법을 보여 줍니다. 새 문서가 Azure Cosmos DB의 임대 컬렉션 또는 컨테이너에 추가되면 트리거가 실행된 다음, 입력 페이로드를 Azure Cosmos DB 문서로 사용하는 워크플로를 실행합니다.

연산	작업 세부 정보	설명
트리거	문서를 받은 경우	이 트리거 작업은 지정된 Azure Cosmos DB 데이터베이스 및 컬렉션에서 삽입 작업이 수행될 때 실행됩니다.
작업	없음	이 커넥터는 동작 작업을 정의하지 않습니다.

이 샘플 커넥터는 Azure Functions 트리거 및 바인딩을 기반으로 하는 Azure Functions에 대한 Azure Cosmos DB 트리거와 동일한 기능을 사용합니다. 전체 샘플은 사용자 지정 기본 제공 Azure Cosmos DB 커넥터 샘플 - Azure Logic Apps 커넥터 확장을 검토하세요.

자세한 내용은 다음 설명서를 검토하세요.

필수 조건

Azure 계정 및 구독 구독이 없는 경우 Azure 체험 계정에 등록합니다.
단일 테넌트 Azure Logic Apps, 표준 논리 앱 워크플로, 커넥터 및 Visual Studio Code를 사용하여 단일 테넌트 기반 워크플로를 만드는 방법에 대한 기본 지식. 자세한 내용은 다음 설명서를 검토하세요.
- Azure Logic Apps의 단일 테넌트 및 다중 테넌트와 통합 서비스 환경
- 단일 테넌트 Azure Logic Apps(표준)를 사용하여 통합 워크플로 만들기 - Azure Portal
Azure Logic Apps(표준) 확장 및 기타 필수 구성 요소가 설치된 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 참조로 추가합니다.
IServiceOperationsProvider 및 IServiceOperationsTriggerProvider라는 인터페이스에 대한 메서드를 구현하는 NuGet 패키지를 사용하여 기본 제공 커넥터에 대한 작업을 제공합니다.
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 기반 트리거가 있는 사용자 지정 기본 제공 커넥터에 대해 예상하는 메서드 구현과의 인터페이스를 보여 줍니다.

Conceptual class diagram showing method implementation for sample Azure Cosmos DB custom built-in connector.

IServiceOperationsProvider

이 인터페이스에는 작업 매니페스트를 제공하고 사용자 지정 기본 제공 커넥터에서 서비스 공급자의 특정 작업 또는 실제 비즈니스 논리를 수행하는 다음 메서드가 포함됩니다. 자세한 내용은 IServiceOperationsProvider를 검토하세요.

GetService()

Azure Logic Apps의 디자이너에는 서비스 설명, 디자이너에 필요한 연결 입력 매개 변수, 기능, 브랜드 색, 아이콘 URL 등을 포함하여 사용자 지정 서비스에 대한 상위 수준 메타데이터를 검색하는 GetService() 메서드가 필요합니다.
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 트리거 바인딩의 type 매개 변수와 동일한 문자열을 반환하는 데 필요합니다.
GetFunctionTriggerDefinition()에는 기본 구현이 있으므로 이 메서드를 명시적으로 구현할 필요가 없습니다. 그러나 디자이너에서 공개하지 않는 추가 매개 변수를 제공하는 것과 같이 트리거의 기본 동작을 업데이트하려는 경우 이 메서드를 구현하고 기본 동작을 재정의할 수 있습니다.

구현할 메서드

다음 섹션에서는 커넥터 예제에서 구현하는 메서드에 대해 설명합니다. 전체 샘플은 CosmosDbServiceOperationProvider.cs 샘플을 검토하세요.

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 확장으로 등록하는 방법을 보여 줍니다.

시작 작업 만들기

[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 Functions 확장으로 Azure Logic Apps 엔진에 등록합니다. 다음 예제에서는 Azure Functions에 대한 기본 제공 Azure Cosmos DB 트리거를 새 트리거로 사용합니다. 또한 이 예제에서는 이미 Azure Logic Apps 확장의 일부인 기존 서비스 공급자 목록에 대한 새 Azure Cosmos DB 서비스 공급자를 등록합니다. 자세한 내용은 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

Conceptual code map diagram that shows complete class implementation.

커넥터 설치

이전 섹션의 NuGet 참조를 추가하려면 Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll이라는 확장 번들에서 extensions.json 파일을 업데이트합니다. 자세한 내용은 Azure/logicapps-connector-extensions 리포지토리로 이동하여 add-extension.ps1이라는 PowerShell 스크립트를 검토하세요.

사용자 지정 기본 제공 커넥터를 포함하도록 확장 번들을 업데이트합니다.

Visual Studio Code용 Azure Logic Apps(표준) 확장이 설치되어 있는 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의 디자이너에서 표준 논리 앱과 빈 워크플로를 엽니다.
디자이너 화면에서 작업 선택을 선택하여 커넥터 작업 선택기를 엽니다.
작업 검색 상자 아래에서 기본 제공을 선택합니다. 검색 상자에서 cosmos db를 입력합니다.

작업 선택기에서 사용자 지정 기본 제공 커넥터 및 트리거를 표시합니다. 예를 들면 다음과 같습니다.
트리거 목록에서 사용자 지정 기본 제공 트리거를 선택하여 워크플로를 시작합니다.

연결 창에서 다음 속성 값을 제공하여 연결을 만듭니다. 예를 들면 다음과 같습니다.

속성	필요함	값	Description
연결 이름	예	<Azure-Cosmos-DB-connection-name>	만들 Azure Cosmos DB 연결의 이름
연결 문자열	예	<Azure Cosmos DB-DB-connection-string>	새로 받은 각 문서를 추가하려는 Azure Cosmos DB 데이터베이스 컬렉션 또는 임대 컬렉션에 대한 연결 문자열

Screenshot showing the connection pane when using the connector for the first time.

완료되면 만들기를 선택합니다.

트리거 속성 창에서 트리거에 대해 다음 속성 값을 제공합니다. 예를 들면 다음과 같습니다.

속성	필요함	값	설명
데이터베이스 이름	예	<Azure-Cosmos-DB-database-name>	사용할 Azure Cosmos DB 데이터베이스의 이름
컬렉션 이름	예	<Azure-Cosmos-DB-collection-name>	새로 받은 각 문서를 추가하려는 Azure Cosmos DB 컬렉션의 이름

Screenshot showing the trigger properties pane.

다음 예제의 경우 코드 보기에서 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 계정을 엽니다. 계정 메뉴에서 데이터 탐색기를 선택합니다. 트리거에서 지정한 데이터베이스 및 컬렉션을 찾습니다. 항목을 컬렉션에 추가합니다.