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

Aplica-se a: Azure Logic Apps (Standard)

Se precisar de conectores que não estejam disponíveis nos fluxos de trabalho da aplicação lógica Standard, pode criar os seus próprios conectores incorporados com o mesmo modelo de extensibilidade utilizado pelos conectores incorporados baseados no fornecedor de serviços disponíveis para fluxos de trabalho Standard no Azure Logic Apps de inquilino único. Este modelo de extensibilidade baseia-se no modelo de extensibilidade Funções do Azure.

Este artigo mostra como criar um conector do Azure Cosmos DB incorporado de exemplo, que tem um único acionador baseado em Funções do Azure e nenhuma ação. O acionador é acionado quando um novo documento é adicionado à coleção de concessões ou contentor no Azure Cosmos DB e, em seguida, executa um fluxo de trabalho que utiliza o payload de entrada como o documento do Azure Cosmos DB.

Operação	Detalhes da operação	Descrição
Acionador	Quando um documento é recebido	Esta operação de acionador é executada quando ocorre uma operação de inserção na base de dados e coleção do Azure Cosmos DB especificada.
Ação	Nenhuma	Este conector não define operações de ação.

Este conector de exemplo utiliza a mesma funcionalidade que o acionador do Azure Cosmos DB para Funções do Azure, que se baseia em Funções do Azure acionadores e enlaces. Para obter o exemplo completo, veja Exemplo de conector incorporado do Azure Cosmos DB - Extensões do Conector do Azure Logic Apps.

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

• Conectores personalizados para aplicações lógicas Standard
• Conectores incorporados baseados no fornecedor de serviços
• Azure Logic Apps de inquilino único

Pré-requisitos

• Uma conta e subscrição do Azure. Se não tiver uma subscrição, inscreva-se numa conta do Azure gratuita.

• Conhecimentos básicos sobre o Azure Logic Apps de inquilino único, fluxos de trabalho de aplicações lógicas Standard, conectores e como utilizar o Visual Studio Code para criar fluxos de trabalho baseados em inquilinos únicos. Para obter mais informações, veja a seguinte documentação:

  • Inquilino único versus ambiente de serviço de integração e multi-inquilino para o Azure Logic Apps

  • Criar um fluxo de trabalho de integração com o Azure Logic Apps (Standard) de inquilino único – portal do Azure

• Visual Studio Code com a extensão do Azure Logic Apps (Standard) e outros pré-requisitos instalados. A sua instalação já deve incluir o pacote NuGet para Microsoft.Azure.Workflows.WebJobs.Extension.

  Nota

  Esta capacidade de criação está atualmente disponível apenas no Visual Studio Code.

• Uma conta, base de dados e contentor ou coleção do Azure Cosmos DB. Para obter mais informações, veja Início Rápido: Criar uma conta, base de dados, contentor e itens do Azure Cosmos DB a partir do portal do Azure.

Passos gerais

O seguinte destaque descreve os passos de alto nível para criar o conector de exemplo:

1. Criar um projeto de biblioteca de classes.

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

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

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

5. Instale o conector para utilização.

Criar o projeto da biblioteca de aulas

1. No Visual Studio Code, crie um projeto de biblioteca de classes .NET Core 3.1.

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

Implementar a interface do fornecedor de serviços

Para fornecer as operações para o conector incorporado de exemplo, no pacote NuGet Microsoft.Azure.Workflows.WebJobs.Extension , implemente os métodos para as seguintes interfaces. O diagrama seguinte mostra as interfaces com as implementações do método que o estruturador e o runtime do Azure Logic Apps esperam para um conector incorporado personalizado que tem um acionador baseado em Funções do Azure:

IServiceOperationsProvider

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

• GetService()

  O estruturador no Azure Logic Apps requer o método GetService() para obter os metadados de alto nível para o seu serviço personalizado, incluindo a descrição do serviço, parâmetros de entrada de ligação necessários no estruturador, capacidades, cor da marca, URL do ícone, entre outros.

• GetOperations()

  O estruturador no Azure Logic Apps requer o método GetOperations() para obter as operações implementadas pelo seu serviço personalizado. A lista de operações baseia-se no esquema swagger. O estruturador também utiliza os metadados de operação para compreender os parâmetros de entrada para operações específicas e gerar as saídas como tokens de propriedade, com base no esquema da saída de uma operação.

• GetBindingConnectionInformation()

  Se o acionador for um tipo de acionador baseado em Funções do Azure, o runtime no Azure Logic Apps requer o método GetBindingConnectionInformation() para fornecer as informações de parâmetros de ligação necessárias ao enlace do acionador Funções do Azure.

• InvokeOperation()

  Se o conector tiver ações, o runtime no Azure Logic Apps requer o método InvokeOperation() para chamar cada ação no conector que é executada durante a execução do fluxo de trabalho. Se o conector não tiver ações, não tem de implementar o método InvokeOperation( ).

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

Para obter mais informações sobre estes métodos e a respetiva implementação, veja estes métodos mais à frente neste artigo.

IServiceOperationsTriggerProvider

Pode adicionar ou expor um Funções do Azure acionador ou ação como acionador de fornecedor de serviços no conector incorporado personalizado. Para utilizar o tipo de acionador baseado em Funções do Azure e o mesmo enlace de Funções do Azure que o acionador do conector gerido do Azure, implemente os seguintes métodos para fornecer as informações de ligação e os enlaces de acionador, conforme exigido pelo Funções do Azure. Para obter mais informações, veja IServiceOperationsTriggerProvider.

• O método GetFunctionTriggerType() é necessário para devolver a cadeia que é igual ao parâmetro de tipo no Funções do Azure enlace do acionador.

• O GetFunctionTriggerDefinition() tem uma implementação predefinida, pelo que não precisa de implementar explicitamente este método. No entanto, se quiser atualizar o comportamento predefinido do acionador, como fornecer parâmetros adicionais que o estruturador não expõe, pode implementar este método e substituir o comportamento predefinido.

Métodos para implementar

As secções seguintes descrevem os métodos que o conector de exemplo implementa. Para obter o exemplo completo, veja Sample CosmosDbServiceOperationProvider.cs.

GetService()

O estruturador 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 estruturador requer o seguinte método para implementar as operações pelo seu serviço. Esta lista de operações baseia-se no esquema swagger.

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

GetBindingConnectionInformation()

Para utilizar o tipo de acionador baseado em Funções do Azure, o método seguinte fornece as informações dos parâmetros de ligação necessários ao enlace do acionador 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>();
}

InvokeOperation()

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

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

GetFunctionTriggerType()

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

O exemplo seguinte devolve a cadeia para o acionador "type": "cosmosDBTrigger"incorporado do Azure Cosmos DB, :

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

GetFunctionTriggerDefinition()

Este método tem uma implementação predefinida, pelo que não precisa de implementar explicitamente este método. No entanto, se quiser atualizar o comportamento predefinido do acionador, como fornecer parâmetros adicionais que o estruturador não expõe, pode implementar este método e substituir o comportamento predefinido.

Registar os seus conectores

Para carregar a extensão de conector incorporada personalizada durante o processo de início do Funções do Azure runtime, tem de adicionar o Funções do Azure registo da extensão como tarefa de arranque e registar o conector como um fornecedor de serviços na lista de fornecedores de serviços. Com base no tipo de dados de que o acionador incorporado precisa como entradas, adicione opcionalmente o conversor. Este exemplo converte o tipo de dados Documento para documentos do Azure Cosmos DB numa matriz JObject .

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

Criar a tarefa de arranque

1. Crie uma classe de arranque com o atributo de assemblagem denominado [assembly:WebJobsStartup].

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

   Por exemplo, o fragmento de código seguinte mostra a implementação da classe de arranque do conector do Azure Cosmos DB incorporado de exemplo:

   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 obter mais informações, veja Registar serviços – Utilizar a injeção de dependências no .NET Funções do Azure.

Registar o fornecedor de serviços

Agora, registe a implementação do fornecedor de serviços como uma extensão Funções do Azure com o motor do Azure Logic Apps. Este exemplo utiliza o acionador incorporado do Azure Cosmos DB para Funções do Azure como um novo acionador. Este exemplo também regista o novo fornecedor de serviços do Azure Cosmos DB para uma lista existente de fornecedores de serviços, que já faz parte da extensão do Azure Logic Apps. Para obter mais informações, veja Registar extensões de enlace Funções do 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);
      }
   }
}

Adicionar um conversor

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

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

Diagrama da biblioteca de classes para classes implementadas

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

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

Instalar o conector

Para adicionar a referência nuGet da secção anterior, no pacote de extensões com o nome Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, atualize o ficheiro extensions.json . Para obter mais informações, aceda ao repositório Azure/logicapps-connector-extensions e reveja o script do PowerShell com o nome add-extension.ps1.

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

2. No Visual Studio Code, que deve ter a extensão Azure Logic Apps (Standard) para Visual Studio Code instalada, crie um projeto de aplicação lógica e instale o pacote de extensão com o seguinte comando do PowerShell:

   PowerShell

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

   Em alternativa, no diretório do projeto da aplicação lógica com uma linha de comandos do PowerShell, execute o script do PowerShell com o nome add-extension.ps1:

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

   Bash

   Para utilizar o Bash, no diretório do projeto da aplicação lógica, execute o script do PowerShell com o seguinte comando:

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

   Se a extensão do conector incorporado personalizado tiver sido instalada com êxito, obterá um resultado 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 func.exe processo estiver em execução, certifique-se de que fecha ou sai desse processo antes de avançar para o passo seguinte.

Testar o conector

1. No Visual Studio Code, abra a aplicação lógica Standard e o fluxo de trabalho em branco no estruturador.

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

3. Na caixa de pesquisa de operações, selecione Incorporado. Na caixa de pesquisa, introduza cosmos db.

   O seletor de operações mostra o conector incorporado personalizado e o acionador, por exemplo:

   

4. Na lista Acionadores , selecione o acionador incorporado personalizado para iniciar o 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 da ligação	Yes	<Azure-Cosmos-DB-connection-name>	O nome da ligação do Azure Cosmos DB a criar
   Cadeia de Ligação	Yes	<Azure Cosmos DB-DB-connection-string>	A cadeia de ligação da coleção de bases de dados do Azure Cosmos DB ou da coleção de concessão onde pretende adicionar cada novo documento recebido.

   

6. Quando concluir, selecione Criar.

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

   Propriedade	Necessário	Valor	Descrição
   Nome da base de dados	Yes	<Azure-Cosmos-DB-database-name>	O nome da base de dados do Azure Cosmos DB a utilizar
   Nome da coleção	Yes	<Azure-Cosmos-DB-collection-name>	O nome da coleção do Azure Cosmos DB onde pretende adicionar cada novo documento recebido.

   

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

   {
      "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 ao seguinte exemplo:

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

8. No Visual Studio Code, no menu Executar , selecione Iniciar Depuração. (Prima F5)

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

   

Passos seguintes

• Origem do conector do Azure Cosmos DB incorporado de exemplo – Extensões do Conector do Azure Logic Apps

• Acionador incorporado do Service Bus: processamento de batches e sessões