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

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

Se sono necessari connettori che non sono 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 del provider di servizi disponibili per i flussi di lavoro Standard in App per la logica di Azure a tenant singolo. Questo modello di estendibilità si basa sul modello di estendibilità Funzioni di Azure.

Questo articolo illustra come creare un esempio di connettore predefinito di Azure Cosmos DB, con un singolo trigger basato su Funzioni di Azure e nessuna azione. Il trigger viene generato quando un nuovo documento viene aggiunto alla raccolta di lease 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 trigger viene eseguita quando si verifica un'operazione di inserimento nel database e nella raccolta di Azure Cosmos DB specificati.
Azione	Nessuno	Questo connettore non definisce operazioni di azione.

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

Per altre informazioni, vedere la documentazione seguente:

• Connettori personalizzati per app per la logica Standard
• Connettori predefiniti basati sul provider di servizi
• App per la logica di Azure a tenant singolo

Prerequisiti

• Un account e una sottoscrizione di Azure. Se non si ha una sottoscrizione, è possibile iscriversi per creare un account Azure gratuito.

• Informazioni di base sulle app per la logica di Azure a tenant singolo, sui flussi di lavoro dell'app per la logica Standard, sui connettori e su come usare Visual Studio Code per la creazione di flussi di lavoro basati su tenant singolo. Per altre informazioni, vedere la documentazione seguente:

  • Ambiente del servizio di integrazione e multi-tenant per App per la logica di Azure

  • Creare un flusso di lavoro di integrazione con App per la logica di Azure a tenant singolo (Standard) - portale di Azure

• Visual Studio Code con l'estensione App per la logica di Azure (Standard) e altri prerequisiti installati. L'installazione deve includere già il pacchetto NuGet per Microsoft.Azure.Workflow.WebJobs.Extension.

  Nota

  Questa funzionalità di creazione è attualmente disponibile solo in Visual Studio Code.

• Un account, un database e una raccolta di Azure Cosmos DB. Per altre informazioni, vedere Guida introduttiva: Creare un account, un database, un database, un contenitore e elementi di Azure Cosmos DB dall'portale di Azure.

Procedure generali

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

1. Creare un progetto Libreria di classi.

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

3. Specificare 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 di runtime Funzioni di Azure.

5. Installare il connettore da usare.

Creare il progetto della 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.Workflow.WebJobs.Extension come riferimento a NuGet.

Implementare l'interfaccia del provider di servizi

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

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, inclusa 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 di operazioni si basa 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 runtime in App per la logica di Azure richiede il metodo GetBindingConnectionInformation() per fornire le informazioni sui parametri di connessione necessari all'associazione di trigger Funzioni di Azure.

• InvokeOperation()

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

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

Per altre informazioni su questi metodi e sulla relativa implementazione, esaminare questi metodi più avanti in questo articolo.

IServiceOperationsTriggerProvider

È possibile aggiungere o esporre un trigger o un'azione 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 Funzioni di Azure del trigger del connettore gestito di Azure, implementare i metodi seguenti per fornire le informazioni di connessione e le associazioni trigger, come richiesto da 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 Funzioni di Azure.

• GetFunctionTriggerDefinition() 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.

Metodi da implementare

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

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. Questo elenco di operazioni si basa 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 sui parametri di connessione necessari per l'associazione di trigger 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 ha azioni, ma il metodo seguente è incluso per la completezza:

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 tipo nell'associazione di trigger Funzioni di Azure.

Nell'esempio seguente viene restituita la stringa per il trigger predefinito di Azure Cosmos DB, "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 predefinita personalizzata del connettore 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 per il trigger predefinito come input, aggiungere facoltativamente il convertitore. In questo esempio viene convertito il tipo di dati Documento per i documenti di Azure Cosmos DB in una matrice JObject .

Le sezioni seguenti illustrano come registrare il connettore predefinito personalizzato come estensione 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 Configure() 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 predefinito predefinito di Azure Cosmos DB 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 .NET Funzioni di Azure.

Registrare il provider di servizi

Registrare ora l'implementazione del provider di servizi come estensione Funzioni di Azure con il motore 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 associazione 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 la matrice JObject. Tuttavia, se si vuole convertire l'elenco di sola lettura dei documenti di Azure Cosmos DB in una matrice 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 della classe seguente che mostra l'implementazione per tutte le classi nel bundle di estensione Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll :

• CosmosDbServiceOperationsProvider
• CosmosDbServiceProvider
• CosmosDbServiceProviderStartup

Installare il connettore

Per aggiungere il riferimento NuGet dalla sezione precedente, nel bundle di estensione denominato Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, aggiornare il file extensions.json . Per altre informazioni, passare al repository Azure/logicapps-connector-extensions e 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 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 l'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 processofunc.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 il flusso di lavoro vuoto nella finestra di progettazione.

2. Nell'area di progettazione selezionare Scegli un'operazione per aprire la selezione 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:

   

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à	Obbligatoria	valore	Descrizione
   Nome connessione	Sì	<Azure-Cosmos-DB-connection-name>	Nome della connessione di Azure Cosmos DB da creare
   Stringa di connessione	Sì	<Azure Cosmos DB-DB-connection-string>	Stringa di connessione per la raccolta di database di Azure Cosmos DB o la raccolta lease in cui si vuole aggiungere ogni nuovo documento ricevuto.

   

6. Al termine, selezionare Crea.

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

   Proprietà	Obbligatoria	valore	Descrizione
   Nome database	Sì	<Azure-Cosmos-DB-database-name>	Nome del database di Azure Cosmos DB da usare
   Nome raccolta	Sì	<Azure-Cosmos-DB-collection-name>	Nome dell'insieme Azure Cosmos DB in cui si desidera aggiungere ogni nuovo documento ricevuto.

   

   In questo esempio, nella visualizzazione codice, la definizione del flusso di lavoro, che si trova nel file workflow.json , ha un triggers oggetto JSON 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 serviceProviderConnections oggetto JSON simile all'esempio seguente:

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

8. In Visual Studio Code selezionare Avvia debug dal menu Esegui. (Premere F5)

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

   

Passaggi successivi

• Origine per il connettore predefinito personalizzato di Azure Cosmos DB - Estensioni del connettore app per la logica di Azure

• Trigger del bus di servizio predefinito: gestione batch e sessione