Sdílet prostřednictvím

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

  • Článek

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 k dispozici 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 služby Azure Functions.

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

Operace Podrobnosti o operaci Popis
Trigger Při přijetí dokumentu Tato operace triggeru se spustí, když dojde k operaci vložení v zadané databázi a kolekci Azure Cosmos DB.
Akce Nic 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 triggerech a vazbách Azure Functions. Kompletní ukázku najdete v ukázkovém vlastním integrovaném konektoru Azure Cosmos DB – Rozšíření konektorů Azure Logic Apps.

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

Požadavky

Základní kroky

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

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

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

  3. Zadejte operace integrovaného konektoru pomocí balíčku NuGet k implementaci metod pro rozhraní s názvem IServiceOperationsProvider a IServiceOperationsTriggerProvider.

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

  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. V projektu přidejte balíček NuGet s názvem Microsoft.Azure.Workflows.WebJobs.Extension jako odkaz NuGet.

Implementace rozhraní poskytovatele služeb

Pokud chcete poskytnout operace pro ukázkový integrovaný konektor, implementujte v balíčku NuGet 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, který má trigger založený na azure Functions:

Koncepční diagram tříd znázorňující implementaci metody pro ukázkový vlastní integrovaný konektor Azure Cosmos DB

IServiceOperationsProvider

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

  • GetService()

    Návrhář v Azure Logic Apps vyžaduje , aby metoda GetService() načetla metadata vysoké úrovně pro vaši vlastní službu, včetně popisu služby, vstupních parametrů připojení vyžadovaných v návrháři, schopnostech, barvě značky, adrese URL ikony atd.

  • GetOperations()

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

  • GetBindingConnectionInformation()

    Pokud je aktivační událost typu založená na Azure Functions, modul runtime v Azure Logic Apps vyžaduje metodu GetBindingConnectionInformation() k poskytnutí požadovaných informací o parametrech připojení pro vazbu triggeru Azure Functions.

  • InvokeOperation()

    Pokud má váš konektor akce, modul runtime v Azure Logic Apps vyžaduje , aby metoda InvokeOperation() volala každou akci v konektoru, která se spouští 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 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 vazbu Azure Functions jako trigger spravovaného konektoru Azure, implementujte následující metody, které poskytují informace o připojení a vazby triggerů, jak to vyžaduje Služba Azure Functions. Další informace najdete v tématu IServiceOperationsTriggerProvider.

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

  • GetFunctionTriggerDefinition () má výchozí implementaci, takže nemusíte explicitně implementovat tuto metodu. 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 přepsat výchozí chování.

Metody implementace

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

Důležité

Pokud máte citlivé informace, například připojovací řetězec, které obsahují uživatelská jména a hesla, ujistěte se, že používáte nejbezpečnější dostupný tok ověřování. Microsoft například doporučuje ověřit přístup k prostředkům Azure pomocí spravované identity , pokud je k dispozici podpora, a přiřadit roli s nejnižším požadovaným oprávněním.

Pokud tato funkce není dostupná, nezapomeňte zabezpečit připojovací řetězec prostřednictvím jiných měr, jako je Azure Key Vault, které můžete použít s nastavením aplikace. Pak můžete přímo odkazovat na zabezpečené řetězce, jako jsou připojovací řetězec a klíče. Podobně jako šablony ARM, kde můžete definovat proměnné prostředí v době nasazení, můžete definovat nastavení aplikace v definici pracovního postupu aplikace logiky. Pak můžete zaznamenávat dynamicky generované hodnoty infrastruktury, jako jsou koncové body připojení, řetězce úložiště a další. Další informace najdete v tématu Typy aplikací pro platformu Microsoft Identity Platform.

GetService()

Návrhář vyžaduje následující metodu, aby získal popis vysoké úrovně pro vaši službu:

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

GetOperations()

Návrhář k získání operací implementovaných vaší službou vyžaduje následující metodu. 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 požadované informace o parametrech připojení k 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 nemá akce, ale k dokončení je zahrnuta následující metoda:

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

GetFunctionTriggerType()

Pokud chcete použít trigger založený na Azure Functions jako trigger ve vašem konektoru, 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 Služby Azure Cosmos DB: "type": "cosmosDBTrigger"

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 přepsat výchozí chování.

Registrace vašeho konektoru

Pokud chcete načíst vlastní integrované rozšíření konektoru během procesu spuštění modulu runtime Azure Functions, 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á aktivační událost potřebuje jako vstupy, volitelně přidejte převaděč. Tento příklad převede datový typ Dokumentu 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 vkládat zprostředkovatele služeb.

    Následující fragment kódu například ukazuje implementaci spouštěcí třídy ukázkového vlastního integrovaného konektoru 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 Služby 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 integrované triggery Azure Functions 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 převaděč 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ý znázorňuje implementaci všech tříd v sadě rozšíření Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll :

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Koncepční diagram mapování kódu, který znázorňuje úplnou implementaci třídy

Instalace konektoru

Pokud chcete přidat odkaz NuGet z předchozí části, aktualizujte v sadě rozšíření s názvem Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll soubor extensions.json. Další informace najdete v úložišti Azure/logicapps-connector-extensions a projděte si skript PowerShellu s názvem add-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 logiky pomocí příkazového řádku PowerShellu spusťte skript PowerShellu s názvem add-extension.ps1:

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

    Udeřit

    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 vlastní integrovaný konektor úspěšně nainstalovalo, získáte výstup, který vypadá podobně jako v následujícím 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ý proces func.exe , nezapomeňte tento proces před pokračováním v dalším kroku zavřít nebo ukončit.

Testování konektoru

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

  2. Na ploše návrháře vyberte Zvolit operaci , aby se otevřel výběr operací konektoru.

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

    Výběr operací zobrazuje váš vlastní integrovaný konektor a trigger, například:

    Snímek obrazovky znázorňující Visual Studio Code a návrháře pro pracovní postup standardní aplikace logiky s novým integrovaným konektorem Azure Cosmos DB

  4. V seznamu Aktivační události 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í Ano <Azure-Cosmos-DB-connection-name> Název připojení ke službě Azure Cosmos DB pro vytvoření
    Připojovací řetězec Ano <Azure Cosmos DB-connection-string> Připojovací řetězec pro kolekci databáze Azure Cosmos DB nebo kolekci zapůjčení, do které chcete přidat každý nový přijatý dokument.

    Snímek obrazovky znázorňující podokno připojení při prvním použití konektoru

  6. Až budete hotovi, vyberte Vytvořit.

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

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

    Snímek obrazovky s podoknem vlastností triggeru

    V tomto příkladu v zobrazení kódu má definice pracovního postupu, která je v souboru workflow.json , triggers objekt JSON, který vypadá podobně jako v 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 na webu Azure Portal účet služby Azure Cosmos DB. V nabídce účtu vyberte Průzkumník dat. Přejděte do databáze a kolekce, kterou jste zadali v triggeru. Přidejte do kolekce položku.

    Snímek obrazovky znázorňující web Azure Portal, účet služby Azure Cosmos DB a Průzkumník dat otevřený pro zadanou databázi a kolekci

Další kroky