Создание настраиваемых встроенных соединителей для стандартных приложений логики в Azure Logic Apps с одним клиентом

Область применения: Azure Logic Apps (стандартная версия)

Если вам необходимы соединители, которые недоступны в рабочих процессах приложений логики уровня "Стандартный", можно создать собственные встроенные соединители с помощью модели расширяемости, которую используют встроенные соединители на основе поставщика службы, доступные для рабочих процессов уровня "Стандартный" в Azure Logic Apps с одним арендатором. Эта модель расширяемости основана на модели расширяемости Функций Azure.

В этой статье показано, как создать пример пользовательского встроенного соединителя Azure Cosmos DB, который имеет один триггер на основе Функции Azure и никаких действий. Триггер запускается при добавлении нового документа в коллекцию аренды или контейнер в Azure Cosmos DB, а затем запускает рабочий процесс, использующий входные полезные данные в качестве документа Azure Cosmos DB.

В этом примере соединителя используются те же функциональные возможности, что и в триггере Azure Cosmos DB для Функций Azure, которые основаны на триггерах и привязках Функций Azure. Полный пример см . в примере пользовательского встроенного соединителя Azure Cosmos DB — расширения соединителя Azure Logic Apps.

Дополнительные сведения см. в следующей документации:

• Пользовательские соединители для приложений логики уровня "Стандартный"
• Встроенные соединители на основе поставщика службы
• Azure Logic Apps с одним клиентом

Необходимые компоненты

• Учетная запись и подписка Azure. Если у вас нет ее, вы можете зарегистрироваться для получения бесплатной учетной записи Azure.

• Базовые знания об Azure Logic Apps с одним арендатором, рабочих процессах приложений логики уровня "Стандартный", соединителях и о том, как с помощью Visual Studio Code создавать рабочие процессы на основе одного арендатора. Дополнительные сведения см. в следующей документации:

  • Один клиент и мультитенант в Azure Logic Apps

  • Создание рабочего процесса интеграции с Azure Logic Apps с одним арендатором (цен. категория "Стандартный") — портал Azure

• Установленный редактор кода Visual Studio Code с расширением Azure Logic Apps (цен. категория "Стандартный") и другими необходимыми компонентами. Установка уже должна включать пакет NuGet для Microsoft.Azure.Workflows.WebJobs.Extension.

  Примечание.

  Возможность разработки в настоящее время доступна только в Visual Studio Code.

• Учетная запись Azure Cosmos DB, база данных и контейнер или коллекция. Дополнительные сведения см. в кратком руководстве по созданию учетной записи Azure Cosmos DB, базы данных, контейнера и элементов из портал Azure.

Пошаговые действия

Ниже описываются основные действия по созданию примера соединителя.

1. Создайте проект библиотеки классов.

2. В проекте добавьте пакет NuGet Microsoft.Azure.Workflows.WebJobs.Extension в виде ссылки NuGet.

3. Предоставьте операции для встроенного соединителя. Для этого с помощью пакета NuGet реализуйте методы для интерфейсов с именами IServiceOperationsProvider и IServiceOperationsTriggerProvider.

4. Зарегистрируйте пользовательский встроенный соединитель в расширении среды выполнения Функций Azure.

5. Установите соединитель для использования.

Создание проекта библиотеки классов

1. В Visual Studio Code создайте проект библиотеки классов .NET Core 3.1.

2. В проекте добавьте пакет NuGet с именем Microsoft.Azure.Workflows.WebJobs.Extension в виде ссылки NuGet.

Реализация интерфейса поставщика службы

Чтобы предоставить операции для примера встроенного соединителя, в пакете NuGet Microsoft.Azure.Workflows.WebJobs.Extension реализуйте методы для приведенных ниже интерфейсов. На следующей схеме представлены интерфейсы с реализациями методов, которые конструктор Azure Logic Apps и среда выполнения ожидают от пользовательского встроенного соединителя, содержащего триггер на основе Функций Azure:

IServiceOperationsProvider

Этот интерфейс включает приведенные ниже методы, которые предоставляют манифест операций и выполняют конкретные задачи поставщика службы или фактическую бизнес-логику в пользовательском встроенном соединителе. Дополнительные сведения см. в разделе IServiceOperationsProvider.

• GetService()

  Конструктору в Azure Logic Apps метод GetService() требуется для того, чтобы получать важные метаданные для пользовательской службы, включая ее описание, необходимые для конструктора входные параметры подключения, возможности, цвет торговой марки, URL-адрес значка и т. д.

• GetOperations()

  Конструктору в Azure Logic Apps метод GetOperations() требуется для получения операций, реализованных пользовательской службой. Список операций основан на схеме Swagger. Конструктор также использует метаданные операций, чтобы распознать входные параметры для определенных операций и создать выходные данные в качестве маркеров свойств на основе схемы выходных данных для операции.

• GetBindingConnectionInformation()

  Если триггер основан на Функциях Azure, метод GetBindingConnectionInformation() требуется среде выполнения в Azure Logic Apps для предоставления необходимых сведений о параметрах подключения привязке триггера Функций Azure.

• InvokeOperation()

  Если соединитель содержит действия, метод InvokeOperation() требуется среде выполнения в Azure Logic Apps для вызова каждого действия в соединителе, совершенного во время выполнения рабочего процесса. Если соединитель не содержит действий, вам не нужно реализовывать метод InvokeOperation().

  В этом примере настраиваемый встроенный соединитель Azure Cosmos DB не имеет действий. Однако метод включен в этот пример для обеспечения полноты.

Дополнительные сведения об этих методах и их реализации см. в описании этих методов далее в этой статье.

IServiceOperationsTriggerProvider

Вы можете добавить или предоставить триггер или действие Функций Azure в качестве триггера поставщика службы в пользовательском встроенном соединителе. Чтобы использовать тип триггера на основе Функций Azure и ту же привязку Функций Azure, что и триггер управляемого соединителя Azure, реализуйте следующие методы для указания сведений о подключении и привязок триггеров, необходимых Функциям Azure. Дополнительные сведения см. в разделе IServiceOperationsTriggerProvider.

• Метод GetFunctionTriggerType() необходим для возврата строки, которая совпадает с параметром type в привязке триггера Функций Azure.

• У 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, приведенный ниже метод предоставит необходимые сведения о параметрах подключения привязке триггера Функций Azure.

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, необходимо вернуть строку, которая совпадает с параметром type в привязке триггера Функций Azure.

В следующем примере возвращается строка для стандартного встроенного триггера Azure Cosmos DB "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

У этого метода есть реализация по умолчанию, поэтому явно реализовывать его не нужно. Однако, если необходимо обновить поведение триггера по умолчанию, например предоставить дополнительные параметры, не указанные в конструкторе, можно реализовать этот метод и переопределить поведение по умолчанию.

Регистрация соединителя

Чтобы загрузить пользовательское встроенное расширение соединителя при запуске среды выполнения Функций Azure, необходимо добавить регистрацию расширения Функций Azure в качестве задания запуска и зарегистрировать соединитель в качестве поставщика службы в списке поставщиков служб. При необходимости добавьте преобразователь в зависимости от того, какой тип входных данных требуется встроенному триггеру. В этом примере тип данных Document для документов Azure Cosmos DB преобразуется в массив JObject.

В следующих разделах показано, как зарегистрировать пользовательский встроенный соединитель в качестве расширения Функций Azure.

Создание задания запуска

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

   Дополнительные сведения см. в разделе Регистрация служб статьи "Использование внедрения зависимостей в Функциях Azure .NET".

Регистрация поставщика службы

Теперь зарегистрируйте реализацию поставщика службы в качестве расширения Функций Azure в обработчике Azure Logic Apps. В этом примере в качестве нового триггера используется встроенный триггер Azure Cosmos DB для Функций Azure. В этом примере также регистрируется новый поставщик служб Azure Cosmos DB для существующего списка поставщиков услуг, который уже входит в расширение Azure Logic Apps. Дополнительные сведения см. в статье Регистрация расширений привязок Функций Azure.

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 применяется универсальный способ для обработки всех встроенных триггеров Функций Azure с использованием массива JObject. Однако, если вы хотите преобразовать доступный только для чтения список документов базы данных 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 и просмотрите скрипт PowerShell с именем add-extension.ps1.

1. Обновите пакет расширений, чтобы включить пользовательский встроенный соединитель.

2. В редакторе 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\>
   

3. Если выполняется какой-либо процесс func.exe, обязательно закройте или завершите его, прежде чем перейти к следующему шагу.

Тестирование соединителя

1. В Visual Studio Code откройте приложение логики уровня "Стандартный" и пустой рабочий процесс в конструкторе.

2. В области конструктора щелкните Choose an operation (Выбрать операцию), чтобы открыть средство выбора операций соединителя.

3. Под полем поиска операций выберите Встроенные. В поле поиска введите cosmos db.

   В средстве выбора операций отобразится пользовательский встроенный соединитель и триггер, например:

   

4. В списке Триггеры выберите свой пользовательский встроенный триггер, чтобы запустить рабочий процесс.

5. На панели подключения укажите следующие значения свойств, чтобы создать подключение, например:

   Свойство	Обязательное поле	значение	Описание
   Имя подключения	Да	<Azure-Cosmos-DB-connection-name>	Имя создаваемого подключения Azure Cosmos DB
   Строка подключения	Да	<Строка подключения к Azure Cosmos DB-DB>	Строка подключения для коллекции баз данных или коллекции аренды Azure Cosmos DB, в которую требуется добавлять каждый новый полученный документ.

   

6. По завершении нажмите Создать.

7. На панели свойств триггера укажите следующие значения свойств для триггера, например:

   Свойство	Обязательное поле	значение	Описание
   Имя базы данных	Да	<Azure-Cosmos-DB-database-name>	Имя базы данных Azure Cosmos DB, используемой
   Имя коллекции	Да	<Azure-Cosmos-DB-collection-name>	Имя коллекции Azure Cosmos DB, в которой необходимо добавить каждый новый полученный документ.

   

   Для этого примера в представлении кода определение рабочего процесса, которое находится в файле workflow.json, содержит объект JSON triggers примерно такого вида:

   {
      "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, содержит объект JSON serviceProviderConnections примерно такого вида:

   {
      "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

• Встроенный триггер служебная шина: пакетная обработка и обработка сеанса