Criar conectores internos personalizados para aplicativos lógicos Standard em Aplicativos Lógicos do Azure de locatário único

  • Artigo

Aplica-se a: Aplicativos Lógicos do Azure (Standard)

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

Este artigo mostra como criar um conector interno personalizado de exemplo do Azure Cosmos DB, que tem um só gatilho baseado em 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 executa um fluxo de trabalho que usa o conteúdo de entrada como o documento do Azure Cosmos DB.

Operação Detalhes da operação Descrição
Gatilho Quando um documento é recebido Essa operação de gatilho é executada quando uma operação de inserção ocorre no banco de dados e na coleção especificados do Azure Cosmos DB.
Ação Nenhum Esse conector não define operações de ação.

Este conector de exemplo usa a mesma funcionalidade que o gatilho de BD Cosmos do Azure para Azure Functions, que se baseia em gatilhos e associações do Azure Functions. Para obter o exemplo completo, examine o conector interno Azure Cosmos DB de exemplo – Extensões do Conector dos Aplicativos Lógicos do Azure.

Para saber mais, consulte a seguinte documentação:

Pré-requisitos

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 o 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 runtime Azure Functions.

  5. Instalar o conector para uso.

Criar seu projeto de biblioteca de classes

  1. Em 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 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 seguinte diagrama mostra as interfaces com as implementações de método que o designer de Aplicativos Lógicos do Azure e o runtime esperam para um conector interno personalizado que tem um gatilho baseado no Azure Functions:

Diagrama de classe conceitual mostrando a implementação do método para um conector interno personalizado do Azure Cosmos DB de exemplo.

IServiceOperationsProvider

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

  • GetService()

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

  • GetOperations()

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

  • GetBindingConnectionInformation()

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

  • InvokeOperation()

    Se o conector tiver ações, o runtime nos Aplicativos Lógicos do Azure requer o método InvokeOperation() será usado pelo runtime para chamar cada ação no conector que for executada durante a execução do fluxo de trabalho. Se o conector não tiver ações, você não precisará 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 fins de integridade.

Para obter mais informações sobre esses métodos e a implementação deles, examine-os posteriormente neste artigo.

IServiceOperationsTriggerProvider

Você pode adicionar ou expor um gatilho ou ação do Azure Functions como um gatilho do provedor de serviços em seu conector interno personalizado. Para usar o tipo de gatilho baseado em Azure Functions e a mesma associação do Azure Functions que o gatilho do conector gerenciado do Azure, implemente os métodos a seguir para fornecer as informações de conexão e disparar associações conforme exigido pelo Azure Functions. Para obter mais informações, examine 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ê poderá implementar esse método e substituir o comportamento padrão.

Métodos a serem implementados

As seções a seguir descrevem os métodos que o conector de exemplo implementa. Para obter o exemplo completo, examine Sample CosmosDbServiceOperationProvider.cs.

Importante

Quando houver informações confidenciais, como cadeias de conexão que incluam 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 a recursos do Azure com uma identidade gerenciada quando houver suporte disponível, e atribua uma função que tenha o mínimo de privilégios necessários.

Se essa funcionalidade estiver indisponível, certifique-se de proteger as cadeias de conexão por meio de outras medidas, como o Azure Key Vault, 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. De modo semelhante aos modelos do ARM, em que é possível definir variáveis de ambiente no momento da implantação, você pode definir as configurações de aplicativo na definição de fluxo de trabalho do aplicativo lógico. Em seguida, você pode capturar os valores da infraestrutura gerados dinamicamente, como pontos de extremidade de conexão, cadeias de caracteres de armazenamento, entre outros. Para obter mais informações, confira 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 seu serviço:

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

GetOperations()

O designer requer esse método para obter as operações implementadas pelo seu serviço. A 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 fornecerá as informações de parâmetros de conexão necessárias à 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 do 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 em 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, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Este método tem uma implementação padrão, portanto, você não precisa implementá-lo explicitamente. 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ê poderá implementar esse método e substituir o comportamento padrão.

Registrar seu conector

Para carregar sua extensão de conector interno personalizado durante o processo de início do runtime do Azure Functions, você precisa adicionar o registro de 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 o gatilho interno precisa como entradas, opcionalmente, adicione o conversor. Este exemplo converte o tipo de dados Documento 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 de 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 snippet de código a seguir mostra a implementação da classe de inicialização para o conector interno personalizado de exemplo 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, examine os serviços de Registro – Use a injeção de dependência no .NET Azure Functions.

Registrar o provedor de serviços

Agora, registre a implementação do provedor de serviços como uma extensão de Azure Functions com o mecanismo de Aplicativos Lógicos do Azure. Este exemplo usa o gatilho de do Azure Cosmos DB interno para 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 Aplicativos Lógicos do Azure. Para saber mais, consulte Registrar extensões de associaçã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

Aplicativos Lógicos do Azure tem 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 banco de dados em uma matriz JObject, poderá adicionar um conversor. Quando o conversor estiver pronto, registre 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, examine o diagrama de classe a seguir que mostra a implementação de todas as classes no pacote de extensão Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll:

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Diagrama de mapa de códigos conceitual que mostra a implementação completa da classe.

Instalar o conector

Para adicionar a referência de NuGet da seção anterior, no pacote de extensão denominado Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, atualize o arquivo extensions.json. Para obter mais informações, acesse o repositório Azure/logicapps-connector-extensions e examine 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 de Aplicativos Lógicos do Azure (Standard) para 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, 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 do conector interno personalizado tiver sido instalada com êxito, você obterá 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, feche ou saia desse processo antes de continuar para a próxima etapa.

Testar sua conexão

  1. Em Visual Studio Code, abra o aplicativo lógico Standard e o 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 do designer, selecione Interno. Na caixa de pesquisa, insira cosmos db.

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

    Captura de tela mostrando o Visual Studio Code e o designer de um fluxo de trabalho de aplicativo lógico Standard com o novo conector interno personalizado do Azure Cosmos DB.

  4. Na lista Gatilhos, selecione o gatilho interno personalizado para iniciar o fluxo de trabalho.

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

    Propriedade Obrigatório Valor Descrição
    Nome da conexão Yes <Azure-Cosmos-DB-connection-name> O nome da conexão do Azure Cosmos DB a ser criada
    Cadeia de Conexão Sim <Azure Cosmos DB-DB-connection-string> A cadeia de conexão da coleção de banco de dados do Azure Cosmos DB ou coleção de concessão em que você deseja adicionar cada novo documento recebido.

    Captura de tela mostrando o painel de conexão ao usar o conector pela primeira vez.

  6. Quando terminar, selecione Criar.

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

    Propriedade Obrigatório Valor Descrição
    Nome do banco 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 em que você deseja adicionar cada novo documento recebido.

    Captura de tela mostrando o painel de propriedades de gatilho.

    Para este exemplo, no modo de exibição de código, a definição de fluxo de trabalho, que está no arquivo workflow.json, tem um objeto JSON triggers que aparece 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 objeto JSON serviceProviderConnections que aparece 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 disparar 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.

    Captura de tela mostrando o portal do Azure, a conta do Azure Cosmos DB e Data Explorer abertos no banco de dados e na coleção especificados.

Próximas etapas