Creación de conectores integrados personalizados para aplicaciones lógicas estándar en Azure Logic Apps de inquilino único

Artikulua
08/06/2024

Se aplica a: Azure Logic Apps (estándar)

Si necesita conectores que no están disponibles en flujos de trabajo de aplicaciones lógicas estándar, puede crear sus propios conectores integrados con el mismo modelo de extensibilidad que usan los conectores integrados basados en el proveedor de servicios que están disponibles para flujos de trabajo estándar en Azure Logic Apps de inquilino único. Este modelo de extensibilidad está basado en el modelo de extensibilidad de Azure Functions.

En este artículo se muestra cómo crear el ejemplo de un conector de Azure Cosmos DB integrado y personalizado que tiene un único desencadenador basado en Azure Functions y ninguna acción. El desencadenador se activa cuando se agrega un nuevo documento a la colección de concesiones o al contenedor de Azure Cosmos DB y, a continuación, ejecuta un flujo de trabajo que usa la carga de entrada como documento de Azure Cosmos DB.

Operación	Detalles de la operación	Descripción
Desencadenador	Cuando se recibe un documento	Esta operación desencadenante se ejecuta cuando se produce una operación de inserción en la base de datos y la colección especificadas de Azure Cosmos DB.
Acción	Ninguno	Este conector no define ninguna operación de acción.

Este conector de ejemplo usa la misma funcionalidad que el desencadenador de Azure Cosmos DB para Azure Functions, el cual se basa en desencadenadores y enlaces de Azure Functions. Para obtener la muestra completa, consulte Muestra personalizada del conector integrado Azure Cosmos DB: extensiones del conector de Azure Logic Apps.

Para más información, revise la siguiente documentación:

Requisitos previos

Una cuenta y una suscripción de Azure. Si aún no tiene una, regístrese para obtener una cuenta de Azure gratuita.
Conocimientos básicos sobre Azure Logic Apps de inquilino único, flujos de trabajo de aplicaciones lógicas estándar, conectores y cómo utilizar Visual Studio Code para crear flujos de trabajo basados en un solo inquilino. Para más información, revise la siguiente documentación:
- Inquilino único frente a multiinquilino en Azure Logic Apps
- Creación de un flujo de trabajo de integración con Azure Logic Apps (estándar) de inquilino único: Azure Portal
Visual Studio Code con la extensión de Azure Logic Apps (estándar) y otros requisitos previos instalados. La instalación ya debe incluir el paquete de NuGet para Microsoft.Azure.Workflows.WebJobs.Extension.

Nota

Esta funcionalidad de creación solo está disponible actualmente en Visual Studio Code.
Una cuenta, una base de datos y un contenedor de Azure Cosmos DB. Para obtener más información, consulte Inicio rápido: Creación de una base de datos, un contenedor y elementos de Azure Cosmos DB desde Azure Portal.

Pasos de alto nivel

En el esquema siguiente se describen los pasos generales a seguir para compilar el conector de ejemplo:

Cree un proyecto de biblioteca de clases.
En el proyecto, agregue el paquete de NuGet microsoft.Azure.Workflows.WebJobs.Extension como referencia de NuGet.
Proporcione las operaciones para el conector integrado utilizando el paquete NuGet para implementar los métodos de las interfaces denominadas IServiceOperationsProvider e IServiceOperationsTriggerProvider.
Registre el conector integrado personalizado con la extensión Azure Functions runtime.
Instale el conector a utilizar.

Cree el proyecto de biblioteca de clases

En Visual Studio Code, cree un proyecto de biblioteca de clases de .NET Core 3.1.
En el proyecto, agregue el paquete de NuGet denominado microsoft.Azure.Workflows.WebJobs.Extension como referencia de NuGet.

Implemente la interfaz del proveedor de servicios

Para proporcionar las operaciones para el conector integrado de ejemplo, en el paquete de NuGet Microsoft.Azure.Workflows.WebJobs.Extension, implemente los siguientes métodos para las interfaces. En el diagrama se muestran las interfaces con las implementaciones de método que el diseñador y el entorno de ejecución de Azure Logic Apps esperan para un conector integrado personalizado que tiene un desencadenador basado en Azure Functions:

Diagrama de clases conceptual en el que se muestra la implementación del método para una muestra del conector integrado personalizado de Azure Cosmos DB.

IServiceOperationsProvider

Esta interfaz incluye estos métodos que proporcionan el manifiesto de operación, y realiza las tareas específicas del proveedor de servicios o la lógica de negocios real en el conector integrado personalizado. Para obtener más información, consulte IServiceOperationsProvider.

GetService()

El diseñador de Azure Logic Apps necesita el método GetService() para recuperar los metadatos de alto nivel del servicio personalizado, incluida la descripción del servicio, los parámetros de entrada de conexión necesarios en el diseñador, las funcionalidades, el color de marca, la dirección URL del icono, etc.
GetOperations()

El diseñador de Azure Logic Apps necesita el método GetOperations() para recuperar las operaciones implementadas por el servicio personalizado. La lista de operaciones se basa en el esquema de Swagger. El diseñador también utiliza los metadatos de la operación para comprender los parámetros de entrada para operaciones específicas y generar las salidas como tokens de propiedad, en función del esquema de la salida de una operación.
GetBindingConnectionInformation()

Si el desencadenador es un tipo de desencadenador basado en Azure Functions, el tiempo de ejecución de Azure Logic Apps necesita el método GetBindingConnectionInformation() para proporcionar la información de parámetros de conexión necesaria al enlace de desencadenador de Azure Functions.
InvokeOperation()

Si el conector tiene acciones, el tiempo de ejecución de Azure Logic Apps necesita que el método InvokeOperation() llame a cada acción del conector que se ejecuta durante la ejecución del flujo de trabajo. Si el conector no tiene acciones, no es necesario implementar el método InvokeOperation().

En este ejemplo, el conector integrado personalizado de Azure Cosmos DB no tiene acciones. Sin embargo, el método se incluye en este ejemplo para completarlo.

Para obtener más información sobre estos métodos y su implementación, revise estos métodos más adelante en este artículo.

IServiceOperationsTriggerProvider

Puede agregar o exponer un desencadenador o acción de Azure Functions como desencadenador de proveedor de servicios en el conector integrado personalizado. Para usar el tipo de desencadenador basado en Azure Functions y el mismo enlace de Azure Functions que el desencadenador del conector administrado de Azure, implemente los siguientes métodos para proporcionar la información de conexión y los enlaces desencadenadores según sea necesario en Azure Functions. Para obtener más información, revise IServiceOperationsTriggerProvider.

El método GetFunctionTriggerType() es necesario para devolver la cadena que igual que el parámetro de tipo en el enlace de desencadenador de Azure Functions.
GetFunctionTriggerDefinition() tiene una implementación predeterminada, por lo que no es necesario implementar explícitamente este método. Sin embargo, si desea actualizar el comportamiento predeterminado del desencadenador, como, por ejemplo, poder proporcionar parámetros adicionales que el diseñador no expone, puede implementar este método e invalidar el comportamiento predeterminado.

Métodos para implementar

En las secciones siguientes se describen los métodos que implementa el conector de ejemplo. Para obtener el ejemplo completo, revise Sample CosmosDbServiceOperationProvider.cs.

Importante

Cuando tenga información confidencial, como cadenas de conexión que incluyen nombres de usuario y contraseñas, asegúrese de usar el flujo de autenticación más seguro disponible. Por ejemplo, Microsoft recomienda autenticar el acceso a los recursos de Azure con una identidad administrada cuando la compatibilidad esté disponible y asignar un rol que tenga el privilegio menos necesario.

Si esta funcionalidad no está disponible, asegúrese de proteger las cadenas de conexión a través de otras medidas, como Azure Key Vault, que puede usar con la configuración de la aplicación. De ese modo, puede hacer referencia directamente a cadenas seguras, como claves y cadenas de conexión. De forma similar a las plantillas de ARM, donde puede definir variables de entorno en el momento de la implementación, puede definir la configuración de la aplicación dentro de la definición de flujo de trabajo de la aplicación lógica. A continuación, puede capturar valores de infraestructura generados dinámicamente, como puntos de conexión, cadenas de almacenamiento, etc. Para más información, consulte Tipos de aplicaciones para la plataforma de identidad de Microsoft.

GetService()

El diseñador necesita el siguiente método para obtener la descripción de alto nivel para el servicio:

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

GetOperations()

El diseñador necesita el siguiente método para obtener las operaciones implementadas por el servicio. Esta lista de operaciones se basa en el esquema de Swagger.

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

GetBindingConnectionInformation()

Para usar el tipo de desencadenador basado en Azure Functions, el siguiente método proporciona la información de los parámetros de conexión necesarios al enlace de desencadenador de Azure Functions.

public string GetBindingConnectionInformation(string operationId, InsensitiveDictionary<JToken> connectionParameters)
{
   return ServiceOperationsProviderUtilities
      .GetRequiredParameterValue(
         serviceId: ServiceId,
         operationId: operationID,
         parameterName: "connectionString",
         parameters: connectionParameters)?
      .ToValue<string>();
}

InvokeOperation()

El conector integrado personalizado de Azure Cosmos DB de ejemplo no tiene acciones, pero se incluye el método siguiente para completarlo:

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

GetFunctionTriggerType()

Para usar un desencadenador basado en Azure Functions como desencadenador en el conector, debe devolver la cadena que es igual que el parámetro de tipo en el enlace de desencadenador de Azure Functions.

En el siguiente ejemplo se devuelve la cadena del desencadenador integrado de Azure Cosmos DB, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Este método tiene una implementación predeterminada, por lo que no es necesario implementar explícitamente este método. Sin embargo, si desea actualizar el comportamiento predeterminado del desencadenador, como, por ejemplo, poder proporcionar parámetros adicionales que el diseñador no expone, puede implementar este método e invalidar el comportamiento predeterminado.

Registro del conector

Para cargar la extensión de conector integrada personalizada durante el proceso de inicio del entorno de ejecución de Azure Functions, debe agregar el registro de extensión Azure Functions como un trabajo de inicio y registrar el conector como proveedor de servicios en la lista de proveedores de servicios. En función del tipo de datos que el desencadenador integrado necesita como entradas, puede agregar el convertidor opcionalmente. En este ejemplo se convierte el tipo de datos Document para documentos de Azure Cosmos DB en una matriz JObject.

En las secciones siguientes se muestra cómo registrar el conector integrado personalizado como una extensión de Azure Functions.

Creación del trabajo de inicio

Cree una clase de inicio mediante el atributo de ensamblado denominado [assembly:WebJobsStartup].

Implemente la interfaz IWebJobsStartup. En el método Configure(), registre la extensión e inserte el proveedor de servicios.

Por ejemplo, el siguiente fragmento de código muestra la implementación de la clase de inicio para el conector integrado personalizado de ejemplo de 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>();
      }
   }
}

Para obtener más información, consulte Registro de servicios: uso de la inserción de dependencias en .NET Azure Functions.

Registre el proveedor de servicios

Ahora, registre la implementación del proveedor de servicios como una extensión de Azure Functions con el motor de Azure Logic Apps. En este ejemplo se usa el desencadenador integrado de Azure Cosmos DB para Azure Functions como un nuevo desencadenador. En este ejemplo también se registra el nuevo proveedor de servicios de Azure Cosmos DB para una lista existente de proveedores de servicios, que ya forma parte de la extensión Azure Logic Apps. Para obtener más información, consulte Registro de las extensiones de enlace de 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);
      }
   }
}

Agregue un convertidor

Azure Logic Apps tiene una manera genérica de controlar cualquier desencadenador integrado de Azure Functions utilizando la matriz JObject. Sin embargo, si desea convertir la lista de solo lectura de los documentos de Azure Cosmos DB en una matriz JObject, puede agregar un convertidor. Cuando el convertidor esté listo, registre el convertidor como parte de ExtensionConfigContext como se ha mostrado anteriormente en este ejemplo:

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

Diagrama de la biblioteca de clases para clases implementadas

Cuando haya terminado, revise el siguiente diagrama de clases que muestra la implementación de todas las clases de la agrupación de extensiones deMicrosoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll:

CosmosDbServiceOperationsProvider
CosmosDbServiceProvider
CosmosDbServiceProviderStartup

Diagrama de mapa de código conceptual en el que se muestra la implementación completa de la clase.

Instale el conector

Para agregar la referencia NuGet de la sección anterior, en el paquete de extensiones denominado Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, actualice el archivo extensions.json. Para obtener más información, vaya al repositorio Azure/logicapps-connector-extensions y revise el script de PowerShell denominado add-extension.ps1.

Actualice la agrupación de extensiones para incluir el conector integrado personalizado.

En Visual Studio Code, que debe tener instalada la extensión Azure Logic Apps (Estándar) para Visual Studio Code, cree un proyecto de aplicación lógica e instale el paquete de extensión mediante el siguiente comando de PowerShell:

PowerShell

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

Como alternativa, ejecute el script de PowerShell denominado add-extension.ps1 desde el directorio del proyecto de aplicación lógica utilizando un símbolo del sistema de PowerShell:

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

Bash

Para usar Bash en su lugar, desde el directorio del proyecto de aplicación lógica, ejecute el script de PowerShell con el siguiente comando:

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

Si la extensión del conector integrado personalizado se instaló correctamente, obtendrá una salida similar al ejemplo siguiente:

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\>

Si algún proceso func.exe se está ejecutando, asegúrese de cerrar o salir de ese proceso antes de continuar con el paso siguiente.

Pruebe el conector

En Visual Studio Code, abra la aplicación lógica estándar y el flujo de trabajo en blanco en el diseñador.
En la superficie del diseñador, seleccione Elegir una operación para abrir el selector de operaciones del conector.
En el cuadro de búsqueda de operaciones, seleccione Integrado. En el cuadro de búsqueda, escriba cosmos db.

El selector de operaciones muestra el conector y el desencadenador integrados personalizados, por ejemplo:
En la lista Desencadenadores, seleccione el desencadenador integrado personalizado para iniciar el flujo de trabajo.

En el panel de conexión, proporcione los siguientes valores de propiedad para crear una conexión, por ejemplo:

Propiedad	Necesario	Valor	Descripción
Nombre de la conexión	Sí	<Azure-Cosmos-DB-connection-name>	Nombre de la conexión de Azure Cosmos DB que se va a crear
Cadena de conexión	Yes	<Azure Cosmos DB-DB-connection-string>	La cadena de conexión de la colección de bases de datos de Azure Cosmos DB o la colección de concesiones donde desea agregar cada nuevo documento recibido.

Captura de pantalla en la que se muestra el panel de conexión al usar el conector por primera vez.

Seleccione Crear cuando haya terminado.

En el panel de propiedades del desencadenador, proporcione los siguientes valores de propiedad para el desencadenador, por ejemplo:

Propiedad	Necesario	Valor	Descripción
Nombre de la base de datos	Sí	<Azure-Cosmos-DB-database-name>	Nombre de la base de datos de Azure Cosmos DB que se va a usar
Nombre de colección	Sí	<Azure-Cosmos-DB-collection-name>	Nombre de la colección de Azure Cosmos DB donde desea agregar cada nuevo documento recibido.

Captura de pantalla en la que se muestra el panel de propiedades del desencadenador.

En este ejemplo, en la vista de código, la definición de flujo de trabajo, que se encuentra en el archivo workflow.json, tiene un objeto JSON triggers que se parece al ejemplo siguiente:

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

La definición de conexión, que se encuentra en el archivo connections.json, tiene un objeto JSON serviceProviderConnections que parece similar al ejemplo siguiente:

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

En Visual Studio Code, seleccione Iniciar depuración en el menú Ejecutar. (Presione F5)
Para desencadenar el flujo de trabajo, abra la cuenta de Azure Cosmos DB en el Azure Portal. En el menú de la cuenta, seleccione Explorador de datos. Navegue a la base de datos y a la colección que especificó en el desencadenador. Agregue un elemento a la colección.

Partekatu honen bidez: