Criar conectores incorporados personalizados para aplicações lógicas Standard no Azure Logic Apps de inquilino único

Se precisar de conectores que não estejam disponíveis nos fluxos de trabalho de aplicações lógicas Standard, pode criar os seus próprios conectores incorporados usando a mesma extensibilidade modelo que é usada pelos conectores incorporados baseados no prestador de serviços disponíveis para fluxos de trabalho standard em Azure Logic Apps de inquilino único. Esta extensibilidade modelo baseia-se na extensibilidade Funções do Azure modelo.

Este artigo mostra como criar um exemplo personalizado de conector Cosmos DB, que tem um único gatilho baseado em Funções do Azure e sem ações. O gatilho dispara quando um novo documento é adicionado à coleção de locação ou recipiente em Cosmos DB e, em seguida, executa um fluxo de trabalho que usa a carga de entrada como o documento Cosmos.

Operação Detalhes da operação Descrição
Acionador Quando um documento é recebido Esta operação de gatilho é executado quando uma operação de inserção ocorre na base de dados e recolha especificadas da Cosmos DB.
Ação Nenhuma Este conector não define nenhuma operação de ação.

Este conector de amostra utiliza a mesma funcionalidade que o gatilho DB Azure Cosmos para Funções do Azure, que se baseia em gatilhos e encadernações Funções do Azure. Para a amostra completa, reveja o conector DB do Cosmos incorporado personalizado - Azure Logic Apps extensões do conector.

Para mais informações, reveja a seguinte documentação:

Pré-requisitos

Passos gerais

O esboço a seguir descreve os passos de alto nível para construir o conector exemplo:

  1. Crie um projeto de biblioteca de classes.

  2. No seu projeto, adicione o pacote Microsoft.Azure.Workflows.WebJobs.Extension NuGet como referência NuGet.

  3. Forneça as operações para o seu conector incorporado utilizando o pacote NuGet para implementar os métodos para as interfaces chamadas IServiceOperationsProvider e IServiceOperationsTriggerProvider.

  4. Registe o seu conector personalizado incorporado com a extensão de tempo de execução Funções do Azure.

  5. Instale o conector para utilização.

Crie o seu projeto de biblioteca de classes

  1. Em Visual Studio Código, crie um projeto de biblioteca de classe .NET Core 3.1.

  2. No seu projeto, adicione o pacote NuGet denominado Microsoft.Azure.Workflows.WebJobs.Extension como referência NuGet.

Implementar a interface do prestador de serviços

Para fornecer as operações para o conector incorporado da amostra, no pacote Microsoft.Azure.Workflows.WebJobs.Extension NuGet, implemente os métodos para as seguintes interfaces. O diagrama a seguir mostra as interfaces com as implementações do método que o designer Azure Logic Apps e o tempo de execução esperam para um conector personalizado incorporado que tenha um gatilho baseado em Funções do Azure:

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

IServiceOperationsProvider

Esta interface inclui os seguintes métodos que fornecem o manifesto de operação e executa as tarefas específicas do seu fornecedor de serviços ou a lógica de negócio real no seu conector personalizado incorporado. Para mais informações, reveja o IServiceOperationsProvider.

  • GetService()

    O designer em Azure Logic Apps requer que o método GetService() recupere os metadados de alto nível para o seu serviço personalizado, incluindo a descrição do serviço, os parâmetros de entrada de conexão exigidos no designer, capacidades, cor da marca, URL do ícone, e assim por diante.

  • GetOperations()

    O designer em Azure Logic Apps requer o método GetOperations() para recuperar as operações implementadas pelo seu serviço personalizado. A lista de operações baseia-se no esquema do Swagger. O designer também usa os metadados de operação para entender os parâmetros de entrada para operações específicas e gerar as saídas como fichas de propriedade, com base no esquema da saída para uma operação.

  • GetBindingConnectionInformation()

    Se o seu gatilho for um tipo de gatilho baseado em Funções do Azure, o tempo de funcionamento em Azure Logic Apps requer que o método GetBindingConnectionInformation() forneça as informações dos parâmetros de ligação necessários à ligação do gatilho Funções do Azure.

  • InvocaçãoOperação()

    Se o seu conector tiver ações, o tempo de funcionamento em Azure Logic Apps requer que o método InvokeOperation() ligue para cada ação no seu conector que funciona durante a execução do fluxo de trabalho. Se o seu conector não tiver ações, não tem de implementar o método InvokeOperation().

    Neste exemplo, o conector personalizado da Cosmos DB não tem ações. No entanto, o método está incluído neste exemplo para a completude.

Para obter mais informações sobre estes métodos e a sua implementação, reveja estes métodos mais tarde neste artigo.

IServiceOperationsTriggerProvider

Pode adicionar ou expor um gatilho ou ação Funções do Azure como um gatilho de um fornecedor de serviços no seu conector personalizado incorporado. Para utilizar o tipo de gatilho baseado em Funções do Azure e a mesma ligação Funções do Azure que o gatilho do conector gerido Azure, implemente os seguintes métodos para fornecer as informações de ligação e acionar as ligações conforme exigido por Funções do Azure. Para mais informações, reveja o IServiceOperationsTriggerProvider.

  • O método GetFunctionTriggerType() é necessário para devolver a cadeia que é a mesma do parâmetro do tipo no Funções do Azure a ligação do gatilho.

  • O GetFunctionTriggerDefinition() tem uma implementação padrão, por isso não precisa de implementar explicitamente este método. No entanto, se pretender atualizar o comportamento padrão do gatilho, como fornecer parâmetros extra que o designer não expõe, pode implementar este método e anular o comportamento padrão.

Métodos para implementar

As seguintes secções descrevem os métodos que o conector exemplo implementa. Para a amostra completa, reveja a Amostra CosmosDbServiceOperationProvider.cs.

GetService()

O designer requer o seguinte método para obter a descrição de alto nível para o seu serviço:

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

GetOperations()

O designer requer o seguinte método para que as operações são implementadas pelo seu serviço. Esta lista de operações baseia-se no esquema do Swagger.

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

GetBindingConnectionInformation()

Para utilizar o tipo de gatilho baseado em Funções do Azure, o seguinte método fornece as informações necessárias sobre os parâmetros de ligação à ligação do gatilho Funções do Azure.

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

InvocaçãoOperação()

O exemplo cosmos DB conector personalizado incorporado não tem ações, mas o seguinte método está incluído para completar:

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

GetFunctionTriggerType()

Para utilizar um gatilho baseado em Funções do Azure como gatilho no seu conector, tem de devolver a corda que é igual ao parâmetro do tipo no Funções do Azure acionamento.

O exemplo a seguir devolve a corda para o gatilho DB Azure Cosmos incorporado fora da caixa: "type": "cosmosDBTrigger"

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

GetFunctionTriggerDefinition()

Este método tem uma implementação padrão, por isso não precisa implementar explicitamente este método. No entanto, se pretender atualizar o comportamento padrão do gatilho, como fornecer parâmetros extra que o designer não expõe, pode implementar este método e anular o comportamento padrão.

Registar os seus conectores

Para carregar a extensão personalizada do conector incorporado durante o processo de início de tempo de funcionamento Funções do Azure, tem de adicionar o registo de extensão Funções do Azure como trabalho de arranque e registar o seu conector como prestador de serviços na lista de prestadores de serviços. Com base no tipo de dados de que o gatilho incorporado necessita como entradas, adicione opcionalmente o conversor. Este exemplo converte o tipo de dados documental para documentos de DB cosmos para uma matriz JObject .

As seguintes secções mostram como registar o seu conector personalizado incorporado como uma extensão Funções do Azure.

Criar o trabalho de arranque

  1. Crie uma classe de arranque utilizando o atributo de montagem denominado [conjunto:WebJobsStartup].

  2. Implementar a interface IWebJobsStartup . No método Configure() registe a extensão e injete o prestador de serviços.

    Por exemplo, o seguinte corte de código mostra a implementação da classe de arranque para o conector DB cosmos incorporado personalizado da amostra:

    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 mais informações, reveja os serviços de registo - Utilize a injeção de dependência em Funções do Azure .NET.

Registar o prestador de serviços

Agora, registe a implementação do prestador de serviços como uma extensão Funções do Azure com o motor Azure Logic Apps. Este exemplo usa o gatilho DB Azure Cosmos incorporado para Funções do Azure como um novo gatilho. Este exemplo também regista o novo prestador de serviços Da Cosmos DB para uma lista existente de prestadores de serviços, que já faz parte da extensão Azure Logic Apps. Para mais informações, reveja o Registo Funções do Azure extensões vinculativas.

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 Cosmos 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 Cosmos Document list to a JObject array.
         context.AddConverter<IReadOnlyList<Document>, JObject[]>(ConvertDocumentToJObject);
      }
   }
}

Adicione um conversor

Azure Logic Apps tem uma forma genérica de lidar com qualquer Funções do Azure gatilho incorporado utilizando a matriz JObject. No entanto, se quiser converter a lista apenas de documentos DB do Azure Cosmos numa matriz JObject , pode adicionar um conversor. Quando o conversor estiver pronto, registe o conversor como parte do ExtensionConfigContext , como mostrado anteriormente neste exemplo:

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

Diagrama de biblioteca de classes para aulas implementadas

Quando terminar, reveja o seguinte diagrama de classe que mostra a implementação de todas as classes do pacote de extensão Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll :

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Conceptual code map diagram that shows complete class implementation.

Instale o seu conector

Para adicionar a referência NuGet da secção anterior, no pacote de extensão denominado Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, atualize o ficheiro extensions.json . Para obter mais informações, aceda ao repo de extensões de conector Azure/logicapps e reveja o script PowerShell denominado add-extension.ps1.

  1. Atualize o pacote de extensão para incluir o conector personalizado incorporado.

  2. Em Visual Studio Código, que deve ter a Azure Logic Apps (Standard) para Visual Studio extensão do Código instalada, criar um projeto de aplicação lógica e instalar o pacote de extensão utilizando o seguinte comando PowerShell:

    PowerShell

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

    Alternativamente, a partir do diretório do seu projeto de aplicação lógica usando um pedido PowerShell, executar o script PowerShell nomeado add-extension.ps1:

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

    Bash

    Para utilizar a Bash, em vez disso, a partir do diretório do seu projeto de aplicações lógicas, execute o script PowerShell com o seguinte comando:

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

    Se a extensão do seu conector incorporado personalizado foi instalada com sucesso, obtém-se uma saída semelhante ao seguinte exemplo:

    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. Se algum processofunc.exe estiver em curso, certifique-se de fechar ou sair desse processo antes de continuar para o passo seguinte.

Teste o seu conector

  1. Em Visual Studio Código, abra a sua app lógica Standard e fluxo de trabalho em branco no designer.

  2. Na superfície do designer, selecione Escolha uma operação para abrir o seletor de operações do conector.

  3. Sob a caixa de pesquisa de operações, selecione Built-in. Na caixa de pesquisa, entra no cosmos db.

    O selecionador de operações mostra o seu conector e gatilho personalizados incorporados, por exemplo:

    Screenshot showing Visual Studio Code and the designer for a Standard logic app workflow with the new custom built-in Cosmos DB connector.

  4. Na lista De gatilhos , selecione o gatilho personalizado incorporado para iniciar o seu fluxo de trabalho.

  5. No painel de ligação, forneça os seguintes valores de propriedade para criar uma ligação, por exemplo:

    Propriedade Necessário Valor Descrição
    Nome de conexão Sim <Nome de conexão Cosmos-DB> O nome para a ligação Cosmos DB para criar
    Cadeia de Ligação Sim <Cosmos-DB-ligação-cadeia> A cadeia de ligação para a coleção de base de dados DB da Azure Cosmos ou a coleção de arrendamento onde pretende adicionar cada novo documento recebido.

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

  6. Quando concluir, selecione Criar.

  7. No painel de propriedades do gatilho, forneça os seguintes valores de propriedade para o seu gatilho, por exemplo:

    Propriedade Necessário Valor Descrição
    Nome da base de dados Sim <Cosmos-DB-base de dados-nome> O nome da base de dados Cosmos DB para usar
    Nome da coleção Sim <Nome da coleção Cosmos-DB> O nome da coleção Cosmos DB onde pretende adicionar cada novo documento recebido.

    Screenshot showing the trigger properties pane.

    Para este exemplo, na visão de código, a definição de fluxo de trabalho, que está no ficheiro workflow.json , tem um triggers objeto JSON que aparece semelhante à seguinte amostra:

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

    A definição de ligação, que está no ficheiro connections.json , tem um serviceProviderConnections objeto JSON que aparece semelhante à seguinte amostra:

    {
       "serviceProviderConnections": {
          "cosmosDb": {
             "parameterValues": {
                "connectionString": "@appsetting('cosmosDb_connectionString')"
             },
             "serviceProvider": {
                "id": "/serviceProviders/CosmosDb"
             },
             "displayName": "myCosmosDbConnection"
          }
       },
       "managedApiConnections": {}
    }
    
  8. Em Visual Studio Código, no menu Executar, selecione Iniciar a depuragem. (Pressione F5)

  9. Para ativar o seu fluxo de trabalho, no portal do Azure, abra a sua conta DB Azure Cosmos. No menu de conta, selecione Data Explorer. Navegue na base de dados e recolha que especificou no gatilho. Adicione um item à coleção.

    Screenshot showing the Azure portal, Cosmos DB account, and Data Explorer open to the specified database and collection.

Passos seguintes