Présentation du déclencheur et des liaisons Azure Cosmos DB pour Azure Functions versions 2.x et ultérieures

  • Article

Cet ensemble d’articles explique comment utiliser des liaisons Azure Cosmos DB dans Azure Functions versions 2.x et ultérieures. Azure Functions prend en charge les liaisons de déclencheur, d’entrée et de sortie pour Azure Cosmos DB.

Action Type
Exécuter une fonction lors de la création ou de la modification d’un document Azure Cosmos DB Déclencheur
Lire un document Azure Cosmos DB Liaison d’entrée
Enregistrer les modifications apportées à un document Azure Cosmos DB Liaison de sortie

Notes

Cette référence concerne Azure Functions versions 2.x et ultérieures. Pour plus d’informations sur l’utilisation de ces liaisons dans Functions 1.x, consultez Liaisons Azure Cosmos DB pour Azure Functions 1.x.

Cette liaison était nommée à l’origine DocumentDB. Dans Azure Functions version 2.x, le déclencheur, les liaisons et le package sont tous nommés Azure Cosmos DB.

API prises en charge

Les liaisons Azure Cosmos DB sont prises en charge uniquement pour une utilisation avec Azure Cosmos DB pour NoSQL. La prise en charge de l’API Table est fournie à l’aide des liaisons de stockage Table à partir de l’extension 5.x. Pour toutes les autres API Azure Cosmos DB, vous devez accéder à la base de données à partir de votre fonction en utilisant le client statique pour votre API, à savoir Azure Cosmos DB for MongoDB, Azure Cosmos DB for Cassandra et Azure Cosmos DB for Apache Gremlin.

Installer l’extension

Le package NuGet de l’extension que vous installez dépend du mode C# que vous utilisez dans votre application de fonction :

Les fonctions s’exécutent dans un processus de travail C# isolé. Pour en savoir plus, consultez Guide pour l’exécution d’Azure Functions C# dans un processus Worker isolé.

Le processus d’installation de l’extension varie en fonction de la version de l’extension :

Cette version de l’extension des liaisons Azure Cosmos DB introduit la possibilité de se connecter à l’aide d’une identité au lieu d’un secret. Pour obtenir un tutoriel sur la configuration de vos applications de fonction avec des identités managées, consultez le tutoriel sur la création d’une application de fonction avec des connexions basées sur l’identité.

Ajoutez l’extension à votre projet en installant le package NuGet, version 4.x.

Si vous écrivez votre application en tirant parti de F#, vous devez également configurer cette extension dans le cadre de la configuration de démarrage de l’application. Dans l’appel à ConfigureFunctionsWorkerDefaults() ou ConfigureFunctionsWebApplication(), ajoutez un délégué prenant un paramètre IFunctionsWorkerApplication. Ensuite, dans le corps de ce délégué, appelez ConfigureCosmosDBExtension() sur l’objet :

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

Installer le bundle

L’extension des liaisons Azure Cosmos DB fait partie d’un bundle d’extension, qui est spécifié dans votre fichier projet host.json. Vous devrez peut-être modifier cette offre groupée pour modifier la version de la liaison ou si les offres groupées ne sont pas encore installées. Pour plus d’informations, consultez le bundle d’extensions.

En raison de modifications de schéma dans le kit de développement logiciel (SDK) Azure Cosmos DB, la version 4.x de l’extension Azure Cosmos DB requiert azure-functions-java-library V3.0.0 pour les fonctions Java.

Cette version de l’offre groupée contient la version 4.x de l’extension des liaisons Azure Cosmos DB qui introduit la possibilité de se connecter à l’aide d’une identité au lieu d’un secret. Pour obtenir un tutoriel sur la configuration de vos applications de fonction avec des identités managées, consultez le tutoriel sur la création d’une application de fonction avec des connexions basées sur l’identité.

Vous pouvez ajouter cette version de l’extension à partir de la préversion de l’offre groupée d’extension v4 en ajoutant ou en remplaçant le code suivant dans votre fichier host.json :

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

Pour en savoir plus, consultez Mettre à jour vos extensions.

Types de liaisons

Les types de liaisons pris en charge pour .NET dépendent à la fois de la version de l’extension et du mode d’exécution C#, qui peut être l’un des suivants :

Une bibliothèque de classes de processus Worker isolé est une fonction C# compilée exécutée dans un processus Worker isolé du runtime.

Choisissez une version pour afficher les détails des types de liaison du mode et de la version.

Le processus Worker isolé prend en charge les types de paramètres en fonction des tableaux ci-dessous. La prise en charge des liaisons vers des types depuis Microsoft.Azure.Cosmos est en préversion.

Déclencheur Cosmos DB

Quand vous souhaitez que la fonction traite un seul document, le déclencheur Cosmos DB peut se lier aux types suivants :

Type Description
Types sérialisables JSON Functions tente de désérialiser les données JSON du document à partir du flux de modification Cosmos DB dans un type d’objet CLR traditionnel (OCT).

Quand vous souhaitez que la fonction traite un lot de documents, le déclencheur Cosmos DB peut se lier aux types suivants :

Type Description
IEnumerable<T>where T est un type sérialisable JSON Énumération des entités incluses dans le lot. Chaque entrée représente un document du flux de modification Cosmos DB.

Liaison d’entrée Azure Cosmos DB

Lorsque vous souhaitez que la fonction traite un seul document, la liaison d’entrée Cosmos DB peut se lier aux types suivants :

Type Description
Types sérialisables JSON Functions tente de désérialiser les données JSON du document dans un type d’objet CLR traditionnel (OCT).

Lorsque vous souhaitez que la fonction traite plusieurs documents d’une requête, la liaison d’entrée Cosmos DB peut se lier aux types suivants :

Type Description
IEnumerable<T>where T est un type sérialisable JSON Énumération des entités renvoyées par la requête. Chaque entrée représente un document.
CosmosClient1 Client connecté au compte Cosmos DB.
Database1 Client connecté à la base de données Cosmos DB.
Container1 Client connecté au conteneur Cosmos DB.

1 Pour utiliser ces types, vous devez référencer Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 ou version ultérieure et les dépendances communes pour les liaisons de type SDK.

Liaison de sortie Azure Cosmos DB

Lorsque vous souhaitez que la fonction écrive dans un seul document, la liaison de sortie Cosmos DB peut se lier aux types suivants :

Type Description
Types sérialisables JSON Objet représentant le contenu JSON d'un document. Functions tente de sérialiser un type d'objet CLR traditionnel (OCT) en données JSON.

Lorsque vous souhaitez que la fonction écrive dans plusieurs documents, la liaison de sortie Cosmos DB peut se lier aux types suivants :

Type Description
T[] where Test un type sérialisable JSON Tableau contenant plusieurs documents. Chaque entrée représente un document.

Pour d’autres scénarios de sortie, créez et utilisez un CosmosClient avec d’autres types de Microsoft.Azure.Cosmos directement. Consultez Inscrire des clients Azure pour obtenir un exemple d’utilisation de l’injection de dépendances pour créer un type de client à partir du Kit de développement logiciel (SDK) Azure.

Exceptions et codes de retour

Liaison Informations de référence
Azure Cosmos DB Codes d’état HTTP pour Azure Cosmos DB

Paramètres host.json

Cette section décrit les paramètres de configuration disponibles pour cette liaison dans les versions 2.x et ultérieures. Les paramètres dans le fichier host.json s’appliquent à toutes les fonctions dans une instance de l’application de fonction. L’exemple de fichier host.json ci-dessous contient seulement les paramètres des versions 2.x et ultérieures pour cette liaison. Pour plus d’informations sur les paramètres de configuration de l’application de fonction dans les versions 2.x et ultérieures, consultez Référence host.json pour Azure Functions.

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
Propriété Default Description
connectionMode Gateway Le mode de connexion utilisé par la fonction lors de la connexion au service Azure Cosmos DB. Les options sont Direct et Gateway.
userAgentSuffix n/a Ajoute la valeur de chaîne spécifiée à toutes les demandes effectuées par le déclencheur ou la liaison au service. Cela facilite le suivi de l’activité dans Azure Monitor, en fonction d’une application de fonction spécifique et du filtrage par User Agent.

Étapes suivantes