Skapa anpassade inbyggda anslutningsappar för vanliga logikappar i Azure Logic Apps

  • Artikel

Gäller för: Azure Logic Apps (Standard)

Om du behöver anslutningsappar som inte är tillgängliga i standardlogikappens arbetsflöden kan du skapa egna inbyggda anslutningsappar med samma utökningsmodell som används av de tjänstleverantörsbaserade inbyggda anslutningsappar som är tillgängliga för Standard-arbetsflöden i Azure Logic Apps med en enda klientorganisation. Den här utökningsmodellen baseras på Azure Functions utökningsmodell.

Den här artikeln visar hur du skapar ett exempel på en anpassad inbyggd Azure Cosmos DB-anslutning, som har en enda Azure Functions-baserad utlösare och inga åtgärder. Utlösaren utlöses när ett nytt dokument läggs till i lånesamlingen eller containern i Azure Cosmos DB och kör sedan ett arbetsflöde som använder indatanyttolasten som Azure Cosmos DB-dokument.

Åtgärd Åtgärdsinformation Beskrivning
Utlösare När ett dokument tas emot Den här utlösaråtgärden körs när en infogningsåtgärd inträffar i den angivna Azure Cosmos DB-databasen och samlingen.
Åtgärd Ingen Den här anslutningsappen definierar inga åtgärdsåtgärder.

Det här exempelanslutningsprogrammet använder samma funktioner som Azure Cosmos DB-utlösaren för Azure Functions, som baseras på Azure Functions utlösare och bindningar. Det fullständiga exemplet finns i Exempel på anpassade inbyggda Azure Cosmos DB-anslutningsappar – Azure Logic Apps Connector-tillägg.

Mer information finns i följande dokumentation:

Förutsättningar

Övergripande steg

Följande disposition beskriver de övergripande stegen för att skapa exempelanslutningsappen:

  1. Skapa ett klassbiblioteksprojekt.

  2. Lägg till NuGet-paketet Microsoft.Azure.Workflows.WebJobs.Extension i projektet som en NuGet-referens.

  3. Ange åtgärderna för den inbyggda anslutningsappen med hjälp av NuGet-paketet för att implementera metoderna för gränssnitten IServiceOperationsProvider och IServiceOperationsTriggerProvider.

  4. Registrera din anpassade inbyggda anslutningsapp med Azure Functions-körningstillägget.

  5. Installera anslutningsappen för användning.

Skapa ditt klassbiblioteksprojekt

  1. Skapa ett .NET Core 3.1-klassbiblioteksprojekt i Visual Studio Code.

  2. I projektet lägger du till NuGet-paketet med namnet Microsoft.Azure.Workflows.WebJobs.Extension som en NuGet-referens.

Implementera gränssnittet för tjänstprovidern

Om du vill tillhandahålla åtgärder för den inbyggda exempelanslutningsappen implementerar du metoderna för följande gränssnitt i NuGet-paketet Microsoft.Azure.Workflows.WebJobs.Extension . Följande diagram visar gränssnitten med de metodimplementeringar som Azure Logic Apps-designern och körningen förväntar sig för en anpassad inbyggd anslutningsapp som har en Azure Functions-baserad utlösare:

Konceptuellt klassdiagram som visar metodimplementering för azure Cosmos DB-anpassade inbyggda anslutningsappar.

IServiceOperationsProvider

Det här gränssnittet innehåller följande metoder som tillhandahåller åtgärdsmanifestet och utför tjänstleverantörens specifika uppgifter eller faktisk affärslogik i din anpassade inbyggda anslutningsapp. Mer information finns i IServiceOperationsProvider.

  • GetService()

    Designern i Azure Logic Apps kräver metoden GetService() för att hämta metadata på hög nivå för din anpassade tjänst, inklusive tjänstbeskrivning, parametrar för anslutningsindata som krävs för designern, funktioner, varumärkesfärg, ikon-URL och så vidare.

  • GetOperations()

    Designern i Azure Logic Apps kräver metoden GetOperations() för att hämta de åtgärder som implementeras av din anpassade tjänst. Åtgärdslistan baseras på Swagger-schemat. Designern använder också åtgärdsmetadata för att förstå indataparametrarna för specifika åtgärder och generera utdata som egenskapstoken, baserat på schemat för utdata för en åtgärd.

  • GetBindingConnectionInformation()

    Om utlösaren är en Azure Functions-baserad utlösartyp kräver körningen i Azure Logic Apps metoden GetBindingConnectionInformation() för att tillhandahålla nödvändig anslutningsparametrar till Azure Functions utlösarbindning.

  • InvokeOperation()

    Om anslutningsappen har åtgärder kräver körningen i Azure Logic Apps metoden InvokeOperation() för att anropa varje åtgärd i anslutningsappen som körs under arbetsflödeskörningen. Om anslutningsappen inte har några åtgärder behöver du inte implementera metoden InvokeOperation().

    I det här exemplet har den anpassade inbyggda Azure Cosmos DB-anslutningsappen inte några åtgärder. Metoden ingår dock i det här exemplet för fullständighet.

Mer information om dessa metoder och deras implementering finns i dessa metoder senare i den här artikeln.

IServiceOperationsTriggerProvider

Du kan lägga till eller exponera en Azure Functions utlösare eller åtgärd som en tjänstleverantörsutlösare i din anpassade inbyggda anslutningsapp. Om du vill använda den Azure Functions-baserade utlösartypen och samma Azure Functions bindning som Utlösaren för azure-hanterad anslutningsapp implementerar du följande metoder för att tillhandahålla anslutningsinformation och utlösa bindningar som krävs av Azure Functions. Mer information finns i IServiceOperationsTriggerProvider.

  • Metoden GetFunctionTriggerType() krävs för att returnera strängen som är samma som typparametern i Azure Functions utlösarbindning.

  • GetFunctionTriggerDefinition() har en standardimplementering, så du behöver inte uttryckligen implementera den här metoden. Men om du vill uppdatera utlösarens standardbeteende, till exempel tillhandahålla extra parametrar som designern inte exponerar, kan du implementera den här metoden och åsidosätta standardbeteendet.

Metoder för att implementera

I följande avsnitt beskrivs de metoder som exempelanslutningsappen implementerar. Det fullständiga exemplet finns i Exempel på CosmosDbServiceOperationProvider.cs.

GetService()

Designern kräver följande metod för att få en beskrivning på hög nivå för din tjänst:

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

GetOperations()

Designern kräver följande metod för att få de åtgärder som implementeras av din tjänst. Den här åtgärdslistan baseras på Swagger-schema.

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

GetBindingConnectionInformation()

Om du vill använda den Azure Functions-baserade utlösartypen tillhandahåller följande metod den information om anslutningsparametrar som krävs för Azure Functions utlösarbindning.

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

InvokeOperation()

Exempel på anpassade inbyggda anslutningsappar i Azure Cosmos DB har inte åtgärder, men följande metod ingår för fullständighet:

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

GetFunctionTriggerType()

Om du vill använda en Azure Functions-baserad utlösare som utlösare i anslutningsappen måste du returnera strängen som är samma som typparametern i Azure Functions-utlösarbindningen.

I följande exempel returneras strängen för den inbyggda Azure Cosmos DB-utlösaren out-of-the-box, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Den här metoden har en standardimplementering, så du behöver inte uttryckligen implementera den här metoden. Men om du vill uppdatera utlösarens standardbeteende, till exempel tillhandahålla extra parametrar som designern inte exponerar, kan du implementera den här metoden och åsidosätta standardbeteendet.

Registrera din anslutningsapp

Om du vill läsa in ditt anpassade inbyggda anslutningstillägg under Azure Functions körningsstartprocess måste du lägga till Azure Functions tilläggsregistrering som startjobb och registrera anslutningsappen som en tjänstleverantör i listan över tjänstleverantörer. Baserat på vilken typ av data som din inbyggda utlösare behöver som indata kan du också lägga till konverteraren. I det här exemplet konverteras dokumentdatatypen för Azure Cosmos DB-dokument till en JObject-matris .

Följande avsnitt visar hur du registrerar din anpassade inbyggda anslutningsapp som ett Azure Functions-tillägg.

Skapa startjobbet

  1. Skapa en startklass med sammansättningsattributet [assembly:WebJobsStartup].

  2. Implementera gränssnittet IWebJobsStartup . I metoden Configure() registrerar du tillägget och matar in tjänstleverantören.

    Följande kodfragment visar till exempel implementeringen av startklassen för den anpassade inbyggda Azure Cosmos DB-anslutningsappen:

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

    Mer information finns i Registrera tjänster – Använd beroendeinmatning i .NET Azure Functions.

Registrera tjänstleverantören

Registrera nu implementeringen av tjänstleverantören som ett Azure Functions-tillägg med Azure Logic Apps-motorn. I det här exemplet används den inbyggda Azure Cosmos DB-utlösaren för Azure Functions som en ny utlösare. Det här exemplet registrerar också den nya Azure Cosmos DB-tjänstleverantören för en befintlig lista över tjänstleverantörer, som redan ingår i Azure Logic Apps-tillägget. Mer information finns i Registrera Azure Functions bindningstillägg.

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

Lägga till en konverterare

Azure Logic Apps har ett allmänt sätt att hantera alla Azure Functions inbyggda utlösare med hjälp av JObject-matrisen. Men om du vill konvertera den skrivskyddade listan över Azure Cosmos DB-dokument till en JObject-matris kan du lägga till en konverterare. När konverteraren är klar registrerar du konverteraren som en del av ExtensionConfigContext enligt ovan i det här exemplet:

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

Klassbiblioteksdiagram för implementerade klasser

När du är klar granskar du följande klassdiagram som visar implementeringen för alla klasser i Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll tilläggspaket:

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Konceptuellt kodkartediagram som visar en fullständig klassimplementering.

Installera anslutningsappen

Om du vill lägga till NuGet-referensen från föregående avsnitt uppdaterar du filen extensions.json i tilläggspaketet med namnetMicrosoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll. Mer information finns i lagringsplatsen Azure/logicapps-connector-extensions och granska PowerShell-skriptet med namnetadd-extension.ps1.

  1. Uppdatera tilläggspaketet så att det innehåller den anpassade inbyggda anslutningsappen.

  2. I Visual Studio Code, som ska ha Azure Logic Apps (Standard) för Visual Studio Code-tillägget installerat, skapar du ett logikappprojekt och installerar tilläggspaketet med följande PowerShell-kommando:

    PowerShell

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

    Du kan också köra PowerShell-skriptet med namnetadd-extension.ps1från logikappprojektets katalog med hjälp av en PowerShell-prompt:

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

    Bash

    Om du i stället vill använda Bash från logikappprojektets katalog kör du PowerShell-skriptet med följande kommando:

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

    Om tillägget för den anpassade inbyggda anslutningsappen har installerats får du utdata som ser ut ungefär som i följande exempel:

    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. Om någon func.exe process körs måste du stänga eller avsluta processen innan du fortsätter till nästa steg.

Testa anslutningsappen

  1. Öppna logikappen Standard och det tomma arbetsflödet i designern i Visual Studio Code.

  2. På designerytan väljer du Välj en åtgärd för att öppna anslutningsappens åtgärdsväljare.

  3. Under sökrutan åtgärder väljer du Inbyggd. I sökrutan anger du cosmos db.

    Åtgärdsväljaren visar din anpassade inbyggda anslutningsapp och utlösare, till exempel:

    Skärmbild som visar Visual Studio Code och designern för ett standardarbetsflöde för logikappar med den nya anpassade inbyggda Azure Cosmos DB-anslutningsappen.

  4. I listan Utlösare väljer du din anpassade inbyggda utlösare för att starta arbetsflödet.

  5. I anslutningsfönstret anger du följande egenskapsvärden för att skapa en anslutning, till exempel:

    Egenskap Krävs Värde Beskrivning
    Anslutningsnamn Ja <Azure-Cosmos-DB-connection-name> Namnet på Azure Cosmos DB-anslutningen som ska skapas
    Anslutningssträng Ja <Azure Cosmos DB-DB-connection-string> Anslutningssträngen för Azure Cosmos DB-databassamlingen eller lånesamlingen där du vill lägga till varje nytt mottaget dokument.

    Skärmbild som visar anslutningsfönstret när du använder anslutningsappen för första gången.

  6. När du är färdig väljer du Skapa.

  7. I fönstret utlösaregenskaper anger du följande egenskapsvärden för utlösaren, till exempel:

    Egenskap Krävs Värde Beskrivning
    Databasnamn Ja <Azure-Cosmos-DB-database-name> Namnet på Den Azure Cosmos DB-databas som ska användas
    Samlingsnamn Ja <Azure-Cosmos-DB-collection-name> Namnet på Azure Cosmos DB-samlingen där du vill lägga till varje nytt mottaget dokument.

    Skärmbild som visar fönstret utlösaregenskaper.

    I det här exemplet i kodvyn har arbetsflödesdefinitionen, som finns i filen workflow.json , ett triggers JSON-objekt som ser ut ungefär som i följande exempel:

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

    Anslutningsdefinitionen, som finns i filen connections.json , har ett serviceProviderConnections JSON-objekt som ser ut ungefär som i följande exempel:

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

  8. I Visual Studio Code går du till menyn Kör och väljer Starta felsökning. (Tryck på F5)

  9. Om du vill utlösa arbetsflödet öppnar du ditt Azure Cosmos DB-konto i Azure Portal. Välj Data Explorer på kontomenyn. Bläddra till databasen och samlingen som du angav i utlösaren. Lägg till ett objekt i samlingen.

    Skärmbild som visar Azure Portal, Azure Cosmos DB-konto och Data Explorer öppna för den angivna databasen och samlingen.

Nästa steg