Creare connettori predefiniti personalizzati per app per la logica Standard in App per la logica di Azure a tenant singolo

  • Articolo

Si applica: App per la logica di Azure (Standard)

Se sono necessari connettori non disponibili nei flussi di lavoro dell'App per la logica Standard, è possibile creare connettori predefiniti usando lo stesso modello di estendibilità usato dai connettori predefiniti basati su provider di servizi disponibili per i flussi di lavoro Standard nelle App per la logica di Azure a tenant singolo. Questo modello di estendibilità si basa sul modello di estendibilità di Funzioni di Azure.

Questo articolo illustra come creare un esempio di connettore predefinito di Azure Cosmos DB, che include un singolo trigger basato su Funzioni di Azure e nessuna azione. Il trigger viene attivato quando un nuovo documento viene aggiunto alla raccolta di leasing o al contenitore in Azure Cosmos DB e quindi esegue un flusso di lavoro che usa il payload di input come documento di Azure Cosmos DB.

Operazione Dettagli dell'operazione Descrizione
Trigger Quando viene ricevuto un documento Questa operazione di trigger viene eseguita quando si verifica un'operazione di inserimento nel database e nella raccolta di Azure Cosmos DB specificati.
Azione None Questo connettore non definisce alcuna operazione di azione.

Questo connettore di esempio usa la stessa funzionalità del trigger di Azure Cosmos DB per Funzioni di Azure, basato su trigger e binding di Funzioni di Azure. Per l'esempio completo, vedere Esempio di connettore predefinito di Azure Cosmos DB - Estensioni del connettore di App per la logica di Azure.

Per altre informazioni, vedere la documentazione seguente:

Prerequisiti

Procedura generale

La struttura seguente descrive i passaggi generali per compilare il connettore di esempio:

  1. Creare un progetto Libreria di classi.

  2. Nel progetto aggiungere il pacchetto NuGet Microsoft.Azure.Workflows.WebJobs.Extension come riferimento NuGet.

  3. Fornire le operazioni per il connettore predefinito usando il pacchetto NuGet per implementare i metodi per le interfacce denominate IServiceOperationsProvider e IServiceOperationsTriggerProvider.

  4. Registrare il connettore predefinito personalizzato con l'estensione runtime di Funzioni di Azure.

  5. Installare il connettore per l'uso.

Creare il progetto di libreria di classi

  1. In Visual Studio Code creare un progetto di libreria di classi .NET Core 3.1.

  2. Nel progetto aggiungere il pacchetto NuGet denominato Microsoft.Azure.Workflows.WebJobs.Extension come riferimento NuGet.

Implementare l'interfaccia del provider di servizi

Per fornire le operazioni per il connettore predefinito di esempio, nel pacchetto NuGet Microsoft.Azure.Workflows.WebJobs.Extension implementare i metodi per le interfacce seguenti. Il diagramma seguente mostra le interfacce con le implementazioni del metodo previste dalla finestra di progettazione e dal runtime di App per la logica di Azure per un connettore predefinito personalizzato che contiene un trigger basato su Funzioni di Azure:

Diagramma classi concettuale che illustra l'implementazione del metodo per il connettore predefinito personalizzato di Azure Cosmos DB di esempio.

IServiceOperationsProvider

Questa interfaccia include i metodi seguenti che forniscono il manifesto dell'operazione ed esegue le attività specifiche del provider di servizi o la logica di business effettiva nel connettore predefinito personalizzato. Per altre informazioni, vedere IServiceOperationsProvider.

  • GetService()

    La finestra di progettazione in App per la logica di Azure richiede il metodo GetService() per recuperare i metadati di alto livello per il servizio personalizzato, tra cui la descrizione del servizio, i parametri di input di connessione necessari per la finestra di progettazione, le funzionalità, il colore del marchio, l'URL dell'icona e così via.

  • GetOperations()

    La finestra di progettazione in App per la logica di Azure richiede il metodo GetOperations() per recuperare le operazioni implementate dal servizio personalizzato. L'elenco delle operazioni è basato sullo schema Swagger. La finestra di progettazione usa anche i metadati dell'operazione per comprendere i parametri di input per operazioni specifiche e generare gli output come token di proprietà, in base allo schema dell'output per un'operazione.

  • GetBindingConnectionInformation()

    Se il trigger è un tipo di trigger basato su Funzioni di Azure, il metodo GetBindingConnectionInformation() viene usato dal runtime in App per la logica di Azure per fornire le informazioni necessarie sui parametri di connessione al binding di trigger di Funzioni di Azure.

  • InvokeOperation()

    Se il connettore ha azioni, il runtime di App per la logica di Azure necessita del metodo InvokeOperation() per chiamare ogni azione nel connettore eseguita durante l'esecuzione del flusso di lavoro. Se il connettore non dispone di azioni, non è necessario implementare il metodo InvokeOperation().

    In questo esempio, il connettore predefinito personalizzato di Azure Cosmos DB non include azioni. Tuttavia, il metodo viene incluso in questo esempio per completezza.

Per altre informazioni su questi metodi e sulla relativa implementazione, vedere questi metodi più avanti nell'articolo.

IServiceOperationsTriggerProvider

È possibile aggiungere o esporre un trigger o un'azione di Funzioni di Azure come trigger del provider di servizi nel connettore predefinito personalizzato. Per usare il tipo di trigger basato su Funzioni di Azure e lo stesso binding di Funzioni di Azure del trigger del connettore gestito di Azure, implementare i metodi seguenti per fornire le informazioni di connessione e le associazioni di trigger in base alle esigenze di Funzioni di Azure. Per altre informazioni, vedere IServiceOperationsTriggerProvider.

  • Il metodo GetFunctionTriggerType() è necessario per restituire la stringa uguale al parametro di tipo nell'associazione di trigger di Funzioni di Azure.

  • GetFunctionTriggerDefinition() ha un'implementazione predefinita, pertanto non è necessario implementare in modo esplicito questo metodo. Tuttavia, se si vuole aggiornare il comportamento predefinito del trigger, ad esempio fornire parametri aggiuntivi che la finestra di progettazione non espone, è possibile implementare questo metodo ed eseguire l'override del comportamento predefinito.

Metodi da implementare

Le sezioni seguenti descrivono i metodi implementati dal connettore di esempio. Per l'esempio completo, vedere CosmosDbServiceOperationProvider.cs di esempio.

Importante

Quando si dispone di informazioni sensibili, ad esempio stringhe di connessione che includono nomi utente e password, assicurarsi di usare il flusso di autenticazione più sicuro disponibile. Ad esempio, Microsoft consiglia di autenticare l'accesso alle risorse di Azure con un'identità gestita quando è disponibile il supporto e assegnare un ruolo con il privilegio minimo richiesto.

Se questa funzionalità non è disponibile, assicurarsi di proteggere le stringhe di connessione tramite altre misure, ad esempio Azure Key Vault, che è possibile usare con le impostazioni dell'app. È quindi possibile fare riferimento direttamente a stringhe sicure, ad esempio stringhe di connessione e chiavi. Analogamente ai modelli ARM, in cui è possibile definire le variabili di ambiente in fase di distribuzione, è possibile indicare le impostazioni dell'app all'interno della definizione del flusso di lavoro dell'app per la logica. È quindi possibile acquisire valori di infrastruttura generati dinamicamente, ad esempio endpoint di connessione, stringhe di archiviazione e altri. Per altre informazioni, vedere Tipi di applicazione per Microsoft Identity Platform.

GetService()

La finestra di progettazione richiede il metodo seguente per ottenere la descrizione generale per il servizio:

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

GetOperations()

La finestra di progettazione richiede il metodo seguente per ottenere le operazioni implementate dal servizio. L'elenco delle operazioni è basato sullo schema Swagger.

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

GetBindingConnectionInformation()

Per usare il tipo di trigger basato su Funzioni di Azure, il metodo seguente fornisce le informazioni necessarie sui parametri di connessione per il binding di trigger di Funzioni di Azure.

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

InvokeOperation()

L'esempio di connettore predefinito personalizzato di Azure Cosmos DB non include azioni, ma per completezza è incluso il metodo seguente:

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

GetFunctionTriggerType()

Per usare un trigger basato su Funzioni di Azure come trigger nel connettore, è necessario restituire la stringa uguale al parametro di ipo nell'associazione di trigger di Funzioni di Azure.

L'esempio seguente restituisce la stringa per il trigger predefinito di Azure Cosmos DB predefinito, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Questo metodo ha un'implementazione predefinita, quindi non è necessario implementare in modo esplicito questo metodo. Tuttavia, se si vuole aggiornare il comportamento predefinito del trigger, ad esempio fornire parametri aggiuntivi che la finestra di progettazione non espone, è possibile implementare questo metodo ed eseguire l'override del comportamento predefinito.

Registrare il connettore

Per caricare l'estensione del connettore predefinita personalizzata durante il processo di avvio del runtime di Funzioni di Azure, è necessario aggiungere la registrazione dell'estensione Funzioni di Azure come processo di avvio e registrare il connettore come provider di servizi nell'elenco dei provider di servizi. In base al tipo di dati necessari al trigger predefinito come input, aggiungere facoltativamente il convertitore. Questo esempio converte il tipo di dati Documento per i documenti di Azure Cosmos DB in un array JObject.

Le sezioni seguenti illustrano come registrare il connettore predefinito personalizzato come estensione di Funzioni di Azure.

Creare il processo di avvio

  1. Creare una classe di avvio usando l'attributo assembly denominato [assembly:WebJobsStartup].

  2. Implementare l'interfaccia IWebJobsStartup. Nel metodo Configura() registrare l'estensione e inserire il provider di servizi.

    Ad esempio, il frammento di codice seguente mostra l'implementazione della classe di avvio per il connettore Azure Cosmos DB personalizzato di esempio:

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

    Per altre informazioni, vedere Registrare i servizi - Usare l'inserimento delle dipendenze in Funzioni di Azure .NET.

Registrare il provider di servizi

Registrare ora l'implementazione del provider di servizi come estensione di Funzioni di Azure con il motore di App per la logica di Azure. Questo esempio usa il trigger predefinito di Azure Cosmos DB per Funzioni di Azure come nuovo trigger. Questo esempio registra anche il nuovo provider di servizi Azure Cosmos DB per un elenco esistente di provider di servizi, che fa già parte dell'estensione App per la logica di Azure. Per altre informazioni, vedere Registrare le estensioni di binding di Funzioni di Azure.

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

Aggiungere un convertitore

App per la logica di Azure offre un modo generico per gestire qualsiasi trigger predefinito di Funzioni di Azure usando l'array JObject. Tuttavia, se si desidera convertire l'elenco di sola lettura dei documenti di Azure Cosmos DB in un array JObject, è possibile aggiungere un convertitore. Quando il convertitore è pronto, registrare il convertitore come parte di ExtensionConfigContext come illustrato in precedenza in questo esempio:

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

Diagramma della libreria di classi per le classi implementate

Al termine, esaminare il diagramma classi seguente che mostra l'implementazione di tutte le classi nel bundle di estensione Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll:

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Diagramma della mappa del codice concettuale che mostra l'implementazione completa della classe.

Installare il connettore

Per aggiungere il riferimento NuGet dalla sezione precedente, nel bundle di estensione denominato Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dllaggiornare il file extensions.json. Per altre informazioni, vedere il repository Azure/logicapps-connector-extensions ed esaminare lo script di PowerShell denominato add-extension.ps1.

  1. Aggiornare il bundle di estensione per includere il connettore predefinito personalizzato.

  2. In Visual Studio Code, che deve avere installato l'estensione App per la logica di Azure (Standard) per Visual Studio Code, creare un progetto di App per la logica e installare il pacchetto di estensione usando il comando di PowerShell seguente:

    PowerShell

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

    In alternativa, dalla directory del progetto dell'App per la logica usando un prompt di PowerShell eseguire lo script di PowerShell denominato add-extension.ps1:

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

    Bash

    Per usare invece Bash, dalla directory del progetto dell'App per la logica, eseguire lo script di PowerShell con il comando seguente:

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

    Se l'estensione per il connettore predefinito personalizzato è stata installata correttamente, si ottiene un output simile all'esempio seguente:

    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. Se un processo func.exe è in esecuzione, assicurarsi di chiudere o uscire dal processo prima di continuare con il passaggio successivo.

Testare il connettore

  1. In Visual Studio Code aprire l'App per la logica Standard e un flusso di lavoro vuoto nella finestra di progettazione.

  2. Nell'area di progettazione selezionare Scegli un'operazione per aprire la selezione delle operazioni del connettore.

  3. Nella casella di ricerca delle operazioni selezionare Predefinita. Nella casella di ricerca immettere cosmos db.

    La selezione operazioni mostra il connettore e il trigger predefiniti personalizzati, ad esempio:

    Screenshot che mostra Visual Studio Code e la finestra di progettazione per un flusso di lavoro di App per la logica Standard con il nuovo connettore predefinito di Azure Cosmos DB personalizzato.

  4. Nell'elenco Trigger selezionare il trigger predefinito personalizzato per avviare il flusso di lavoro.

  5. Nel riquadro connessione specificare i valori delle proprietà seguenti per creare una connessione, ad esempio:

    Proprietà Richiesto Valore Descrizione
    Nome connessione Sì <Azure-Cosmos-DB-connection-name> Nome della connessione di Azure Cosmos DB da creare
    Stringa di connessione Sì < Ottenere la stringa di connessione di Azure Cosmos DB> Stringa di connessione per la raccolta di database o leasing di Azure Cosmos DB in cui si desidera aggiungere ogni nuovo documento ricevuto.

    Screenshot che mostra il riquadro di connessione quando si usa il connettore per la prima volta.

  6. Al termine, seleziona Crea.

  7. Nel riquadro delle proprietà del trigger specificare i valori delle proprietà seguenti per il trigger, ad esempio:

    Proprietà Richiesto Valore Descrizione
    Nome database Sì <Azure-Cosmos-DB-database-name> Nome del database Azure Cosmos DB da usare
    Nome raccolta Sì <Azure-Cosmos-DB-collection-name> Nome della raccolta di Azure Cosmos DB in cui si desidera aggiungere ogni nuovo documento ricevuto.

    Screenshot che mostra il riquadro delle proprietà del trigger.

    Per questo esempio, nella visualizzazione codice, la definizione del flusso di lavoro, che si trova nel file workflow.json, ha un oggetto JSON triggers simile all'esempio seguente:

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

    La definizione di connessione, che si trova nel file connections.json, ha un oggetto JSON serviceProviderConnections simile all'esempio seguente:

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

  8. In Visual Studio Code scegliere Avvia debug nel menu Esegui. (premere F5)

  9. Per attivare il flusso di lavoro, nel portale di Azure aprire l'account Azure Cosmos DB. Nel menu dell'account selezionare Esplora dati. Passare al database e alla raccolta specificati nel trigger. Aggiungere un elemento alla raccolta.

    Screenshot che mostra il portale di Azure, l'account Azure Cosmos DB e Esplora dati aperto al database e alla raccolta specificati.

Passaggi successivi