Créer des connecteurs intégrés personnalisés pour les applications logiques Standard dans des Azure Logic Apps à locataire unique

  • Article

S’applique à : Azure Logic Apps (Standard)

Si vous avez besoin de connecteurs qui ne sont pas disponibles dans les workflows d’application logique Standard, vous pouvez créer vos propres connecteurs intégrés à l’aide du même modèle d’extensibilité utilisé par des Connecteurs intégrés basés sur un fournisseur de services disponibles pour les workflows Standard dans les applications logiques Azure Logic monolocataires. Ce modèle d’extensibilité est basé sur le modèle d’extensibilité Azure Functions.

Cet article montre comment créer un exemple de connecteur Azure Cosmos DB intégré personnalisé, qui possède un seul déclencheur basé sur Azure Functions et aucune action. Le déclencheur s’active lorsqu'un nouveau document est ajouté à la collection ou au conteneur de location dans Azure Cosmos DB et exécute ensuite un workflow qui utilise la charge utile d'entrée comme document Azure Cosmos DB.

Opération Détails de l’opération Description
Déclencheur Lorsqu’un document est reçu Cette opération de déclencheur s’exécute lorsqu’une opération d’insertion se produit dans la base de données et la collection Azure Cosmos DB spécifiées.
Action None Ce connecteur ne définit aucune opération d’action.

Cet exemple de connecteur utilise la même fonctionnalité que le déclencheur Azure Cosmos DB pour Azure Functions, basé sur desdéclencheurs et des liaisons Azure Functions . Pour obtenir l’exemple complet, consultez Exemple de connecteur de base de données intégré Azure Cosmos DB personnalisé - Extensions de connecteur Azure Logic Apps.

Pour plus d’informations, consultez la documentation suivante :

Prérequis

Procédure générale

Le schéma suivant décrit les étapes de haut niveau pour construire l’exemple de connecteur :

  1. Créez un projet de bibliothèque de classes.

  2. Dans votre projet, ajoutez le package NuGet Microsoft.Azure.Workflows.WebJobs.Extension comme référence NuGet.

  3. Fournissez les opérations pour votre connecteur intégré en utilisant le package NuGet pour implémenter les méthodes des interfaces nommées IServiceOperationsProvider et IServiceOperationsTriggerProvider.

  4. Inscrivez votre connecteur intégré personnalisé avec l'extension runtime Azure Functions.

  5. Installez le connecteur à utiliser.

Créer votre projet de bibliothèque de classes

  1. Dans Visual Studio Code, créez un projet de bibliothèque de classes .NET Core 3.1.

  2. Dans votre projet, ajoutez le package NuGet nommé Microsoft.Azure.Workflows.WebJobs.Extension comme référence NuGet.

Implémenter l’interface du fournisseur de services

Pour fournir les opérations de l'exemple de connecteur intégré, implémentez les méthodes des interfaces suivantes dans le package NuGet Microsoft.Azure.Workflows.WebJobs.Extension. Le diagramme suivant montre les interfaces avec les implémentations de méthode attendues par le concepteur et le runtime Azure Logic Apps pour un connecteur intégré personnalisé avec un déclencheur basé sur Azure Functions :

Diagramme de classe conceptuel montrant l’implémentation de méthode pour un exemple de connecteur intégré Azure Cosmos DB.

IServiceOperationsProvider

Cette interface inclut les méthodes suivantes qui fournissent le manifeste des opérations et exécutent les tâches spécifiques de votre fournisseur de services ou la logique commerciale réelle dans votre connecteur intégré personnalisé. Pour plus d'informations, consultez IServiceOperationsProvider.

  • GetService()

    Le concepteur d'Azure Logic Apps requiert la méthode GetService() pour récupérer les métadonnées de haut niveau de votre service personnalisé, y compris la description du service, les paramètres d'entrée de connexion requis sur le concepteur, les capacités, la marque, l'URL de l'icône, etc.

  • GetOperations()

    Le concepteur d'Azure Logic Apps a besoin de la méthode GetOperations() pour récupérer les opérations implémentées par votre service personnalisé. La liste des opérations est basée sur le schéma Swagger. Le concepteur utilise également les métadonnées d’opération pour comprendre les paramètres d’entrée pour des opérations spécifiques et générer les sorties en tant que jetons de propriété, en fonction du schéma de la sortie pour une opération.

  • GetBindingConnectionInformation()

    Si votre déclencheur est un type de déclencheur Azure Functions, le runtime dans Azure Logic Apps nécessite la méthode GetBindingConnectionInformation() pour fournir les informations de paramètres de connexion requises pour la liaison de déclencheur Azure Functions.

  • InvokeOperation()

    Si votre connecteur a des actions, le runtime dans Azure Logic Apps nécessite la méthode InvokeOperation() pour appeler chaque action dans votre connecteur qui s’exécute pendant l’exécution du workflow. Si votre connecteur ne comporte pas d'actions, vous n'avez pas besoin d'implémenter la méthode InvokeOperation().

    Dans cet exemple, le connecteur intégré personnalisé Azure Cosmos DB n'a pas d'actions. Toutefois, la méthode est incluse dans cet exemple à des fin d’exhaustivité.

Pour plus d’informations sur ces méthodes et leur implémentation, consultez ces méthodes plus loin dans cet article.

IServiceOperationsTriggerProvider

Vous pouvez ajouter ou exposer un déclencheur ou une action Azure Functions en tant que déclencheur de fournisseur de services dans votre connecteur intégré personnalisé. Pour utiliser le type de déclencheur basé sur Azure Functions et la même liaison Azure Functions que le déclencheur de connecteur managé Azure, implémentez les méthodes suivantes pour fournir les informations de connexion et les liaisons de déclencheur requises par Azure Functions. Pour plus d’informations, consultez IServiceOperationsTriggerProvider.

  • La méthode GetFunctionTriggerType() est requise pour renvoyer la chaîne identique au paramètre de type dans la liaison de déclencheur Azure Functions.

  • La GetFunctionTriggerDefinition() a une implémentation par défaut. Vous n’avez donc pas besoin d’implémenter explicitement cette méthode. Toutefois, si vous souhaitez mettre à jour le comportement par défaut du déclencheur, par exemple fournir des paramètres supplémentaires que le concepteur n’expose pas, vous pouvez implémenter cette méthode et remplacer le comportement par défaut.

Méthodes à implémenter

Les sections suivantes décrivent les méthodes que l’exemple de connecteur implémente. Pour l'exemple complet, consultez Exemple CosmosDbServiceOperationProvider.cs.

GetService()

Le concepteur a besoin de la méthode suivante pour obtenir la description de haut niveau de votre service :

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

GetOperations()

Le concepteur nécessite la méthode suivante pour obtenir les opérations implémentées par votre service. Cette liste des opérations est basée sur le schéma Swagger.

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

GetBindingConnectionInformation()

Pour utiliser le type de déclencheur basé sur Azure Functions, la méthode suivante fournit les informations de paramètres de connexion requises pour la liaison de déclencheur Azure Functions.

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

InvokeOperation()

L'exemple de connecteur intégré personnalisé Azure Cosmos DB ne comporte pas d'actions, mais la méthode suivante est incluse par souci d'exhaustivité :

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

GetFunctionTriggerType()

Pour utiliser un déclencheur Azure Functions en tant que déclencheur dans votre connecteur, vous devez retourner la chaîne identique au paramètre type dans la liaison de déclencheur Azure Functions.

L’exemple suivant retourne la chaîne pour le déclencheur de base de données Azure Cosmos intégré et opérationnel, "type": "cosmosDBTrigger":

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

GetFunctionTriggerDefinition()

Cette méthode est implémentée par défaut. Vous n’avez donc pas besoin d’implémenter explicitement cette méthode. Toutefois, si vous souhaitez mettre à jour le comportement par défaut du déclencheur, par exemple fournir des paramètres supplémentaires que le concepteur n’expose pas, vous pouvez implémenter cette méthode et remplacer le comportement par défaut.

Inscrire le connecteur

Pour charger votre extension de connecteur intégrée personnalisée pendant le processus de démarrage du runtime Azure Functions, vous devez ajouter l'inscription de l'extension Azure Functions comme tâche de démarrage puis inscrire votre connecteur comme fournisseur de services dans la liste des fournisseurs de services. En fonction du type de données dont votre déclencheur intégré a besoin comme entrées, vous pouvez ajouter le convertisseur. Cet exemple convertit le type de données Document pour les documents Azure Cosmos DB en un tableau JObject.

Les sections suivantes montrent comment inscrire votre connecteur intégré personnalisé en tant qu'extension Azure Functions.

Créer le travail de démarrage

  1. Créez une classe de démarrage en utilisant l'attribut assembly nommé [assembly:WebJobsStartup].

  2. Implémentez l’interface IWebJobsStartup. Dans la méthode Configure(), inscrivez l'extension et injectez le fournisseur de services.

    Par exemple, l'extrait de code suivant montre l'implémentation de la classe de démarrage pour l'exemple de connecteur Azure Cosmos DB intégré personnalisé :

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

    Pour plus d'informations, consultez Services d'inscription - Utilisation de l'injection de dépendances dans .NET Azure Functions.

Inscrire le fournisseur de services

À présent, inscrivez l’implémentation du fournisseur de services en tant qu’extension Azure Functions avec le moteur Azure Logic Apps. Cet exemple utilise le déclencheur intégré Azure Cosmos DB pour Azure Functions comme nouveau déclencheur. Cet exemple inscrit également le nouveau fournisseur de services Azure Cosmos DB dans une liste existante de fournisseurs de services, qui fait déjà partie de l'extension Azure Logic Apps. Pour plus d’informations, consultez Inscrire des extensions de liaison 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);
      }
   }
}

Ajouter un convertisseur

Azure Logic Apps offre un moyen générique de gérer tout déclencheur intégré Azure Functions à l’aide du tableau JObject. Mais si vous souhaitez convertir la liste en lecture seule des documents Azure Cosmos DB en un tableau JObject, vous pouvez ajouter un convertisseur. Lorsque le convertisseur est prêt, inscrivez-le en tant que partie de ExtensionConfigContext, comme indiqué précédemment dans cet exemple :

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

Diagramme de la bibliothèque de classes pour les classes implémentées

Lorsque vous avez terminé, examinez le diagramme de classes suivant qui présente l'implémentation de toutes les classes du groupe d'extension Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll :

  • CosmosDbServiceOperationsProvider
  • CosmosDbServiceProvider
  • CosmosDbServiceProviderStartup

Diagramme de mappage de code conceptuel montrant l’implémentation complète de la classe.

Installer votre connecteur

Pour ajouter la référence NuGet de la section précédente, dans le pack d'extensions nommé Microsoft.Azure.Workflows.ServiceProvider.Extensions.CosmosDB.dll, mettez à jour le fichier extensions.json. Pour plus d'informations, rendez-vous sur le référentiel Azure/logicapps-connector-extensions et consultez le script PowerShell nommé add-extension.ps1.

  1. Mettez à jour le pack d'extensions pour inclure le connecteur intégré personnalisé.

  2. Dans Visual Studio Code, où l'extension Azure Logic Apps (Standard) pour Visual Studio Code devrait être installée, créez un projet d'application logique et installez le package d'extensions à l'aide de la commande PowerShell suivante :

    PowerShell

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

    Sinon, à partir du répertoire de votre projet d'application logique, en utilisant une invite PowerShell, exécutez le script PowerShell nommé add-extension.ps1 :

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

    Bash

    Pour utiliser Bash à la place, à partir du répertoire de votre projet d'application logique, exécutez le script PowerShell avec la commande suivante :

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

    Si l'extension pour votre connecteur intégré personnalisé a été installée avec succès, vous obtenez un résultat similaire à l'exemple suivant :

    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. Si un processus func.exe est en cours d'exécution, veillez à le fermer ou à le quitter avant de passer à l'étape suivante.

Tester votre connecteur

  1. Dans Visual Studio Code, ouvrez votre application logique standard et votre workflow vide dans le concepteur.

  2. Sur la surface du concepteur, sélectionnez Choisir une opération pour ouvrir le sélecteur d'opérations du connecteur.

  3. Dans la zone de recherche des opérations, sélectionnez Intégré. Dans la zone de recherche, entrez cosmos db.

    Le sélecteur d'opérations montre votre connecteur intégré personnalisé et le déclencheur, par exemple :

    Capture d’écran montrant Visual Studio Code et le concepteur d’un flux de travail d’application logique Standard avec le nouveau connecteur Azure Cosmos DB intégré personnalisé.

  4. Dans la liste Déclencheurs, sélectionnez votre déclencheur intégré personnalisé pour lancer votre workflow.

  5. Dans le volet de connexion, fournissez les valeurs de propriété suivantes pour créer une connexion, par exemple :

    Propriété Obligatoire Valeur Description
    Nom de connexion Oui <Azure-Cosmos-DB-connection-name> Le nom de la connexion Azure Cosmos DB à créer
    Chaîne de connexion Oui <Azure Cosmos DB-DB-connection-string> La chaîne de connexion pour la collection de bases de données Azure Cosmos DB ou la collection de location où vous voulez ajouter chaque nouveau document reçu.

    Capture d’écran montrant le volet de connexion lors de l’utilisation du connecteur pour la première fois.

  6. Sélectionnez Créer lorsque vous avez terminé.

  7. Dans le volet des propriétés du déclencheur, fournissez les valeurs de propriété suivantes pour votre déclencheur, par exemple :

    Propriété Obligatoire Valeur Description
    Nom de la base de données Oui <Azure-Cosmos-DB-database-name> Le nom de la base de données Azure Cosmos DB à utiliser
    Nom de la collection Oui <Azure-Cosmos-DB-collection-name> Le nom de la collection Azure Cosmos DB où vous voulez ajouter chaque nouveau document reçu.

    Capture d’écran montrant le volet Propriétés du déclencheur.

    Pour cet exemple, en mode Code, la définition du workflow, qui se trouve dans le fichier workflow.json, contient un objet JSON triggers similaire à l'exemple suivant :

    {
   "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 définition de la connexion, qui se trouve dans le fichier connections.json, possède un objet JSON serviceProviderConnections similaire à l'exemple suivant :

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

  8. Dans Visual Studio Code, sélectionnez Commencer le débogage dans le menu Exécuter. (Appuyez sur F5)

  9. Pour déclencher votre workflow, dans le portail Azure, ouvrez votre compte Azure Cosmos DB. Dans le menu du compte, sélectionnez Data Explorer. Accédez à la base de données et à la collection que vous avez spécifiées dans le déclencheur. Ajoutez un élément à la collection.

    Capture d’écran montrant les Portail Azure, le compte Azure Cosmos DB et Data Explorer ouverts à la base de données et à la collection spécifiées.

Étapes suivantes