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

Van toepassing op: Azure Logic Apps (Standard)

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 op serviceproviders gebaseerde ingebouwde connectors 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 Azure Cosmos DB-connector maakt, die één trigger op basis van Azure Functions en geen acties heeft. De trigger wordt geactiveerd wanneer een nieuw document wordt toegevoegd aan de leaseverzameling of container in Azure Cosmos DB en vervolgens een werkstroom uitvoert die de nettolading van de invoer gebruikt als het Azure Cosmos DB-document.

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

Deze voorbeeldconnector maakt gebruik van dezelfde functionaliteit als de Azure Cosmos DB-trigger voor Azure Functions, die is gebaseerd op Azure Functions triggers en bindingen. Voor het volledige voorbeeld raadpleegt u Voorbeeld van aangepaste ingebouwde Azure Cosmos DB-connector - Azure Logic Apps-connectorextensies.

Raadpleeg de volgende documentatie voor meer informatie:

• Aangepaste connectors voor logische standaard-apps
• Ingebouwde connectors op basis van serviceproviders
• Azure Logic Apps met één tenant

Vereisten

• Een Azure-account en -abonnement. Als u nog geen abonnement hebt, meld u dan aan voor een gratis Azure-account.

• Basiskennis van Azure Logic Apps met één tenant, standaardwerkstromen voor logische apps, connectors en het gebruik van Visual Studio Code voor het maken van werkstromen met één tenant. Raadpleeg de volgende documentatie voor meer informatie:

  • Omgeving met één tenant versus multitenant en integratieservice voor Azure Logic Apps

  • Een integratiewerkstroom maken met Azure Logic Apps met één tenant (Standard) - Azure Portal

• Visual Studio Code met de Azure Logic Apps -extensie (Standard) en andere vereisten geïnstalleerd. Uw installatie moet al het NuGet-pakket voor Microsoft.Azure.Workflows.WebJobs.Extension bevatten.

  Notitie

  Deze ontwerpfunctie is momenteel alleen beschikbaar in Visual Studio Code.

• Een Azure Cosmos DB-account, -database en -container of -verzameling. Raadpleeg Quickstart: Een Azure Cosmos DB-account, -database, -container en -items maken vanuit de Azure Portal voor meer informatie.

Stappen op hoog niveau

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

1. Een klassenbibliotheekproject maken.

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 namen 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 een NuGet-verwijzing.

De interface van de serviceprovider implementeren

Als u de bewerkingen voor de ingebouwde voorbeeldconnector wilt opgeven, 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 Ontwerper en runtime van Azure Logic Apps verwachten voor een aangepaste ingebouwde connector met een trigger op basis van Azure Functions:

IServiceOperationsProvider

Deze interface bevat de volgende methoden die het bewerkingsmanifest leveren 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, inclusief de servicebeschrijving, vereiste verbindingsinvoerparameters voor de ontwerper, mogelijkheden, merkkleur, pictogram-URL, enzovoort.

• GetOperations()

  Voor de ontwerpfunctie in Azure Logic Apps is de methode GetOperations() vereist 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 de invoerparameters voor specifieke bewerkingen te begrijpen en de uitvoer te genereren als eigenschapstokens, 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 informatie over de verbindingsparameters te verstrekken aan de Azure Functions-triggerbinding.

• InvokeOperation()

  Als uw connector acties heeft, vereist de runtime in Azure Logic Apps de methode InvokeOperation() om elke actie in uw connector aan te roepen 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 Connector van Azure Cosmos DB geen acties. De methode is echter opgenomen in dit voorbeeld voor de volledigheid.

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

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 van 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, zodat u deze methode niet expliciet hoeft te implementeren. Als u echter het standaardgedrag van de trigger wilt bijwerken, zoals het opgeven van extra parameters die de ontwerper niet beschikbaar maakt, kunt u deze methode implementeren en het standaardgedrag overschrijven.

Te implementeren methoden

In de volgende secties worden de methoden beschreven die met de voorbeeldconnector worden geïmplementeerd. Raadpleeg Sample CosmosDbServiceOperationProvider.cs (Voorbeeld 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, biedt 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 Azure Cosmos DB-connector heeft geen acties, maar de volgende methode is voor de volledigheid opgenomen:

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

GetFunctionTriggerType()

Als u een trigger op basis van Azure Functions 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 standaard implementatie, zodat u deze methode niet expliciet hoeft te implementeren. Als u echter het standaardgedrag van de trigger wilt bijwerken, zoals het opgeven van extra parameters die de ontwerper niet beschikbaar maakt, kunt u deze methode implementeren en het standaardgedrag overschrijven.

De connector registreren

Als u uw aangepaste ingebouwde connectorextensie wilt laden tijdens het startproces van de Azure Functions runtime, moet u de registratie van de Azure Functions-extensie 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 Azure 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 assembly-kenmerk met de naam [assembly:WebJobsStartup]..

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

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

   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 Services registreren - Afhankelijkheidsinjectie gebruiken in .NET Azure Functions voor meer informatie.

De serviceprovider registreren

Registreer nu de implementatie van de serviceprovider als een Azure Functions-extensie met de Azure Logic Apps-engine. In dit voorbeeld wordt de ingebouwde Azure Cosmos DB-trigger voor Azure Functions als een nieuwe trigger gebruikt. In dit voorbeeld wordt ook de nieuwe Azure Cosmos DB-serviceprovider geregistreerd voor een bestaande lijst met serviceproviders, die al deel uitmaakt van de Azure Logic Apps-extensie. Raadpleeg Registreren 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 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);
      }
   }
}

Een conversieprogramma toevoegen

Azure Logic Apps biedt een algemene manier om elke Azure Functions ingebouwde trigger af te handelen 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 klaar is, registreert u het conversieprogramma als onderdeel van ExtensionConfigContext , zoals eerder in dit voorbeeld is weergegeven:

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

Diagram van de klassenbibliotheek voor geïmplementeerde klassen

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

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

De 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 uitbreidingsbundel bij met de aangepaste ingebouwde connector.

2. In Visual Studio Code, waarop de Azure Logic Apps (Standard) voor Visual Studio Code-extensie moet zijn geïnstalleerd, maakt u een project voor een logische app 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 er ongeveer uitziet als in 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 er eenfunc.exe proces wordt uitgevoerd, moet u dit proces sluiten of afsluiten voordat u verdergaat met de volgende stap.

De connector testen

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

2. Selecteer op het ontwerpoppervlak Kies een bewerking om de kiezer voor verbindingsbewerkingen te openen.

3. Selecteer onder het zoekvak voor bewerkingen de optie Ingebouwd. Voer cosmos db in het zoekvak in.

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

   

4. Selecteer in de lijst Triggers de 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	<Azure Cosmos-DB-connection-name>	De naam voor de Azure Cosmos DB-verbinding die moet worden gemaakt
   Verbindingsreeks	Yes	<Azure Cosmos DB-DB-connection-string>	De connection string voor de Azure Cosmos DB-databaseverzameling of leaseverzameling waaraan u elk nieuw ontvangen document wilt toevoegen.

   

6. Selecteer Maken als u klaar bent.

7. Geef in het deelvenster met triggereigenschappen de volgende eigenschapswaarden op voor de trigger, bijvoorbeeld:

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

   

   In 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 Uitvoeren de optie Foutopsporing starten. (Druk op F5)

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

   

Volgende stappen

• Bron voor een voorbeeld van een aangepaste ingebouwde Azure Cosmos DB-connector - Azure Logic Apps-connectorextensies

• Ingebouwde Service Bus-trigger: batchverwerking en sessieafhandeling