Aangepaste ingebouwde connectors maken voor standaardlogica-apps in Azure Logic Apps met enkele tenant

Als u connectors nodig hebt die niet beschikbaar zijn in standaardwerkstromen voor logische apps, kunt u uw eigen ingebouwde connectors maken met hetzelfde uitbreidbaarheidsmodel dat wordt gebruikt door de ingebouwde connectors van de serviceprovider die beschikbaar zijn voor Standard-werkstromen in Azure Logic Apps met één tenant. Dit uitbreidbaarheidsmodel is gebaseerd op het Azure Functions uitbreidbaarheidsmodel.

In dit artikel wordt beschreven hoe u een voorbeeld van een aangepaste ingebouwde Cosmos DB-connector maakt, die één op Azure Functions gebaseerde trigger heeft en geen acties. De trigger wordt geactiveerd wanneer een nieuw document wordt toegevoegd aan de leaseverzameling of container in Cosmos DB en vervolgens een werkstroom uitvoert die gebruikmaakt van de invoerpayload als het Cosmos-document.

Bewerking Bewerkingsdetails Description
Trigger Wanneer een document wordt ontvangen Deze triggerbewerking wordt uitgevoerd wanneer een invoegbewerking plaatsvindt in de opgegeven Cosmos DB-database en -verzameling.
Actie Geen Deze connector definieert geen actiebewerkingen.

Deze voorbeeldconnector gebruikt dezelfde functionaliteit als de Azure Cosmos DB-trigger voor Azure Functions, die is gebaseerd op Azure Functions triggers en bindingen. Bekijk voor het volledige voorbeeld de aangepaste, ingebouwde Cosmos DB-connector sample Azure Logic Apps Connector Extensions.

Raadpleeg de volgende documentatie voor meer informatie:

Vereisten

Stappen op hoog niveau

In het volgende overzicht worden de stappen op hoog niveau beschreven voor het bouwen van de voorbeeldconnector:

  1. Maak een klassebibliotheekproject.

  2. Voeg in uw project het NuGet-pakket Microsoft.Azure.Workflows.WebJobs.Extension toe als nuGet-verwijzing.

  3. Geef de bewerkingen voor uw ingebouwde connector op met behulp van het NuGet-pakket om de methoden voor de interfaces met de naam IServiceOperationsProvider en IServiceOperationsTriggerProvider te implementeren.

  4. Registreer uw aangepaste ingebouwde connector met de Azure Functions runtime-extensie.

  5. Installeer de connector voor gebruik.

Uw klasbibliotheekproject maken

  1. Maak in Visual Studio Code een .NET Core 3.1-klassebibliotheekproject.

  2. Voeg in uw project het NuGet-pakket met de naam Microsoft.Azure.Workflows.WebJobs.Extension toe als nuGet-verwijzing.

De interface van de serviceprovider implementeren

Als u de bewerkingen voor de ingebouwde voorbeeldconnector wilt leveren, implementeert u in het NuGet-pakket Microsoft.Azure.Workflows.WebJobs.Extension de methoden voor de volgende interfaces. In het volgende diagram ziet u de interfaces met de methode-implementaties die de Azure Logic Apps designer en runtime verwachten voor een aangepaste ingebouwde connector met een op Azure Functions gebaseerde trigger:

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

IServiceOperationsProvider

Deze interface bevat de volgende methoden die het bewerkingsmanifest bieden en de specifieke taken of de werkelijke bedrijfslogica van uw serviceprovider uitvoeren in uw aangepaste ingebouwde connector. Raadpleeg IServiceOperationsProvider voor meer informatie.

  • GetService()

    De ontwerper in Azure Logic Apps vereist de Methode GetService() om de metagegevens op hoog niveau voor uw aangepaste service op te halen, waaronder de servicebeschrijving, verbindingsinvoerparameters die vereist zijn voor de ontwerper, mogelijkheden, merkkleur, pictogram-URL, enzovoort.

  • GetOperations()

    De ontwerpfunctie in Azure Logic Apps vereist de methode GetOperations() om de bewerkingen op te halen die door uw aangepaste service zijn geïmplementeerd. De lijst met bewerkingen is gebaseerd op het Swagger-schema. De ontwerpfunctie gebruikt ook de metagegevens van de bewerking om inzicht te hebben in de invoerparameters voor specifieke bewerkingen en om de uitvoer als eigenschapstokens te genereren op basis van het schema van de uitvoer voor een bewerking.

  • GetBindingConnectionInformation()

    Als uw trigger een op Azure Functions gebaseerd triggertype is, vereist de runtime in Azure Logic Apps de methode GetBindingConnectionInformation() om de vereiste verbindingsparameters op te geven aan de Azure Functions triggerbinding.

  • InvokeOperation()

    Als uw connector acties heeft, vereist de runtime in Azure Logic Apps de methode InvokeOperation() om elke actie aan te roepen in uw connector die wordt uitgevoerd tijdens de uitvoering van de werkstroom. Als uw connector geen acties heeft, hoeft u de methode InvokeOperation() niet te implementeren.

    In dit voorbeeld heeft de aangepaste ingebouwde Cosmos DB-connector geen acties. De methode is echter opgenomen in dit voorbeeld voor volledigheid.

Raadpleeg deze methoden verderop in dit artikel voor meer informatie over deze methoden en hun implementatie.

IServiceOperationsTriggerProvider

U kunt een Azure Functions trigger of actie toevoegen of beschikbaar maken als een serviceprovidertrigger in uw aangepaste ingebouwde connector. Als u het triggertype op basis van Azure Functions en dezelfde Azure Functions binding wilt gebruiken als de trigger voor de beheerde Azure-connector, implementeert u de volgende methoden om de verbindingsgegevens en triggerbindingen op te geven, zoals vereist door Azure Functions. Raadpleeg IServiceOperationsTriggerProvider voor meer informatie.

  • De methode GetFunctionTriggerType() is vereist om de tekenreeks te retourneren die hetzelfde is als de typeparameter in de Azure Functions triggerbinding.

  • GetFunctionTriggerDefinition() heeft een standaardimplementatie, dus u hoeft deze methode niet expliciet te implementeren. Als u echter het standaardgedrag van de trigger wilt bijwerken, zoals extra parameters opgeven die de ontwerper niet beschikbaar maakt, kunt u deze methode implementeren en het standaardgedrag overschrijven.

Methoden om te implementeren

In de volgende secties worden de methoden beschreven die door de voorbeeldconnector worden geïmplementeerd. Raadpleeg Sample CosmosDbServiceOperationProvider.cs voor het volledige voorbeeld.

GetService()

De ontwerpfunctie vereist de volgende methode om de beschrijving op hoog niveau voor uw service op te halen:

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

GetOperations()

De ontwerpfunctie vereist de volgende methode om de bewerkingen op te halen die door uw service worden geïmplementeerd. Deze lijst met bewerkingen is gebaseerd op het Swagger-schema.

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

GetBindingConnectionInformation()

Als u het triggertype op basis van Azure Functions wilt gebruiken, bevat de volgende methode de vereiste informatie over verbindingsparameters voor de Azure Functions triggerbinding.

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

InvokeOperation()

De aangepaste ingebouwde Cosmos DB-voorbeeldconnector heeft geen acties, maar de volgende methode is opgenomen voor volledigheid:

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

GetFunctionTriggerType()

Als u een op Azure Functions gebaseerde trigger wilt gebruiken als trigger in uw connector, moet u de tekenreeks retourneren die hetzelfde is als de typeparameter in de Azure Functions triggerbinding.

In het volgende voorbeeld wordt de tekenreeks geretourneerd voor de standaard ingebouwde Azure Cosmos DB-trigger: "type": "cosmosDBTrigger"

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

GetFunctionTriggerDefinition()

Deze methode heeft een standaardimplementatie, dus u hoeft deze methode niet expliciet te implementeren. Als u echter het standaardgedrag van de trigger wilt bijwerken, zoals extra parameters opgeven die de ontwerper niet beschikbaar maakt, kunt u deze methode implementeren en het standaardgedrag overschrijven.

De connector registreren

Als u de aangepaste ingebouwde connectorextensie wilt laden tijdens het Azure Functions runtime-startproces, moet u de Azure Functions-extensieregistratie toevoegen als opstarttaak en uw connector registreren als serviceprovider in de lijst met serviceproviders. Voeg eventueel het conversieprogramma toe op basis van het type gegevens dat uw ingebouwde trigger nodig heeft als invoer. In dit voorbeeld wordt het gegevenstype Document voor Cosmos DB-documenten geconverteerd naar een JObject-matrix .

In de volgende secties ziet u hoe u uw aangepaste ingebouwde connector registreert als een Azure Functions-extensie.

De opstarttaak maken

  1. Maak een opstartklasse met behulp van het assemblykenmerk met de naam [assembly:WebJobsStartup].

  2. Implementeer de interface IWebJobsStartup . Registreer in de methode Configure() de extensie en injecteer de serviceprovider.

    In het volgende codefragment ziet u bijvoorbeeld de implementatie van de opstartklasse voor de aangepaste ingebouwde Cosmos DB-voorbeeldconnector:

    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>();
          }
       }
    }
    

    Zie Register-services - afhankelijkheidsinjectie gebruiken in .NET Azure Functions voor meer informatie.

De serviceprovider registreren

Registreer nu de implementatie van de serviceprovider als een Azure Functions-extensie bij de Azure Logic Apps-engine. In dit voorbeeld wordt de ingebouwde Azure Cosmos DB-trigger gebruikt voor Azure Functions als een nieuwe trigger. In dit voorbeeld wordt ook de nieuwe Cosmos DB-serviceprovider geregistreerd voor een bestaande lijst met serviceproviders, die al deel uitmaakt van de Azure Logic Apps-extensie. Zie Register Azure Functions bindingsextensies voor meer informatie.

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);
      }
   }
}

Een conversieprogramma toevoegen

Azure Logic Apps heeft een algemene manier om alle Azure Functions ingebouwde trigger te verwerken met behulp van de JObject-matrix. Als u echter de alleen-lezenlijst met Azure Cosmos DB-documenten wilt converteren naar een JObject-matrix , kunt u een conversieprogramma toevoegen. Wanneer het conversieprogramma gereed is, registreert u het conversieprogramma als onderdeel van ExtensionConfigContext , zoals eerder in dit voorbeeld wordt weergegeven:

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

Klassebibliotheekdiagram voor geïmplementeerde klassen

Als u klaar bent, bekijkt u het volgende klassediagram waarin de implementatie voor alle klassen in de Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll extensiebundel wordt weergegeven:

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Conceptual code map diagram that shows complete class implementation.

Uw connector installeren

Als u de NuGet-verwijzing uit de vorige sectie wilt toevoegen, werkt u in de extensiebundel met de naam Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dllhet bestand extensions.json bij. Ga voor meer informatie naar de opslagplaats azure/logicapps-connector-extensions en bekijk het PowerShell-script met de naam add-extension.ps1.

  1. Werk de extensiebundel bij om de aangepaste ingebouwde connector op te nemen.

  2. In Visual Studio Code, waarop de Azure Logic Apps (Standard) moet zijn geïnstalleerd voor Visual Studio Code-extensie, maakt u een logic app-project en installeert u het extensiepakket met behulp van de volgende PowerShell-opdracht:

    PowerShell

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

    U kunt ook vanuit de map van uw logische app-project met behulp van een PowerShell-prompt het PowerShell-script met de naam add-extension.ps1uitvoeren:

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

    Bash

    Als u in plaats daarvan Bash wilt gebruiken, voert u vanuit de map van uw logische app-project het PowerShell-script uit met de volgende opdracht:

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

    Als de extensie voor uw aangepaste ingebouwde connector is geïnstalleerd, krijgt u uitvoer die lijkt op het volgende voorbeeld:

    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. Als eenfunc.exe proces wordt uitgevoerd, moet u dat proces sluiten of afsluiten voordat u verdergaat met de volgende stap.

Uw connector testen

  1. Open in Visual Studio Code uw logische standaard-app en lege werkstroom in de ontwerpfunctie.

  2. Selecteer op het ontwerpoppervlak Een bewerking kiezen om de connectorbewerkingenkiezer te openen.

  3. Selecteer ingebouwd onder het zoekvak voor bewerkingen. Voer in het zoekvak cosmos db in.

    In de bewerkingskiezer ziet u uw aangepaste ingebouwde connector en trigger, bijvoorbeeld:

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

  4. Selecteer in de lijst Triggers uw aangepaste ingebouwde trigger om uw werkstroom te starten.

  5. Geef in het verbindingsvenster de volgende eigenschapswaarden op om een verbinding te maken, bijvoorbeeld:

    Eigenschap Vereist Waarde Beschrijving
    Verbindingsnaam Yes <Cosmos-DB-connection-name> De naam voor de Cosmos DB-verbinding die moet worden gemaakt
    Verbindingsreeks Yes <Cosmos-DB-connection-string> De connection string voor de Azure Cosmos DB-databaseverzameling of leaseverzameling waar u elk nieuw ontvangen document wilt toevoegen.

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

  6. Selecteer Maken als u klaar bent.

  7. Geef in het deelvenster Triggereigenschappen de volgende eigenschapswaarden op voor uw trigger, bijvoorbeeld:

    Eigenschap Vereist Waarde Beschrijving
    Databasenaam Yes <Cosmos-DB-databasenaam> De naam voor de Cosmos DB-database die moet worden gebruikt
    Naam van verzameling Yes <Naam van Cosmos-DB-verzameling> De naam voor de Cosmos DB-verzameling waaraan u elk nieuw ontvangen document wilt toevoegen.

    Screenshot showing the trigger properties pane.

    Voor dit voorbeeld heeft de werkstroomdefinitie in de codeweergave, die zich in het bestand workflow.json bevindt, een triggers JSON-object dat lijkt op het volgende voorbeeld:

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

    De verbindingsdefinitie, die zich in het bestand connections.json bevindt, heeft een serviceProviderConnections JSON-object dat lijkt op het volgende voorbeeld:

    {
       "serviceProviderConnections": {
          "cosmosDb": {
             "parameterValues": {
                "connectionString": "@appsetting('cosmosDb_connectionString')"
             },
             "serviceProvider": {
                "id": "/serviceProviders/CosmosDb"
             },
             "displayName": "myCosmosDbConnection"
          }
       },
       "managedApiConnections": {}
    }
    
  8. Selecteer in Visual Studio Code in het menu UitvoerenStartmenu Foutopsporing. (Druk op F5)

  9. Als u uw werkstroom wilt activeren, opent u in de Azure Portal uw Azure Cosmos DB-account. Selecteer Data Explorer in het accountmenu. Blader naar de database en verzameling die u hebt opgegeven in de trigger. Voeg een item toe aan de verzameling.

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

Volgende stappen