Share via

Egyéni beépített összekötők létrehozása standard logikai alkalmazásokhoz egybérlős Azure Logic Apps esetén

  • Cikk

A következőkre vonatkozik: Azure Logic Apps (Standard)

Ha olyan összekötőkre van szüksége, amelyek nem érhetők el a Standard logikaialkalmazás-munkafolyamatokban, létrehozhatja saját beépített összekötőit ugyanazzal a bővíthetőségi modellel, amelyet a szolgáltatói alapú beépített összekötők használnak az egybérlős Azure Logic Apps standard munkafolyamataihoz. Ez a bővíthetőségi modell a Azure Functions bővíthetőségi modellen alapul.

Ez a cikk bemutatja, hogyan hozhat létre példaként egy egyéni beépített Azure Cosmos DB-összekötőt, amely egyetlen Azure Functions-alapú eseményindítóval rendelkezik, és nincs művelete. Az eseményindító akkor aktiválódik, ha új dokumentumot adnak hozzá az Azure Cosmos DB-beli bérletgyűjteményhez vagy -tárolóhoz, majd futtat egy munkafolyamatot, amely a bemeneti hasznos adatokat használja Azure Cosmos DB-dokumentumként.

Művelet Művelet részletei Description
Eseményindító Dokumentum beérkezésekor Ez az eseményindító-művelet akkor fut, ha beszúrási művelet történik a megadott Azure Cosmos DB-adatbázisban és -gyűjteményben.
Művelet None Ez az összekötő nem határoz meg műveleti műveleteket.

Ez a mintaösszekötő ugyanazt a funkciót használja, mint az Azure Cosmos DB-eseményindító Azure Functions, amely Azure Functions eseményindítókon és kötéseken alapul. A teljes mintaért tekintse át az egyéni beépített Azure Cosmos DB-összekötő – Azure Logic Apps-összekötőbővítmények mintáját.

További információért tekintse át a következő dokumentációt:

Előfeltételek

Magas szintű lépések

Az alábbi vázlat a példa-összekötő összeállításának magas szintű lépéseit ismerteti:

  1. Hozzon létre egy osztálytárprojektet.

  2. A projektben adja hozzá a Microsoft.Azure.Workflows.WebJobs.Extension NuGet-csomagot NuGet-referenciaként.

  3. Adja meg a beépített összekötő műveleteit a NuGet-csomaggal az IServiceOperationsProvider és az IServiceOperationsTriggerProvider interfészek metódusainak implementálásához.

  4. Regisztrálja egyéni beépített összekötőjét a Azure Functions futtatókörnyezeti bővítménnyel.

  5. Telepítse az összekötőt használatra.

Az osztálytár projekt létrehozása

  1. A Visual Studio Code-ban hozzon létre egy .NET Core 3.1-osztálytárprojektet.

  2. A projektben adja hozzá a Microsoft.Azure.Workflows.WebJobs.Extension nevű NuGet-csomagot NuGet-referenciaként.

A szolgáltatói felület implementálása

A minta beépített összekötő műveleteinek biztosításához a Microsoft.Azure.Workflows.WebJobs.Extension NuGet-csomagban implementálja a következő felületek metódusait. Az alábbi ábrán az Azure Logic Apps tervezője és futtatókörnyezete által egy Azure Functions-alapú eseményindítóval rendelkező egyéni beépített összekötőhöz elvárt metódus-implementációk illesztői láthatók:

Az Azure Cosmos DB egyéni beépített összekötőjének metódus-implementációját bemutató fogalmi osztálydiagram.

IServiceOperationsProvider

Ez a felület a következő metódusokat tartalmazza, amelyek biztosítják a műveletjegyzéket, és elvégzik a szolgáltató konkrét feladatait vagy tényleges üzleti logikáját az egyéni beépített összekötőben. További információ: IServiceOperationsProvider.

  • GetService()

    Az Azure Logic Apps tervezője megköveteli a GetService() metódust az egyéni szolgáltatás magas szintű metaadatainak lekéréséhez, beleértve a szolgáltatás leírását, a tervezőhöz szükséges kapcsolatbemeneti paramétereket, a képességeket, a márkaszínt, az ikon URL-címét stb.

  • GetOperations()

    Az Azure Logic Apps tervezője megköveteli a GetOperations() metódust az egyéni szolgáltatás által implementált műveletek lekéréséhez. A műveleti lista a Swagger-sémán alapul. A tervező a művelet metaadatait is felhasználja az adott műveletek bemeneti paramétereinek megértéséhez, és a kimeneteket tulajdonságtokenként hozza létre a művelet kimenetének sémája alapján.

  • GetBindingConnectionInformation()

    Ha az eseményindító egy Azure Functions-alapú eseményindító-típus, az Azure Logic Apps futtatókörnyezetéhez a GetBindingConnectionInformation() metódusra van szükség, hogy megadja a szükséges kapcsolatparaméter-információkat a Azure Functions triggerkötéshez.

  • InvokeOperation()

    Ha az összekötő rendelkezik műveletekkel, az Azure Logic Apps futtatókörnyezetéhez az InvokeOperation() metódusra van szükség a munkafolyamat végrehajtása során futó összekötő minden egyes műveletének meghívásához. Ha az összekötő nem rendelkezik műveletekkel, nem kell implementálnia az InvokeOperation() metódust .

    Ebben a példában az Azure Cosmos DB egyéni beépített összekötője nem rendelkezik műveletekkel. A teljesség érdekében azonban ebben a példában a metódus szerepel.

Ezekről a módszerekről és azok implementálásáról a cikk későbbi részében talál további információt.

IServiceOperationsTriggerProvider

Az egyéni beépített összekötőben hozzáadhat vagy közzétehet Azure Functions eseményindítót vagy műveletet szolgáltatói eseményindítóként. A Azure Functions-alapú eseményindító típusának és az Azure által felügyelt összekötő eseményindítójának Azure Functions kötésének használatához implementálja az alábbi módszereket a kapcsolatadatok és a triggerkötések Azure Functions által megkövetelt megadásához. További információ: IServiceOperationsTriggerProvider.

  • A GetFunctionTriggerType() metódus szükséges a Azure Functions triggerkötés típusparaméterével megegyező sztring visszaadásához.

  • A GetFunctionTriggerDefinition() alapértelmezett implementációval rendelkezik, így nem kell explicit módon implementálnia ezt a módszert. Ha azonban frissíteni szeretné az eseményindító alapértelmezett viselkedését, például további paramétereket szeretne megadni, amelyeket a tervező nem tesz közzé, akkor implementálhatja ezt a módszert, és felülbírálhatja az alapértelmezett viselkedést.

Implementálandó módszerek

A következő szakaszok a példa-összekötő által implementált módszereket ismertetik. A teljes mintaért tekintse át a CosmosDbServiceOperationProvider.cs mintát.

GetService()

A tervező a következő metódust igényli a szolgáltatás magas szintű leírásának lekéréséhez:

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

GetOperations()

A tervező a következő metódust igényli a szolgáltatás által implementált műveletek lekéréséhez. Ez a műveleti lista a Swagger-sémán alapul.

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

GetBindingConnectionInformation()

A Azure Functions-alapú triggertípus használatához a következő metódus biztosítja a szükséges kapcsolatparaméter-információkat a Azure Functions triggerkötéshez.

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

InvokeOperation()

Az Azure Cosmos DB egyéni beépített összekötője nem rendelkezik műveletekkel, de a teljesség érdekében a következő metódust tartalmazza:

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

GetFunctionTriggerType()

Ha Azure Functions-alapú eseményindítót szeretne használni az összekötőben, vissza kell adnia azt a sztringet, amely megegyezik a Azure Functions triggerkötés típusparaméterével.

Az alábbi példa a beépített Azure Cosmos DB-eseményindító sztringét adja vissza: "type": "cosmosDBTrigger"

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

GetFunctionTriggerDefinition()

Ez a metódus alapértelmezett implementációval rendelkezik, így nem kell explicit módon implementálnia ezt a metódust. Ha azonban frissíteni szeretné az eseményindító alapértelmezett viselkedését, például további paramétereket szeretne megadni, amelyeket a tervező nem tesz közzé, akkor implementálhatja ezt a módszert, és felülbírálhatja az alapértelmezett viselkedést.

Összekötő regisztrálása

Az egyéni beépített összekötőbővítmény Azure Functions futásidejű indítási folyamat során való betöltéséhez hozzá kell adnia a Azure Functions bővítmény regisztrációját indítási feladatként, és regisztrálnia kell az összekötőt szolgáltatóként a szolgáltatói listában. A beépített eseményindító bemenetként szükséges adattípusa alapján igény szerint adja hozzá a konvertert. Ez a példa az Azure Cosmos DB-dokumentumok Dokumentum adattípusát JObject tömbté alakítja.

Az alábbi szakaszok bemutatják, hogyan regisztrálhatja az egyéni beépített összekötőt Azure Functions bővítményként.

Az indítási feladat létrehozása

  1. Hozzon létre egy indítási osztályt a [assembly:WebJobsStartup] szerelvényattribútummal.

  2. Implementálja az IWebJobsStartup felületet. A Configure() metódusban regisztrálja a bővítményt, és adja meg a szolgáltatót.

    Az alábbi kódrészlet például az egyéni beépített Azure Cosmos DB-összekötő indítási osztályának implementációját mutatja be:

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

    További információ: Szolgáltatások regisztrálása – Függőséginjektálás használata a .NET-ben Azure Functions.

A szolgáltató regisztrálása

Most regisztrálja a szolgáltató implementációját Azure Functions bővítményként az Azure Logic Apps motorjával. Ez a példa a beépített Azure Cosmos DB-eseményindítót használja Azure Functions új eseményindítóként. Ez a példa az új Azure Cosmos DB-szolgáltatót is regisztrálja a szolgáltatók meglévő listájához, amely már része az Azure Logic Apps bővítménynek. További információ: Regisztráció Azure Functions kötésbővítmények.

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

Konverter hozzáadása

Az Azure Logic Apps általános módon kezeli a beépített Azure Functions eseményindítót a JObject tömb használatával. Ha azonban JObject-tömbbe szeretné konvertálni az Azure Cosmos DB-dokumentumok írásvédett listáját, hozzáadhat egy konvertert. Ha a konverter készen áll, regisztrálja a konvertert az ExtensionConfigContext részeként a példában korábban látható módon:

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

Osztálytár diagramja implementált osztályokhoz

Ha végzett, tekintse át az alábbi osztálydiagramot, amely a Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll bővítménycsomag összes osztályának implementációját mutatja be:

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

A teljes osztály implementációját bemutató fogalmi kódtérkép-diagram.

Az összekötő telepítése

Az előző szakasz NuGet-hivatkozásának hozzáadásához a Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dllnevű bővítménycsomagban frissítse a extensions.json fájlt. További információt az Azure/logicapps-connector-extensions adattárban talál, és tekintse át a add-extension.ps1nevű PowerShell-szkriptet.

  1. Frissítse a bővítménycsomagot úgy, hogy tartalmazza az egyéni beépített összekötőt.

  2. A Visual Studio Code-ban, amelynek telepítve kell lennie az Azure Logic Apps (Standard) for Visual Studio Code bővítménynek , hozzon létre egy logikai alkalmazásprojektet, és telepítse a bővítménycsomagot a következő PowerShell-paranccsal:

    PowerShell

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

    Másik lehetőségként futtassa a add-extension.ps1nevű PowerShell-szkriptet a logikaialkalmazás-projekt könyvtárából egy PowerShell-parancssor használatával:

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

    Bash

    A Bash használatához futtassa a PowerShell-szkriptet a logikai alkalmazás projektjének könyvtárából a következő paranccsal:

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

    Ha az egyéni beépített összekötő bővítményének telepítése sikerült, a következő példához hasonló kimenetet kap:

    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. Ha valamelyikfunc.exe folyamat fut, a következő lépés folytatása előtt mindenképpen zárja be vagy lépjen ki a folyamatból.

Az összekötő tesztelése

  1. A Visual Studio Code-ban nyissa meg a Standard logikai alkalmazást és az üres munkafolyamatot a tervezőben.

  2. A tervezőfelületen válassza a Művelet kiválasztása lehetőséget az összekötőműveletek választójának megnyitásához.

  3. A műveletek keresőmezőjében válassza a Beépített lehetőséget. A keresőmezőbe írja be a cosmos db kifejezést.

    A műveletválasztó megjeleníti az egyéni beépített összekötőt és eseményindítót, például:

    Képernyőkép a Visual Studio Code-ról és egy standard logikai alkalmazás munkafolyamatának tervezőjével az új, egyéni beépített Azure Cosmos DB-összekötővel.

  4. Az Eseményindítók listában válassza ki az egyéni beépített eseményindítót a munkafolyamat elindításához.

  5. A kapcsolat panelen adja meg a következő tulajdonságértékeket a kapcsolat létrehozásához, például:

    Tulajdonság Kötelező Érték Leírás
    Kapcsolat neve Yes <Azure-Cosmos-DB-connection-name> A létrehozandó Azure Cosmos DB-kapcsolat neve
    Kapcsolati sztring Yes <Azure Cosmos DB-DB-connection-string> Az Azure Cosmos DB adatbázis-gyűjteményének vagy bérletgyűjteményének kapcsolati sztring, ahol minden új fogadott dokumentumot fel szeretne venni.

    Képernyőkép a kapcsolatpanelről az összekötő első használatakor.

  6. Ha elkészült, válassza a Létrehozás lehetőséget.

  7. Az eseményindító tulajdonságai panelen adja meg az eseményindító következő tulajdonságértékeit, például:

    Tulajdonság Kötelező Érték Leírás
    Adatbázis neve Yes <Azure-Cosmos-DB-database-name> A használni kívánt Azure Cosmos DB-adatbázis neve
    Gyűjtemény neve Yes <Azure-Cosmos-DB-collection-name> Annak az Azure Cosmos DB-gyűjteménynek a neve, amelyhez hozzá szeretné adni az egyes új fogadott dokumentumokat.

    Képernyőkép az eseményindító tulajdonságai panelről.

    Ebben a példában kódnézetben a munkafolyamat-definíció, amely a workflow.json fájlban található, egy triggers JSON-objektummal rendelkezik, amely az alábbi példához hasonlóan jelenik meg:

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

    A connections.json fájlban található kapcsolatdefiníció egy serviceProviderConnections JSON-objektummal rendelkezik, amely az alábbi példához hasonlóan jelenik meg:

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

  8. A Visual Studio Code Futtatás menüjében válassza a Hibakeresés indítása lehetőséget. (Nyomja le az F5 billentyűt)

  9. A munkafolyamat elindításához nyissa meg az Azure Cosmos DB-fiókot a Azure Portal. A fiók menüben válassza a Data Explorer lehetőséget. Keresse meg az eseményindítóban megadott adatbázist és gyűjteményt. Elem hozzáadása a gyűjteményhez.

    Képernyőkép a Azure Portal, az Azure Cosmos DB-fiókról és a Data Explorer a megadott adatbázishoz és gyűjteményhez való megnyitásáról.

Következő lépések