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

Статья
08/06/2024

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

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

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

Операция	Сведения об операции	Description
Триггер	При получении документа	Эта операция триггера выполняется при выполнении операции вставки в указанной базе данных и коллекции Azure Cosmos DB.
Действие	нет	Этот соединитель не определяет никаких операций с действиями.

В этом примере соединителя используются те же функциональные возможности, что и в триггере Azure Cosmos DB для Функций Azure, которые основаны на триггерах и привязках Функций Azure. Полный пример см . в примере пользовательского встроенного соединителя Azure Cosmos DB — расширения соединителя 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.

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

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

Создайте проект библиотеки классов.
В проекте добавьте пакет NuGet Microsoft.Azure.Workflows.WebJobs.Extension в виде ссылки NuGet.
Предоставьте операции для встроенного соединителя. Для этого с помощью пакета NuGet реализуйте методы для интерфейсов с именами IServiceOperationsProvider и IServiceOperationsTriggerProvider.
Зарегистрируйте пользовательский встроенный соединитель в расширении среды выполнения Функций Azure.
Установите соединитель для использования.

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

В Visual Studio Code создайте проект библиотеки классов .NET Core 3.1.
В проекте добавьте пакет NuGet с именем Microsoft.Azure.Workflows.WebJobs.Extension в виде ссылки NuGet.

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

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

Схема концептуального класса, показывающая реализацию метода для примера пользовательского соединителя Azure Cosmos DB.

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.

Внимание

Если у вас есть конфиденциальная информация, например строка подключения, включающих имена пользователей и пароли, обязательно используйте самый безопасный поток проверки подлинности. Например, корпорация Майкрософт рекомендует пройти проверку подлинности доступа к ресурсам Azure с управляемым удостоверением при наличии поддержки и назначить роль с минимальными привилегиями.

Если эта возможность недоступна, обязательно защитите строка подключения с помощью других мер, таких как Azure Key Vault, которые можно использовать с параметрами приложения. Потом можно напрямую ссылаться на такие защищенные строки, как строки подключения и ключи. Аналогично шаблонам ARM, где переменные среды определяют в процессе развертывания, настройки приложения можно задать в рамках определения рабочего процесса приложения логики. Затем можно захватывать динамически генерируемые значения инфраструктуры, такие как конечные точки подключения, строки хранения и другие. Дополнительные сведения см. в разделе "Типы приложений" для платформа удостоверений Майкрософт.

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.

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

Создайте класс запуска, используя атрибут сборки с именем [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>();
      }
   }
}

Дополнительные сведения см. в разделе Регистрация служб статьи "Использование внедрения зависимостей в Функциях 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.

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

В редакторе 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 откройте приложение логики уровня "Стандартный" и пустой рабочий процесс в конструкторе.
В области конструктора щелкните Choose an operation (Выбрать операцию), чтобы открыть средство выбора операций соединителя.
Под полем поиска операций выберите Встроенные. В поле поиска введите cosmos db.

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

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

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

Снимок экрана: область подключения при первом использовании соединителя.

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

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

Свойство	Обязательное поле	значение	Описание
Имя базы данных	Да	<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": {}
}

В Visual Studio Code выберите в меню Выполнить пункт Запустить отладку. (Нажмите клавишу F5.)
Чтобы активировать рабочий процесс, на портале Azure откройте страницу для учетной записи Azure Cosmos DB. В меню учетной записи выберите Обозреватель данных. Перейдите к базе данных и коллекции, указанных в триггере. Добавьте элемент в коллекцию.

Поделиться через