Vytváření vlastních integrovaných konektorů pro standardní aplikace logiky v jediném tenantovi služby Azure Logic Apps

Platí pro: Azure Logic Apps (Standard)

Pokud potřebujete konektory, které nejsou dostupné v pracovních postupech standardní aplikace logiky, můžete vytvořit vlastní integrované konektory pomocí stejného modelu rozšiřitelnosti, který používají integrované konektory založené na poskytovateli služeb , které jsou dostupné pro standardní pracovní postupy v Azure Logic Apps s jedním tenantem. Tento model rozšiřitelnosti je založený na modelu rozšiřitelnosti Azure Functions.

Tento článek ukazuje, jak vytvořit příklad vlastního integrovaného konektoru Azure Cosmos DB, který má jeden trigger založený na Azure Functions a žádné akce. Trigger se aktivuje, když se do kolekce zapůjčení nebo kontejneru ve službě Azure Cosmos DB přidá nový dokument a pak spustí pracovní postup, který jako dokument služby Azure Cosmos DB použije vstupní datovou část.

Operace	Podrobnosti o operaci	Popis
Trigger	Při přijetí dokumentu	Tato operace triggeru se spustí, když v zadané databázi a kolekci Azure Cosmos DB proběhne operace vložení.
Akce	Žádné	Tento konektor nedefinuje žádné operace akcí.

Tento ukázkový konektor používá stejné funkce jako trigger služby Azure Cosmos DB pro Azure Functions, který je založený na Azure Functions triggerech a vazbách. Úplnou ukázku najdete v tématu Ukázka vlastního integrovaného konektoru Azure Cosmos DB – Rozšíření konektoru Azure Logic Apps.

Další informace najdete v následující dokumentaci:

• Vlastní konektory pro standardní aplikace logiky
• Integrované konektory založené na poskytovateli služeb
• Azure Logic Apps s jedním tenantem

Požadavky

• Účet a předplatné Azure. Pokud předplatné nemáte, zaregistrujte si bezplatný účet Azure.

• Základní znalosti o Azure Logic Apps s jedním tenantem, pracovních postupech a konektorech aplikací logiky úrovně Standard a o tom, jak používat Visual Studio Code k vytváření pracovních postupů založených na jednom tenantovi. Další informace najdete v následující dokumentaci:

  • Jednoklienta versus prostředí víceklientů a integrační služby pro Azure Logic Apps

  • Vytvoření pracovního postupu integrace pomocí Azure Logic Apps s jedním tenantem (Standard) – Azure Portal

• Visual Studio Code s nainstalovaným rozšířením Azure Logic Apps (Standard) a dalšími požadavky. Vaše instalace by už měla obsahovat balíček NuGet pro Microsoft.Azure.Workflows.WebJobs.Extension.

  Poznámka

  Tato funkce vytváření obsahu je v současné době dostupná jenom v editoru Visual Studio Code.

• Účet služby Azure Cosmos DB, databáze a kontejner nebo kolekce. Další informace najdete v tématu Rychlý start: Vytvoření účtu, databáze, kontejneru a položek služby Azure Cosmos DB z Azure Portal.

Základní kroky

Následující osnova popisuje základní kroky k sestavení ukázkového konektoru:

1. Vytvořte projekt knihovny tříd.

2. Do projektu přidejte balíček NuGet Microsoft.Azure.Workflows.WebJobs.Extension jako odkaz na NuGet.

3. Zadejte operace pro integrovaný konektor pomocí balíčku NuGet k implementaci metod pro rozhraní s názvy IServiceOperationsProvider a IServiceOperationsTriggerProvider.

4. Zaregistrujte vlastní integrovaný konektor s rozšířením Azure Functions runtime.

5. Nainstalujte konektor pro použití.

Vytvoření projektu knihovny tříd

1. V editoru Visual Studio Code vytvořte projekt knihovny tříd .NET Core 3.1.

2. Do projektu přidejte balíček NuGet s názvem Microsoft.Azure.Workflows.WebJobs.Extension jako odkaz na NuGet.

Implementace rozhraní poskytovatele služeb

Pokud chcete poskytnout operace pro ukázkový integrovaný konektor, implementujte v balíčku NuGet Microsoft.Azure.Workflows.WebJobs.Extension metody pro následující rozhraní. Následující diagram znázorňuje rozhraní s implementacemi metod, které návrhář Azure Logic Apps a modul runtime očekávají pro vlastní integrovaný konektor s triggerem založeným na Azure Functions:

IServiceOperationsProvider

Toto rozhraní obsahuje následující metody, které poskytují manifest operace a provádějí konkrétní úlohy poskytovatele služeb nebo skutečnou obchodní logiku ve vašem vlastním integrovaném konektoru. Další informace najdete v tématu IServiceOperationsProvider.

• GetService()

  Návrhář v Azure Logic Apps vyžaduje metodu GetService() k načtení metadat vysoké úrovně pro vaši vlastní službu, včetně popisu služby, vstupních parametrů připojení požadovaných u návrháře, možností, barvy značky, adresy URL ikon atd.

• GetOperations()

  Návrhář v Azure Logic Apps vyžaduje metodu GetOperations() k načtení operací implementovaných vaší vlastní službou. Seznam operací je založený na schématu Swaggeru. Návrhář také používá metadata operace k pochopení vstupních parametrů pro konkrétní operace a generování výstupů jako tokenů vlastností na základě schématu výstupu pro operaci.

• GetBindingConnectionInformation()

  Pokud je váš trigger typu triggeru založeného na Azure Functions, modul runtime v Azure Logic Apps vyžaduje metodu GetBindingConnectionInformation(), která poskytne požadované informace o parametrech připojení pro vazbu triggeru Azure Functions.

• InvokeOperation()

  Pokud váš konektor obsahuje akce, modul runtime v Azure Logic Apps vyžaduje metodu InvokeOperation() k volání každé akce v konektoru, která se spustí během provádění pracovního postupu. Pokud váš konektor nemá akce, nemusíte implementovat metodu InvokeOperation().

  V tomto příkladu nemá vlastní integrovaný konektor Azure Cosmos DB žádné akce. Metoda je však zahrnuta v tomto příkladu pro úplnost.

Další informace o těchto metodách a jejich implementaci najdete dále v tomto článku.

IServiceOperationsTriggerProvider

Trigger nebo akci Azure Functions můžete přidat nebo zveřejnit jako trigger poskytovatele služeb ve vlastním integrovaném konektoru. Pokud chcete použít typ triggeru založeného na Azure Functions a stejnou Azure Functions vazbu jako trigger spravovaného konektoru Azure, implementujte následující metody, které poskytují informace o připojení a aktivační vazby podle požadavků Azure Functions. Další informace najdete v tématu IServiceOperationsTriggerProvider.

• Metoda GetFunctionTriggerType() je vyžadována k vrácení řetězce, který je stejný jako parametr typu ve vazbě triggeru Azure Functions.

• GetFunctionTriggerDefinition() má výchozí implementaci, takže tuto metodu nemusíte explicitně implementovat. Pokud ale chcete aktualizovat výchozí chování triggeru, například poskytnout další parametry, které návrhář nezpřístupňuje, můžete tuto metodu implementovat a výchozí chování přepsat.

Metody k implementaci

Následující části popisují metody, které ukázkový konektor implementuje. Úplnou ukázku najdete v ukázkové ukázce CosmosDbServiceOperationProvider.cs.

GetService()

Návrhář vyžaduje následující metodu k získání základního popisu vaší služby:

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

GetOperations()

Návrhář vyžaduje následující metodu, aby vaše služba implementovala operace. Tento seznam operací je založený na schématu Swaggeru.

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

GetBindingConnectionInformation()

Pokud chcete použít typ triggeru založeného na Azure Functions, následující metoda poskytuje informace o požadovaných parametrech připojení vazbě triggeru Azure Functions.

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

InvokeOperation()

Příklad vlastního integrovaného konektoru Azure Cosmos DB neobsahuje akce, ale pro úplnost je zahrnuta následující metoda:

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

GetFunctionTriggerType()

Pokud chcete jako trigger v konektoru použít trigger založený na Azure Functions, musíte vrátit řetězec, který je stejný jako parametr typu ve vazbě triggeru Azure Functions.

Následující příklad vrátí řetězec pro předdefinovaný trigger "type": "cosmosDBTrigger"Azure Cosmos DB:

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

GetFunctionTriggerDefinition()

Tato metoda má výchozí implementaci, takže tuto metodu nemusíte explicitně implementovat. Pokud ale chcete aktualizovat výchozí chování triggeru, například poskytnout další parametry, které návrhář nezpřístupňuje, můžete tuto metodu implementovat a výchozí chování přepsat.

Registrace vašeho konektoru

Pokud chcete během procesu spuštění modulu runtime Azure Functions načíst vlastní předdefinované rozšíření konektoru, musíte přidat registraci rozšíření Azure Functions jako spouštěcí úlohu a zaregistrovat konektor jako poskytovatele služeb v seznamu poskytovatelů služeb. Na základě typu dat, která předdefinovaný trigger potřebuje jako vstupy, volitelně přidejte převaděč. Tento příklad převede datový typ Document pro dokumenty Azure Cosmos DB na pole JObject .

Následující části ukazují, jak zaregistrovat vlastní integrovaný konektor jako rozšíření Azure Functions.

Vytvoření spouštěcí úlohy

1. Vytvořte spouštěcí třídu pomocí atributu sestavení s názvem [assembly:WebJobsStartup].

2. Implementujte rozhraní IWebJobsStartup . V metodě Configure() zaregistrujte rozšíření a vložte poskytovatele služby.

   Například následující fragment kódu ukazuje implementaci spouštěcí třídy pro ukázkový integrovaný konektor 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>();
         }
      }
   }
   

   Další informace najdete v tématu Registrace služeb – použití injektáže závislostí v .NET Azure Functions.

Registrace poskytovatele služeb

Teď zaregistrujte implementaci poskytovatele služeb jako rozšíření Azure Functions pomocí modulu Azure Logic Apps. V tomto příkladu se jako nový trigger používá integrovaný trigger Azure Cosmos DB pro Azure Functions. Tento příklad také zaregistruje nového poskytovatele služeb Azure Cosmos DB pro existující seznam poskytovatelů služeb, který je již součástí rozšíření Azure Logic Apps. Další informace najdete v tématu Registrace rozšíření vazeb 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);
      }
   }
}

Přidání převaděče

Azure Logic Apps nabízí obecný způsob, jak zpracovat všechny Azure Functions integrované triggery pomocí pole JObject. Pokud ale chcete převést seznam dokumentů Azure Cosmos DB jen pro čtení na pole JObject , můžete přidat převaděč. Až bude převaděč připravený, zaregistrujte ho jako součást ExtensionConfigContext , jak je znázorněno výše v tomto příkladu:

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

Diagram knihovny tříd pro implementované třídy

Až budete hotovi, projděte si následující diagram tříd, který ukazuje implementaci pro všechny třídy v Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll sadě rozšíření:

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

Instalace konektoru

Pokud chcete přidat odkaz NuGet z předchozí části, aktualizujte v sadě rozšíření s názvemMicrosoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dllsoubor extensions.json . Další informace najdete v úložišti Azure/logicapps-connector-extensions a projděte si skript PowerShellu s názvemadd-extension.ps1.

1. Aktualizujte sadu rozšíření tak, aby zahrnovala vlastní integrovaný konektor.

2. V editoru Visual Studio Code, který by měl mít nainstalované rozšíření Azure Logic Apps (Standard) pro Visual Studio Code , vytvořte projekt aplikace logiky a nainstalujte balíček rozšíření pomocí následujícího příkazu PowerShellu:

   PowerShell

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

   Případně z adresáře projektu aplikace logiky pomocí příkazového řádku PowerShellu spusťte skript PowerShellu s názvemadd-extension.ps1:

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

   Bash

   Pokud chcete místo toho použít Bash, spusťte z adresáře projektu aplikace logiky skript PowerShellu pomocí následujícího příkazu:

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

   Pokud se rozšíření pro váš vlastní integrovaný konektor úspěšně nainstalovalo, zobrazí se výstup podobný následujícímu příkladu:

   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. Pokud je spuštěný nějaký func.exe proces, nezapomeňte ho zavřít nebo ukončit, než budete pokračovat k dalšímu kroku.

Testování konektoru

1. V editoru Visual Studio Code otevřete aplikaci logiky Standard a prázdný pracovní postup v návrháři.

2. Na ploše návrháře vyberte Zvolit operaci a otevřete tak výběr operací konektoru.

3. Pod vyhledávacím polem operací vyberte Předdefinované. Do vyhledávacího pole zadejte cosmos db.

   Ve výběru operací se zobrazí váš vlastní integrovaný konektor a trigger, například:

   

4. V seznamu Triggery vyberte vlastní předdefinovaný trigger a spusťte pracovní postup.

5. V podokně připojení zadejte následující hodnoty vlastností pro vytvoření připojení, například:

   Vlastnost	Požaduje se	Hodnota	Popis
   Název připojení	Yes	<Název připojení ke službě Azure Cosmos DB>	Název připojení ke službě Azure Cosmos DB, které se má vytvořit
   Připojovací řetězec	Yes	<Azure Cosmos DB-DB-connection-string>	Připojovací řetězec pro kolekci nebo zapůjčení databáze Azure Cosmos DB, do které chcete přidat každý nový přijatý dokument.

   

6. Po dokončení vyberte Vytvořit.

7. V podokně vlastností triggeru zadejte následující hodnoty vlastností triggeru, například:

   Vlastnost	Požaduje se	Hodnota	Popis
   Název databáze	Yes	<Název databáze Azure Cosmos-DB>	Název databáze Azure Cosmos DB, která se má použít
   Název kolekce	Yes	<Název kolekce Azure Cosmos-DB>	Název kolekce Azure Cosmos DB, do které chcete přidat každý nový přijatý dokument.

   

   V tomto příkladu v zobrazení kódu má triggers definice pracovního postupu, která je v souboru workflow.json, objekt JSON, který se podobá následující ukázce:

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

   Definice připojení, která je v souboru connections.json , má serviceProviderConnections objekt JSON, který se podobá následující ukázce:

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

8. V editoru Visual Studio Code v nabídce Spustit vyberte Spustit ladění. (Stiskněte klávesu F5.

9. Pokud chcete aktivovat pracovní postup, otevřete v Azure Portal svůj účet služby Azure Cosmos DB. V nabídce účtu vyberte Data Explorer. Přejděte k databázi a kolekci, kterou jste zadali v triggeru. Přidejte položku do kolekce.

   

Další kroky

• Zdroj pro ukázku vlastního integrovaného konektoru Azure Cosmos DB – Rozšíření konektoru Azure Logic Apps

• Předdefinovaný trigger služby Service Bus: dávkování a zpracování relací