Tworzenie niestandardowych łączników wbudowanych dla aplikacji logiki w warstwie Standardowa w usłudze Azure Logic Apps z jedną dzierżawą

Dotyczy: Azure Logic Apps (wersja Standardowa)

Jeśli potrzebujesz łączników, które nie są dostępne w standardowych przepływach pracy aplikacji logiki, możesz utworzyć własne wbudowane łączniki przy użyciu tego samego modelu rozszerzalności, który jest używany przez wbudowane łączniki dostawcy usług dostępne dla standardowych przepływów pracy w usłudze Azure Logic Apps z jedną dzierżawą. Ten model rozszerzalności jest oparty na modelu rozszerzalności Azure Functions.

W tym artykule pokazano, jak utworzyć przykładowy wbudowany łącznik usługi Azure Cosmos DB, który ma jeden wyzwalacz oparty na Azure Functions i nie zawiera żadnych akcji. Wyzwalacz jest uruchamiany po dodaniu nowego dokumentu do kolekcji dzierżawy lub kontenera w usłudze Azure Cosmos DB, a następnie uruchamia przepływ pracy, który używa ładunku wejściowego jako dokumentu usługi Azure Cosmos DB.

Operacja Szczegóły operacji Opis
Wyzwalacz Po odebraniu dokumentu Ta operacja wyzwalacza jest uruchamiana, gdy operacja wstawiania odbywa się w określonej bazie danych i kolekcji usługi Azure Cosmos DB.
Akcja Brak Ten łącznik nie definiuje żadnych operacji akcji.

Ten przykładowy łącznik używa tych samych funkcji co wyzwalacz usługi Azure Cosmos DB dla Azure Functions, który jest oparty na wyzwalaczach i powiązaniach Azure Functions. Aby zapoznać się z kompletnym przykładem, zapoznaj się z przykładowym niestandardowym łącznikiem usługi Azure Cosmos DB — Rozszerzenia łącznika usługi Azure Logic Apps.

Aby uzyskać więcej informacji, zapoznaj się z następującą dokumentacją:

Wymagania wstępne

Kroki ogólne

W poniższym konspekcie opisano ogólne kroki tworzenia przykładowego łącznika:

  1. Utwórz projekt biblioteki klas.

  2. W projekcie dodaj pakiet NuGet Microsoft.Azure.Workflows.WebJobs.Extension jako odwołanie nuGet.

  3. Podaj operacje dla wbudowanego łącznika przy użyciu pakietu NuGet w celu zaimplementowania metod dla interfejsów o nazwach IServiceOperationsProvider i IServiceOperationsTriggerProvider.

  4. Zarejestruj niestandardowy wbudowany łącznik przy użyciu rozszerzenia środowiska uruchomieniowego Azure Functions.

  5. Zainstaluj łącznik do użycia.

Tworzenie projektu biblioteki klas

  1. W Visual Studio Code utwórz projekt biblioteki klas platformy .NET Core 3.1.

  2. W projekcie dodaj pakiet NuGet o nazwie Microsoft.Azure.Workflows.WebJobs.Extension jako odwołanie NuGet.

Implementowanie interfejsu dostawcy usług

Aby zapewnić operacje dla przykładowego wbudowanego łącznika, w pakiecie NuGet Microsoft.Azure.Workflows.WebJobs.Extension zaimplementuj metody dla następujących interfejsów. Na poniższym diagramie przedstawiono interfejsy z implementacjami metod oczekiwanymi przez projektanta i środowiska uruchomieniowego usługi Azure Logic Apps dla niestandardowego wbudowanego łącznika z wyzwalaczem opartym na Azure Functions:

Koncepcyjny diagram klas przedstawiający implementację metody dla przykładowego niestandardowego łącznika wbudowanego usługi Azure Cosmos DB.

IServiceOperationsProvider

Ten interfejs zawiera następujące metody, które zapewniają manifest operacji i wykonują określone zadania dostawcy usług lub rzeczywistą logikę biznesową w niestandardowym wbudowanym łączniku. Aby uzyskać więcej informacji, zobacz IServiceOperationsProvider.

  • GetService()

    Projektant w usłudze Azure Logic Apps wymaga metody GetService(), aby pobrać metadane wysokiego poziomu dla usługi niestandardowej, w tym opis usługi, parametry wejściowe połączenia wymagane w projektancie, możliwości, kolor marki, adres URL ikony itd.

  • GetOperations()

    Projektant w usłudze Azure Logic Apps wymaga metody GetOperations(), aby pobrać operacje zaimplementowane przez usługę niestandardową. Lista operacji jest oparta na schemacie struktury Swagger. Projektant używa również metadanych operacji do zrozumienia parametrów wejściowych dla określonych operacji i wygenerowania danych wyjściowych jako tokenów właściwości na podstawie schematu danych wyjściowych dla operacji.

  • GetBindingConnectionInformation()

    Jeśli wyzwalacz jest typem wyzwalacza opartego na Azure Functions, środowisko uruchomieniowe w usłudze Azure Logic Apps wymaga metody GetBindingConnectionInformation(), aby podać wymagane informacje o parametrach połączenia do powiązania wyzwalacza Azure Functions.

  • InvokeOperation()

    Jeśli łącznik zawiera akcje, środowisko uruchomieniowe w usłudze Azure Logic Apps wymaga metody InvokeOperation(), aby wywołać każdą akcję w łączniku, która jest uruchamiana podczas wykonywania przepływu pracy. Jeśli łącznik nie ma akcji, nie musisz implementować metody InvokeOperation().

    W tym przykładzie niestandardowy łącznik wbudowany usługi Azure Cosmos DB nie ma akcji. Jednak metoda jest uwzględniona w tym przykładzie na potrzeby kompletności.

Aby uzyskać więcej informacji na temat tych metod i ich implementacji, zapoznaj się z tymi metodami w dalszej części tego artykułu.

IServiceOperationsTriggerProvider

Możesz dodać lub uwidocznić wyzwalacz Azure Functions lub akcję jako wyzwalacz dostawcy usług w niestandardowym wbudowanym łączniku. Aby użyć typu wyzwalacza opartego na Azure Functions i tego samego powiązania Azure Functions co wyzwalacz łącznika zarządzanego platformy Azure, zaimplementuj następujące metody, aby zapewnić informacje o połączeniu i powiązania wyzwalacza zgodnie z wymaganiami Azure Functions. Aby uzyskać więcej informacji, zobacz IServiceOperationsTriggerProvider.

  • Metoda GetFunctionTriggerType() jest wymagana do zwrócenia ciągu, który jest taki sam jak parametr typu w powiązaniu wyzwalacza Azure Functions.

  • GetFunctionTriggerDefinition() ma domyślną implementację, więc nie trzeba jawnie implementować tej metody. Jeśli jednak chcesz zaktualizować domyślne zachowanie wyzwalacza, takie jak podanie dodatkowych parametrów, których projektant nie uwidacznia, możesz zaimplementować tę metodę i zastąpić domyślne zachowanie.

Metody implementowania

W poniższych sekcjach opisano metody implementowane przez przykładowy łącznik. Pełny przykład można znaleźć w pliku Sample CosmosDbServiceOperationProvider.cs.

GetService()

Projektant wymaga następującej metody, aby uzyskać ogólny opis usługi:

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

GetOperations()

Projektant wymaga następującej metody, aby uzyskać operacje zaimplementowane przez usługę. Ta lista operacji jest oparta na schemacie struktury Swagger.

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

GetBindingConnectionInformation()

Aby użyć typu wyzwalacza opartego na Azure Functions, poniższa metoda udostępnia wymagane informacje o parametrach połączenia do powiązania wyzwalacza Azure Functions.

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

InvokeOperation()

Przykładowy niestandardowy wbudowany łącznik usługi Azure Cosmos DB nie zawiera akcji, ale następująca metoda jest uwzględniona pod kątem kompletności:

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

GetFunctionTriggerType()

Aby użyć wyzwalacza opartego na Azure Functions jako wyzwalacza w łączniku, należy zwrócić ciąg, który jest taki sam jak parametr typu w powiązaniu wyzwalacza Azure Functions.

Poniższy przykład zwraca ciąg wbudowanego wyzwalacza "type": "cosmosDBTrigger"usługi Azure Cosmos DB:

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

GetFunctionTriggerDefinition()

Ta metoda ma domyślną implementację, więc nie trzeba jawnie implementować tej metody. Jeśli jednak chcesz zaktualizować domyślne zachowanie wyzwalacza, takie jak podanie dodatkowych parametrów, których projektant nie uwidacznia, możesz zaimplementować tę metodę i zastąpić domyślne zachowanie.

Rejestrowanie łącznika

Aby załadować niestandardowe wbudowane rozszerzenie łącznika podczas procesu uruchamiania środowiska uruchomieniowego Azure Functions, należy dodać rejestrację rozszerzenia Azure Functions jako zadanie uruchamiania i zarejestrować łącznik jako dostawcę usług na liście dostawców usług. Na podstawie typu danych, których potrzebuje wbudowany wyzwalacz jako dane wejściowe, opcjonalnie dodaj konwerter. W tym przykładzie typ danych Dokumentu dla dokumentów usługi Azure Cosmos DB jest konwertowany na tablicę JObject .

W poniższych sekcjach pokazano, jak zarejestrować niestandardowy wbudowany łącznik jako rozszerzenie Azure Functions.

Tworzenie zadania uruchamiania

  1. Utwórz klasę uruchamiania przy użyciu atrybutu zestawu o nazwie [assembly:WebJobsStartup].

  2. Zaimplementuj interfejs IWebJobsStartup . W metodzie Configure() zarejestruj rozszerzenie i wstrzykuj dostawcę usług.

    Na przykład poniższy fragment kodu przedstawia implementację klasy uruchamiania dla przykładowego niestandardowego wbudowanego łącznika usługi 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>();
          }
       }
    }
    

    Aby uzyskać więcej informacji, zobacz Rejestrowanie usług — używanie iniekcji zależności na platformie .NET Azure Functions.

Rejestrowanie dostawcy usług

Teraz zarejestruj implementację dostawcy usług jako rozszerzenie Azure Functions za pomocą aparatu usługi Azure Logic Apps. W tym przykładzie użyto wbudowanego wyzwalacza usługi Azure Cosmos DB dla Azure Functions jako nowego wyzwalacza. W tym przykładzie zarejestrowano również nowego dostawcę usług Azure Cosmos DB dla istniejącej listy dostawców usług, która jest już częścią rozszerzenia usługi Azure Logic Apps. Aby uzyskać więcej informacji, zobacz Rejestrowanie rozszerzeń powiązań 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);
      }
   }
}

Dodawanie konwertera

Usługa Azure Logic Apps ma ogólny sposób obsługi każdego Azure Functions wbudowanego wyzwalacza przy użyciu tablicy JObject. Jeśli jednak chcesz przekonwertować listę dokumentów usługi Azure Cosmos DB tylko do odczytu na tablicę JObject , możesz dodać konwerter. Gdy konwerter jest gotowy, zarejestruj konwerter w ramach elementu ExtensionConfigContext , jak pokazano wcześniej w tym przykładzie:

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

Diagram biblioteki klas dla wdrożonych klas

Po zakończeniu zapoznaj się z poniższym diagramem klasy, który pokazuje implementację dla wszystkich klas w pakiecie rozszerzeń Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll :

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Koncepcyjny diagram mapy kodu przedstawiający kompletną implementację klasy.

Instalowanie łącznika

Aby dodać odwołanie nuGet z poprzedniej sekcji, w pakiecie rozszerzeń o nazwie Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dllzaktualizuj plik extensions.json . Aby uzyskać więcej informacji, przejdź do repozytorium Azure/logicapps-connector-extensions i przejrzyj skrypt programu PowerShell o nazwie add-extension.ps1.

  1. Zaktualizuj pakiet rozszerzeń, aby uwzględnić niestandardowy wbudowany łącznik.

  2. W Visual Studio Code, które powinny mieć zainstalowane rozszerzenie usługi Azure Logic Apps (Standard) dla Visual Studio Code, utworzyć projekt aplikacji logiki i zainstalować pakiet rozszerzeń przy użyciu następującego polecenia programu PowerShell:

    Program PowerShell

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

    Alternatywnie z katalogu projektu aplikacji logiki przy użyciu wiersza polecenia programu PowerShell uruchom skrypt programu PowerShell o nazwie add-extension.ps1:

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

    Bash

    Aby zamiast tego użyć powłoki Bash, w katalogu projektu aplikacji logiki uruchom skrypt programu PowerShell za pomocą następującego polecenia:

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

    Jeśli rozszerzenie dla niestandardowego wbudowanego łącznika zostało pomyślnie zainstalowane, otrzymasz dane wyjściowe podobne do następującego przykładu:

    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. Jeśli jakikolwiek proces func.exe jest uruchomiony, pamiętaj, aby zamknąć lub zakończyć ten proces, zanim przejdziesz do następnego kroku.

Testowanie łącznika

  1. W Visual Studio Code otwórz aplikację logiki w warstwie Standardowa i pusty przepływ pracy w projektancie.

  2. Na powierzchni projektanta wybierz pozycję Wybierz operację , aby otworzyć selektor operacji łącznika.

  3. W polu wyszukiwania operacji wybierz pozycję Wbudowane. W polu wyszukiwania wprowadź cosmos db.

    Selektor operacji przedstawia niestandardowy wbudowany łącznik i wyzwalacz, na przykład:

    Zrzut ekranu przedstawiający Visual Studio Code i projektanta standardowego przepływu pracy aplikacji logiki z nowym niestandardowym wbudowanym łącznikiem usługi Azure Cosmos DB.

  4. Z listy Wyzwalacze wybierz niestandardowy wbudowany wyzwalacz, aby uruchomić przepływ pracy.

  5. W okienku połączenia podaj następujące wartości właściwości, aby utworzyć połączenie, na przykład:

    Właściwość Wymagany Wartość Opis
    Nazwa połączenia Tak <Azure-Cosmos-DB-connection-name> Nazwa połączenia usługi Azure Cosmos DB do utworzenia
    Parametry połączenia Tak <Parametry połączenia usługi Azure Cosmos DB> Parametry połączenia dla kolekcji bazy danych lub kolekcji dzierżawy usługi Azure Cosmos DB, w których chcesz dodać każdy nowy odebrany dokument.

    Zrzut ekranu przedstawiający okienko połączenia podczas korzystania z łącznika po raz pierwszy.

  6. Gdy wszystko będzie gotowe, wybierz przycisk Utwórz.

  7. W okienku właściwości wyzwalacza podaj następujące wartości właściwości wyzwalacza, na przykład:

    Właściwość Wymagany Wartość Opis
    Nazwa bazy danych Tak <Azure-Cosmos-DB-database-name> Nazwa bazy danych usługi Azure Cosmos DB do użycia
    Nazwa kolekcji Tak <Azure-Cosmos-DB-collection-name> Nazwa kolekcji usługi Azure Cosmos DB, w której chcesz dodać każdy nowy odebrany dokument.

    Zrzut ekranu przedstawiający okienko właściwości wyzwalacza.

    W tym przykładzie w widoku kodu definicja przepływu pracy, która znajduje się w pliku workflow.json , ma triggers obiekt JSON podobny do następującego przykładu:

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

    Definicja połączenia, która znajduje się w pliku connections.json , ma serviceProviderConnections obiekt JSON, który jest podobny do następującego przykładu:

    {
       "serviceProviderConnections": {
          "cosmosDb": {
             "parameterValues": {
                "connectionString": "@appsetting('cosmosDb_connectionString')"
             },
             "serviceProvider": {
                "id": "/serviceProviders/CosmosDb"
             },
             "displayName": "myCosmosDbConnection"
          }
       },
       "managedApiConnections": {}
    }
    
  8. W Visual Studio Code w menu Uruchom wybierz pozycję Rozpocznij debugowanie. (Naciśnij klawisz F5)

  9. Aby wyzwolić przepływ pracy, otwórz konto usługi Azure Cosmos DB w Azure Portal. W menu konta wybierz pozycję Data Explorer. Przejdź do bazy danych i kolekcji określonej w wyzwalaczu. Dodaj element do kolekcji.

    Zrzut ekranu przedstawiający Azure Portal, konto usługi Azure Cosmos DB i Data Explorer otwarte dla określonej bazy danych i kolekcji.

Następne kroki