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

Artikel
08/07/2024

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

Om du behöver anslutningsappar som inte är tillgängliga i standardarbetsflöden för logikappar 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å Utökningsmodellen för Azure Functions.

Den här artikeln visar hur du skapar ett exempel på en anpassad inbyggd Azure Cosmos DB-anslutningsapp, 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.

Den här exempelanslutningsappen 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

Ett Azure-konto och prenumeration. Om du inte har någon prenumeration kan du registrera ett kostnadsfritt Azure-konto.
Grundläggande kunskaper om Azure Logic Apps för en klientorganisation, standardarbetsflöden för logikappar, anslutningsappar och hur du använder Visual Studio Code för att skapa enkla klientbaserade arbetsflöden. Mer information finns i följande dokumentation:
- Enskild klientorganisation jämfört med flera klienter i Azure Logic Apps
- Skapa ett integreringsarbetsflöde med Azure Logic Apps (Standard) med en enda klientorganisation – Azure-portalen
Visual Studio Code med Tillägget Azure Logic Apps (Standard) och andra krav installerade. Installationen bör redan innehålla NuGet-paketet för Microsoft.Azure.Workflows.WebJobs.Extension.

Kommentar

Den här redigeringsfunktionen är för närvarande endast tillgänglig i Visual Studio Code.
Ett Azure Cosmos DB-konto, en databas och en container eller samling. Mer information finns i Snabbstart: Skapa ett Azure Cosmos DB-konto, en databas, en container och ett objekt från Azure-portalen.

Steg på hög nivå

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

Skapa ett klassbiblioteksprojekt.
I projektet lägger du till NuGet-paketet Microsoft.Azure.Workflows.WebJobs.Extension som en NuGet-referens.
Ange åtgärderna för den inbyggda anslutningsappen med hjälp av NuGet-paketet för att implementera metoderna för gränssnitten med namnet IServiceOperationsProvider och IServiceOperationsTriggerProvider.
Registrera din anpassade inbyggda anslutningsapp med Azure Functions-körningstillägget.
Installera anslutningsappen för användning.

Skapa ditt klassbiblioteksprojekt

Skapa ett .NET Core 3.1-klassbiblioteksprojekt i Visual Studio Code.
I projektet lägger du till NuGet-paketet med namnet Microsoft.Azure.Workflows.WebJobs.Extension som en NuGet-referens.

Implementera tjänstproviderns gränssnitt

Om du vill ange åtgärderna 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änstbeskrivningen, 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. Driftlistan baseras på Swagger-schema. 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ösarbindningen.
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 Azure Managed Connector-utlösaren implementerar du följande metoder för att tillhandahålla anslutningsinformation och utlösarbindningar 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ösarbindningen.
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 ange 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 CosmosDbServiceOperationProvider.cs.

Viktigt!

När du har känslig information, till exempel niska veze som innehåller användarnamn och lösenord, bör du använda det säkraste tillgängliga autentiseringsflödet. Microsoft rekommenderar till exempel att du autentiserar åtkomst till Azure-resurser med en hanterad identitet när support är tillgänglig och tilldelar en roll som har minst behörighet.

Om den här funktionen inte är tillgänglig måste du skydda niska veze via andra mått, till exempel Azure Key Vault, som du kan använda med appinställningar. Du kan sedan direkt referera till säkra strängar, till exempel niska veze och nycklar. På samma sätt som ARM-mallar, där du kan definiera miljövariabler vid distributionen, kan du definiera appinställningar i logikappens arbetsflödesdefinition. Du kan sedan samla in dynamiskt genererade infrastrukturvärden, till exempel anslutningsslutpunkter, lagringssträngar med mera. Mer information finns i Programtyper för Microsoft platforma za identitete.

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 driftlistan 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 nödvändig information om anslutningsparametrar till Azure Functions-utlösarbindningen.

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 Azure Cosmos DB-anslutningsappar 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 en 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 färdiga inbyggda Azure Cosmos DB-utlösaren: "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 ange 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 startprocessen för Azure Functions-körning måste du lägga till Azure Functions-tilläggsregistreringen som ett startjobb och registrera anslutningsappen som tjänstleverantör i listan över tjänstleverantörer. Baserat på vilken typ av data som den inbyggda utlösaren behöver som indata kan du 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

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

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. I det här exemplet registreras även 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 inbyggda Azure Functions-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 som du ser tidigare 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äggspaketet :

CosmosDbServiceOperationsProvider
CosmosDbServiceProvider
CosmosDbServiceProviderStartup

Konceptuellt kodkartadiagram som visar 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 namnet Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll. Mer information finns i lagringsplatsen Azure/logicapps-connector-extensions och granska PowerShell-skriptet med namnet add-extension.ps1.

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

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 namnet add-extension.ps1 från logikappprojektets katalog med hjälp av en PowerShell-prompt:

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

Våldsamt slag

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 din anpassade inbyggda anslutningsapp 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\>

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 ditt anslutningsprogram

I Visual Studio Code öppnar du standardlogikappen och det tomma arbetsflödet i designern.
På designerytan väljer du Välj en åtgärd för att öppna anslutningsåtgärdsväljaren.
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:
I listan Utlösare väljer du din anpassade inbyggda utlösare för att starta arbetsflödet.

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

Property	Obligatoriskt	Värde	beskrivning
Anslutningens namn	Ja	<Azure-Cosmos-DB-connection-name>	Namnet på Azure Cosmos DB-anslutningen som ska skapas
Anslutningssträng	Ja	<Azure Cosmos DB-DB-connection-string>	Niska veze 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 anslutningsappen används för första gången.

Välj Skapa när du är klar.

I fönstret egenskaper för utlösare anger du följande egenskapsvärden för utlösaren, till exempel:

Property	Obligatoriskt	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 för utlösaregenskaper.

I det här exemplet i kodvyn har arbetsflödesdefinitionen, som finns i filen workflow.json , ett triggers JSON-objekt som liknar 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 liknar följande exempel:

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

I Visual Studio Code går du till menyn Kör och väljer Starta felsökning. (Tryck på F5)
Öppna ditt Azure Cosmos DB-konto i Azure-portalen för att utlösa arbetsflödet. På kontomenyn väljer du Datautforskaren. Bläddra till databasen och samlingen som du angav i utlösaren. Lägg till ett objekt i samlingen.

Dela via