Présentation de l’extension Connector pour Azure Functions (Aperçu)

L’extension Connector fournit la liaison de déclenchement entrante qui exécute une fonction lorsqu’un événement se produit dans un service connecté via un connecteur géré. Pour appeler des opérations et effectuer des actions dans ces services connectés depuis votre code de fonction, utilisez un SDK Azure Connectors, actuellement disponible pour .NET, Node.jset Python. Pour plus d’informations sur les déclencheurs, les actions du SDK et le moment d’utiliser les connecteurs gérés, voir Utiliser les connecteurs gérés dans Azure Functions.

Fonctionnement de l’extension

Une fonction déclenchée par un connecteur utilise ces composantes :

Lorsqu’un événement configuré se produit, l’espace de noms Connector envoie l’événement vers le point de terminaison webhook de l’extension. L’extension utilise la functionName valeur de la chaîne de requête pour sélectionner la fonction et transmet le corps de l’événement JSON au paramètre de déclenchement. L’hôte Fonctions valide la clé système avant que l’extension ne traite la requête, sauf si vous configurez une autre couche d’authentification comme décrit dans les rappels d’authentifique.

Dans une fonction worker isolée .NET, appliquez [ConnectorTrigger] au paramètre qui reçoit le corps de l’événement.

Installer l’extension

Le déclencheur Connector prend en charge le modèle de travailleur isolé .NET. Pour des informations sur les versions prises en charge de .NET dans les versions d’exécution d’Azure Functions, voir Langages par version d’exécution.

Ajoutez le package d’extension Preview Connector à votre projet :

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector --prerelease

Pour utiliser des modèles de charges utiles fortement typées ou appeler des opérations de connecteurs gérés, ajoutez également le SDK Azure Connectors preview :

dotnet add package Azure.Connectors.Sdk --prerelease

Pour les versions actuelles des paquets et les projets complets, voir les exemples de connecteurs Azure Functions pour .NET.

Installer l’extension

Installez les paquets utilisés par le déclencheur Connector :

npm install @azure/functions @azure/functions-extensions-connectors @azure/connectors

Ces packages offrent les fonctionnalités suivantes :

• @azure/functions fournit l’enregistrement de base connectorTrigger , qui reçoit l’entrée de déclenchement sous forme de type générique par unknowndéfaut .
• @azure/functions-extensions-connectors enveloppe l’entrée dans un contexte de déclenchement de connecteur normalisé et fournit des contextes typés pour les opérations de connecteur prises en charge.
• @azure/connectors, le SDK preview Azure Connectors pour Node.js, fournit les modèles de charge utile utilisés par ces contextes et clients pour appeler les opérations de connecteur.

Configurez votre application pour utiliser la version 4.42.0 ou ultérieure du pack d’extension preview dans le fichierhost.json :

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Pour les versions actuelles des paquets et les projets complets, voir les exemples de connecteurs Azure Functions pour TypeScript.

Installer l’extension

Utilisez le modèle de programmation Python v2 et installez les paquets requis par le déclencheur Connector :

azure-functions>=2.2.0
azurefunctions-extensions-connectors

La bibliothèque Python de base Azure-functions peut lier la charge utile de déclenchement à str, dict, ou bytes. Le package azurefunctions-extensions-connectors intègre le SDK Azure Connectors pour Python et enregistre des convertisseurs supplémentaires pour les annotations SDK spécifiques à l’opération qu’il supporte.

Configurez votre application pour utiliser la version 4.42.0 ou ultérieure du pack d’extension preview dans le fichierhost.json :

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Pour les versions actuelles des paquets et les projets complets, voir les exemples de connecteurs Azure Functions pour Python.

Types de liaisons

Le déclencheur Connector prend en charge ces types de paramètres pour les fonctions de travail isolées .NET :

Pour des exemples de code et le comportement de la charge utile spécifique à l’opération, voir la référence de déclenchement Connector.

Pour déterminer quelles opérations de connecteur ont des modèles de payload .NET fortement typés, voir Operations to Azure Functions signature mapping.

Types de liaisons

L’enregistrement de base connectorTrigger transmet l’entrée déclencheuse à un type de gestionnaire générique qui est par défaut .unknown Le @azure/functions-extensions-connectors package analyse l’entrée brute en a ConnectorTriggerContext<T> avec les propriétés normalisées payload et items de , les contextes typés originaux rawPayloadet spécifiques à l’opération lorsque disponibles. Pour les opérations sans enregistrement typé, utilisez le contexte générique et validez la unknown charge utile avant d’accéder à son contenu.

Pour déterminer quelles opérations de connecteur ont fortement typé des modèles de charge utile TypeScript, voir Operations to Azure Functions signature mapping.

Types de liaisons

Le déclencheur Connector prend en charge ces types de paramètres Python :

Pour déterminer quelles opérations de connecteur possèdent un convertisseur Python typé enregistré et si l’annotation représente un élément ou une collection, voir Operations to Azure Functions signature mapping. Utilisez str, dict, ou bytes pour des opérations qui n’ont pas d’annotation SDK prise en charge.

Configurer les ressources du connecteur

Avant que l’extension ne puisse recevoir un événement, créez ces ressources et configurations :

1. Un espace de noms de connecteurs.
2. Une connexion de connecteur gérée autorisée à accéder au service externe.
3. Une configuration de déclencheur qui sélectionne l’événement du connecteur et identifie la fonction de destination.

La configuration du déclencheur inclut la connexion du connecteur gérée, le nom de l’opération, les paramètres d’opération, l’URL de rappel et l’authentification du rappel. Pour les valeurs de configuration et les instructions de création d’un déclencheur en utilisant Azure CLI ou le portail Connector Namespace, voir Configurer le déclencheur.

Authentifier les rappels

Par défaut, l’extension Connector crée une clé système de fonction appli nommée connector_extension. Récupérez la clé en exécutant :

az functionapp keys list \
    --resource-group <RESOURCE_GROUP> \
    --name <FUNCTION_APP_NAME> \
    --query "systemKeys.connector_extension" \
    --output tsv

Configurez l’URL de rappel sans la clé :

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

Stockez la clé séparément dans notificationDetails.authentication:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

Au moment du rappel, l’espace de noms Connector ajoute la clé comme code paramètre de la chaîne de requête. Garder la clé séparée de l’URL de rappel enregistrée permet au portail de la masquer comme un secret.

Pour les déploiements nécessitant une authentification en retour de rappel basée sur l’identité, utilisez l’authentification intégrée App Service avec une identité gérée au lieu d’une clé système partagée. Pour le schéma complet, voir Authentifier vos fonctions dans un espace de noms de connecteur.

Paramètres host.json

L’authentification par clé système par défaut ne nécessite pas de réglages spécifiques au connecteur dans le fichierhost.json .

Lorsque l’authentification intégrée App Service valide les rappels depuis l’espace de noms du connecteur, vous pouvez désactiver la vérification redondante de la clé système :

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

À utiliser Anonymous uniquement lorsqu’une autre couche d’authentification, telle que l’authentification intégrée des services applicatifs, valide les requêtes avant qu’elles n’atteignent l’hôte des Fonctions.

Pour une implémentation complète de cette configuration d’application indépendante du langage, voir l’exemple d’authentification intégrée.

Étapes suivantes

• Managed connector trigger for Azure Function
• Utilisez des connecteurs gérés dans Azure Functions
• Exemples de connecteurs Azure Functions
• Qu’est-ce que l’espace de noms connecteur Azure ?
• Référence des connecteurs