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

Aplica-se a: Aplicativos Lógicos do Azure (Padrão)

Se precisar de conectores que não estão disponíveis nos fluxos de trabalho do aplicativo lógico Padrão, você pode criar seus próprios conectores internos usando o mesmo modelo de extensibilidade usado pelos conectores internos baseados em provedor de serviços disponíveis para fluxos de trabalho padrão em Aplicativos Lógicos do Azure de locatário único. Este modelo de extensibilidade baseia-se no modelo de extensibilidade do Azure Functions.

Este artigo mostra como criar um exemplo de conector interno personalizado do Azure Cosmos DB, que tem um único gatilho baseado no Azure Functions e nenhuma ação. O gatilho é acionado quando um novo documento é adicionado à coleção de concessão ou contêiner no Azure Cosmos DB e, em seguida, executa um fluxo de trabalho que usa a carga de entrada como o documento do Azure Cosmos DB.

Operação	Detalhes da operação	Description
Acionador	Quando um documento é recebido	Essa operação de gatilho é executada quando uma operação de inserção acontece no banco de dados e na coleção especificados do Azure Cosmos DB.
Ação	Nenhuma	Este conector não define nenhuma operação de ação.

Este conector de exemplo usa a mesma funcionalidade que o gatilho do Azure Cosmos DB para o Azure Functions, que se baseia em gatilhos e associações do Azure Functions. Para obter o exemplo completo, consulte Exemplo de conector interno personalizado do Azure Cosmos DB - Azure Logic Apps Connector Extensions.

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

• Conectores personalizados para aplicativos lógicos padrão
• Conectores integrados baseados em provedor de serviços
• Aplicativos Lógicos do Azure de locatário único

Pré-requisitos

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

• Conhecimento básico sobre Aplicativos Lógicos do Azure de locatário único, fluxos de trabalho de aplicativos lógicos padrão, conectores e como usar o Visual Studio Code para criar fluxos de trabalho baseados em locatário único. Para obter mais informações, consulte a seguinte documentação:

  • Locatário único versus multilocatário nos Aplicativos Lógicos do Azure

  • Criar um fluxo de trabalho de integração com Aplicativos Lógicos do Azure de locatário único (Padrão) - Portal do Azure

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

  Nota

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

• Uma conta, um banco de dados e um contêiner ou coleção do Azure Cosmos DB. Para obter mais informações, consulte Guia de início rápido: criar uma conta, banco de dados, contêiner e itens do Azure Cosmos DB no portal do Azure.

Etapas de alto nível

A estrutura de tópicos a seguir descreve as etapas de alto nível para criar o conector de exemplo:

1. Crie um projeto de biblioteca de classes.

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

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

4. Registre seu conector interno personalizado com a extensão de tempo de execução do Azure Functions.

5. Instale o conector para uso.

Crie seu projeto de biblioteca de classes

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

2. Em seu projeto, adicione o pacote NuGet chamado Microsoft.Azure.Workflows.WebJobs.Extension como uma referência do NuGet.

Implementar a interface do provedor de serviços

Para fornecer as operações para o conector interno de exemplo, no pacote NuGet Microsoft.Azure.Workflows.WebJobs.Extension , implemente os métodos para as interfaces a seguir. O diagrama a seguir mostra as interfaces com as implementações de método que o designer e o tempo de execução dos Aplicativos Lógicos do Azure esperam para um conector interno personalizado que tenha um gatilho baseado no Azure Functions:

IServiceOperationsProvider

Essa interface inclui os seguintes métodos que fornecem o manifesto de operação e executam as tarefas específicas do provedor de serviços ou a lógica de negócios real em seu conector interno personalizado. Para obter mais informações, consulte IServiceOperationsProvider.

• GetService()

  O designer nos Aplicativos Lógicos do Azure requer o método GetService() para recuperar os metadados de alto nível para seu serviço personalizado, incluindo a descrição do serviço, os parâmetros de entrada de conexão necessários no designer, os recursos, a cor da marca, a URL do ícone e assim por diante.

• GetOperations()

  O designer nos Aplicativos Lógicos do Azure requer o método GetOperations() para recuperar as operações implementadas pelo seu serviço personalizado. A lista de operações é baseada no esquema 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 tokens de propriedade, com base no esquema da saída para uma operação.

• GetBindingConnectionInformation()

  Se o gatilho for um tipo de gatilho baseado no Azure Functions, o tempo de execução nos Aplicativos Lógicos do Azure exigirá o método GetBindingConnectionInformation() para fornecer as informações de parâmetros de conexão necessárias para a associação de gatilho do Azure Functions.

• InvokeOperation()

  Se o conector tiver ações, o tempo de execução nos Aplicativos Lógicos do Azure exigirá 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 será necessário implementar o método InvokeOperation( ).

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

Para obter mais informações sobre esses métodos e sua implementação, revise esses métodos posteriormente neste artigo.

IServiceOperationsTriggerProvider

Você pode adicionar ou expor um gatilho ou ação do Azure Functions como um gatilho de provedor de serviços em seu conector interno personalizado. Para usar o tipo de gatilho baseado no Azure Functions e a mesma vinculação do Azure Functions que o gatilho do conector gerenciado do Azure, implemente os seguintes métodos para fornecer as informações de conexão e as associações de gatilho, conforme exigido pelo Azure Functions. Para obter mais informações, consulte IServiceOperationsTriggerProvider.

• O método GetFunctionTriggerType() é necessário para retornar a cadeia de caracteres que é igual ao parâmetro type na associação de gatilho do Azure Functions.

• O GetFunctionTriggerDefinition() tem uma implementação padrão, portanto, você não precisa implementar explicitamente esse método. No entanto, se você quiser atualizar o comportamento padrão do gatilho, como fornecer parâmetros extras que o designer não expõe, você pode implementar esse método e substituir o comportamento padrão.

Métodos de implementação

As seções a seguir descrevem os métodos que o conector de exemplo implementa. Para obter a amostra completa, consulte Amostra CosmosDbServiceOperationProvider.cs.

Importante

Quando você tiver informações confidenciais, como cadeias de conexão que incluem nomes de usuário e senhas, certifique-se de usar o fluxo de autenticação mais seguro disponível. Por exemplo, a Microsoft recomenda que você autentique o acesso aos recursos do Azure com uma identidade gerenciada quando o suporte estiver disponível e atribua uma função que tenha o menor privilégio necessário.

Se esse recurso não estiver disponível, certifique-se de proteger as cadeias de conexão por meio de outras medidas, como o Cofre da Chave do Azure, que você pode usar com as configurações do aplicativo. Em seguida, você pode fazer referência direta a cadeias de caracteres seguras, como cadeias de conexão e chaves. Semelhante aos modelos ARM, onde você pode definir variáveis de ambiente no momento da implantação, você pode definir as configurações do aplicativo dentro da definição do fluxo de trabalho do aplicativo lógico. Em seguida, você pode capturar valores de infraestrutura gerados dinamicamente, como pontos de extremidade de conexão, cadeias de caracteres de armazenamento e muito mais. Para obter mais informações, consulte Tipos de aplicativo para a plataforma de identidade da Microsoft.

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 obter as operações implementadas pelo seu serviço. Esta lista de operações é baseada no esquema Swagger.

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

GetBindingConnectionInformation()

Para usar o tipo de gatilho baseado no Azure Functions, o método a seguir fornece as informações de parâmetros de conexão necessárias para a associação de gatilho do Azure Functions.

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

InvokeOperation()

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

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

GetFunctionTriggerType()

Para usar um gatilho baseado no Azure Functions como um gatilho em seu conector, você precisa retornar a cadeia de caracteres que é igual ao parâmetro type na associação de gatilho do Azure Functions.

O exemplo a seguir retorna a cadeia de caracteres para o gatilho interno do Azure Cosmos DB pronto para uso, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Esse método tem uma implementação padrão, portanto, você não precisa implementar explicitamente esse método. No entanto, se você quiser atualizar o comportamento padrão do gatilho, como fornecer parâmetros extras que o designer não expõe, você pode implementar esse método e substituir o comportamento padrão.

Registar os seus conectores

Para carregar sua extensão de conector interna personalizada durante o processo de início do tempo de execução do Azure Functions, você precisa adicionar o registro da extensão do Azure Functions como um trabalho de inicialização e registrar seu conector como um provedor de serviços na lista de provedores de serviços. Com base no tipo de dados que seu gatilho interno precisa como entradas, opcionalmente adicione o conversor. Este exemplo converte o tipo de dados Document para documentos do Azure Cosmos DB em uma matriz JObject .

As seções a seguir mostram como registrar seu conector interno personalizado como uma extensão do Azure Functions.

Criar o trabalho de inicialização

1. Crie uma classe de inicialização usando o atributo assembly chamado [assembly:WebJobsStartup].

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

   Por exemplo, o trecho de código a seguir mostra a implementação da classe de inicialização para o exemplo de conector interno personalizado do 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 obter mais informações, consulte Serviços de registro - Usar injeção de dependência no .NET Azure Functions.

Registar o prestador de serviços

Agora, registre a implementação do provedor de serviços como uma extensão do Azure Functions com o mecanismo de Aplicativos Lógicos do Azure. Este exemplo usa o gatilho interno do Azure Cosmos DB para o Azure Functions como um novo gatilho. Este exemplo também registra o novo provedor de serviços do Azure Cosmos DB para uma lista existente de provedores de serviços, que já faz parte da extensão de Aplicativos Lógicos do Azure. Para obter mais informações, consulte Registrar extensões de vinculação do 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);
      }
   }
}

Adicionar um conversor

Os Aplicativos Lógicos do Azure têm uma maneira genérica de lidar com qualquer gatilho interno do Azure Functions usando a matriz JObject . No entanto, se você quiser converter a lista somente leitura de documentos do Azure Cosmos DB em uma matriz JObject , poderá adicionar um conversor. Quando o conversor estiver pronto, registre-o 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 de biblioteca de classes para classes implementadas

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

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

Instale o conector

Para adicionar a referência NuGet da seção anterior, no pacote de extensão chamado Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, atualize o arquivo extensions.json . Para obter mais informações, vá para o repositório Azure/logicapps-connector-extensions e revise o script do PowerShell chamado add-extension.ps1.

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

2. No Visual Studio Code, que deve ter a extensão Azure Logic Apps (Standard) for Visual Studio Code instalada, crie um projeto de aplicativo lógico e instale o pacote de extensão usando o seguinte comando do PowerShell:

   PowerShell

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

   Como alternativa, no diretório do seu projeto de aplicativo lógico usando um prompt do PowerShell, execute o script do PowerShell chamado add-extension.ps1:

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

   Bash

   Para usar o Bash em vez disso, no diretório do seu projeto de aplicativo lógico, 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 para o conector interno personalizado foi instalada com êxito, você obtém uma saída semelhante ao exemplo a seguir:

   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 processo func.exe estiver em execução, certifique-se de fechar ou sair desse processo antes de continuar para a próxima etapa.

Testar o conector

1. No Visual Studio Code, abra seu aplicativo lógico padrão e fluxo de trabalho em branco no designer.

2. Na superfície do designer, 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, digite cosmos db.

   O seletor de operações mostra seu conector e gatilho internos personalizados, por exemplo:

   

4. Na lista Triggers, selecione seu gatilho interno personalizado para iniciar seu fluxo de trabalho.

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

   Property	Necessário	Valor	Description
   Nome da ligação	Sim	<Azure-Cosmos-DB-connection-name>	O nome da conexão do Azure Cosmos DB a ser criada
   Cadeia de Ligação	Sim	<Azure Cosmos DB-DB-connection-string>	A cadeia de conexão para a coleção de banco de dados do Azure Cosmos DB ou coleção de concessão onde você deseja adicionar cada novo documento recebido.

   

6. Quando tiver terminado, selecione Criar.

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

   Property	Necessário	Valor	Description
   Nome da base de dados	Sim	<Azure-Cosmos-DB-database-name>	O nome do banco de dados do Azure Cosmos DB a ser usado
   Nome da coleção	Sim	<Azure-Cosmos-DB-collection-name>	O nome da coleção do Azure Cosmos DB onde você deseja adicionar cada novo documento recebido.

   

   Neste exemplo, na visualização de código, a definição de fluxo de trabalho, que está no arquivo workflow.json , tem um triggers objeto JSON que parece semelhante ao exemplo a seguir:

   {
      "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 conexão, que está no arquivo connections.json , tem um serviceProviderConnections objeto JSON que parece semelhante ao exemplo a seguir:

   {
      "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. (Pressione F5)

9. Para acionar seu fluxo de trabalho, no portal do Azure, abra sua conta do Azure Cosmos DB. No menu da conta, selecione Data Explorer. Navegue até o banco de dados e a coleção que você especificou no gatilho. Adicione um item à coleção.

   

Próximos passos

• Origem para exemplo de conector interno personalizado do Azure Cosmos DB - Azure Logic Apps Connector Extensions

• Gatilho interno do Service Bus: processamento em lote e manipulação de sessão