Vue d’ensemble du déclencheur et des liaisons Azure Cosmos DB pour Azure Functions

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

Action	Catégorie
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

Important

Cette version de l’extension de liaison Azure Cosmos DB prend en charge Azure Functions version 4.x. Si votre application utilise toujours la version 1.x du runtime Functions, consultez plutôt les liaisons Azure Cosmos DB pour Azure Functions 1.x. Dans le runtime Functions v1.x, cette liaison a été initialement nommée DocumentDB.

API prises en charge

Ce tableau indique comment se connecter aux différentes API Azure Cosmos DB à partir de votre code de fonction :

API	Recommandation
Azure Cosmos DB pour NoSQL	Utiliser l’extension de liaison Azure Cosmos DB
Azure Cosmos DB pour MongoDB	Utilisez un Kit de développement logiciel (SDK) client natif.
Azure Cosmos DB pour table	Utilisez la version 5.x ou ultérieure de l’extension de liaison Tables Azure.
Azure Cosmos DB pour Apache Cassandra	Utilisez un Kit de développement logiciel (SDK) client natif.
Azure Cosmos DB pour Apache Gremlin (API Graph)	Utiliser un Kit de développement logiciel (SDK) client natif
Azure Cosmos DB pour PostgreSQL	Utilisez un Kit de développement logiciel (SDK) client natif.

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 :

Modèle de worker isolé

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é.

Modèle in-process

Important

La prise en charge du modèle in-process prendra fin le 10 novembre 2026. Pour continuer à bénéficier d’une prise en charge complète, nous vous recommandons vivement de migrer vos applications vers le modèle worker isolé.

Les fonctions s’exécutent dans le même processus que l’hôte Functions. Pour en découvrir plus, consultez Développer des fonctions de bibliothèque de classes C# à l’aide d’Azure Functions.

Dans une variation de ce modèle, Functions peut être exécuté à l’aide de scripts C#, principalement pris en charge pour la modification du portail C#. Pour mettre à jour les extensions de liaison existantes pour les applications de script C# exécutées dans le portail sans avoir à republier votre application de fonction, consultez Mettre à jour vos extensions.

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

Version 4.x et ultérieures de l’extension

Cette section décrit l’utilisation d’une bibliothèque de classes. Pour les scripts C#, vous devez installer la version 4.x du bundle d’extensions à la place.

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é.

Elle change également les types avec lesquels vous pouvez établir une liaison, en remplaçant les types du Kit de développement logiciel (SDK) v2 Microsoft.Azure.DocumentDB par des types plus récents du Kit de développement logiciel (SDK) v3 Microsoft.Azure.Cosmos. En savoir plus sur la façon dont ces nouveaux types sont différents et sur la manière de les migrer à partir du Guide de migration SDK, du déclencheur, de la liaison d’entréeet des exemples de liaison de sortie .

Cette version de l’extension est disponible sous la forme d’un package NuGet version 4.x.

Functions 2.x et versions ultérieures

Cette section décrit l’utilisation d’une bibliothèque de classes. Pour les scripts C#, vous devez installer la version 2.x ou 3.x du bundle d’extensions à la place.

Pour utiliser le déclencheur et les liaisons, vous devez référencer le package NuGet approprié. Installez le package NuGet, version 3.x.

Version 4.x et ultérieures 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

Functions 2.x et versions ultérieures

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

Installer le bundle

Pour pouvoir utiliser cette extension de liaison dans votre application, assurez-vous que le fichier host.json à la racine de votre projet contient cette extensionBundle référence :

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

Dans cet exemple, la version valeur de [4.0.0, 5.0.0) l’hôte Functions indique à l’hôte Functions d’utiliser une version groupée qui est au moins 4.0.0 mais inférieure à , qui inclut toutes les versions potentielles 5.0.0de 4.x. Cette notation gère efficacement votre application sur la dernière version mineure disponible de l’offre groupée d’extensions v4.x.

Si possible, vous devez utiliser la dernière version principale de l’offre groupée d’extensions et autoriser le runtime à gérer automatiquement la dernière version mineure. Vous pouvez afficher le contenu de la dernière offre groupée sur la page de publication des offres groupées d’extensions. Pour plus d’informations, consultez les bundles d’extensions Azure Functions.

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.

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 :

Modèle de worker isolé

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.

Modèle in-process

Une bibliothèque de classes in-process est une fonction C# compilée exécutée dans le même processus que le runtime Functions.

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

Version 4.x et ultérieures de l’extension

L’extension Azure Cosmos DB prend en charge les types de paramètres en fonction du tableau ci-dessous.

Scénario de liaison	Types de paramètres
Déclencheur Cosmos DB (document unique)	Types sérialisables JSON1
Déclencheur Cosmos DB (lot de documents)	IEnumerable<T>where T est un type sérialisable JSON1
Entrée Cosmos DB (document unique)	Types sérialisables JSON1
Entrée Cosmos DB (requête retournant plusieurs documents)	CosmosClient IEnumerable<T> where T est un type sérialisable JSON1
Sortie Cosmos DB (document unique)	Types sérialisables JSON1
Sortie Cosmos DB (plusieurs documents)	ICollector<T> ou IAsyncCollector<T> where T est un type sérialisable JSON1

Les documents ¹ contenant des données JSON peuvent être désérialisés dans des types d’objets CLR (POCO) connus.

Functions 2.x et versions ultérieures

Les versions antérieures de l’extension exposaient des types de l’espace de noms Microsoft.Azure.Documents désormais dépréciés. Les types plus récents de Microsoft.Azure.Cosmos sont exclusifs à l’extension 4.x et aux versions ultérieures.

Version 4.x et ultérieures de l’extension

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 :

Catégorie	Descriptif
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 :

Catégorie	Descriptif
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 :

Catégorie	Descriptif
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 :

Catégorie	Descriptif
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.
Base de données1	Client connecté à la base de données Cosmos DB.
Conteneur1	Client connecté au conteneur Cosmos DB.

¹ 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 :

Catégorie	Descriptif
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 :

Catégorie	Descriptif
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.

Functions 2.x et versions ultérieures

Les versions antérieures des extensions dans le processus Worker isolé prennent uniquement en charge la liaison à des types JSON sérialisables. Des options supplémentaires sont disponibles pour l’extension 4.x et les versions ultérieures.

Types de liaisons sdk

La prise en charge des types de SDK pour Azure Cosmos est en préversion. Suivez l’exemple de liaisons du SDK Python pour CosmosDB pour bien démarrer avec les types de SDK pour Cosmos dans Python.

Important

L’utilisation de liaisons de type SDK nécessite le modèle de programmation Python v2.

---

Liaison	Types de paramètres	Échantillons
Entrée CosmosDB	ContainerProxy, CosmosClient, DatabaseProxy	ContainerProxy, CosmosClient, DatabaseProxy

---

Exceptions et codes de retour

Liaison	Informations de référence
Base de données 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 la version 2.x et les versions ultérieures. Les paramètres dans le fichier host.json s’appliquent à toutes les fonctions dans une instance de l’application de fonction. Pour plus d’informations sur les paramètres de configuration des applications de fonction, consultez host.json référence pour Azure Functions.

Version 4.x et ultérieures de l’extension

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

Propriété	Par défaut	Descriptif
connectionMode	Gateway	Le mode de connexion utilisé par la fonction lors de la connexion au service Azure Cosmos DB. Options : Direct se connecte directement aux réplicas principaux via TCP et peut fournir une latence inférieure et Gateway acheminer les requêtes via une passerelle frontale via HTTPS. Pour plus d’informations, consultez les modes de connexion du Kit de développement logiciel (SDK) Azure Cosmos DB.
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.

Functions 2.x et versions ultérieures

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

Propriété	Par défaut	Descriptif
connectionMode	Gateway	Le mode de connexion utilisé par la fonction lors de la connexion au service Azure Cosmos DB. Options : Direct se connecte directement aux réplicas principaux via TCP et peut fournir une latence inférieure et Gateway acheminer les requêtes via une passerelle frontale via HTTPS. Pour plus d’informations, consultez les modes de connexion du Kit de développement logiciel (SDK) Azure Cosmos DB.
protocole	Https	Le protocole de connexion utilisé par la fonction lors de la connexion au service Azure Cosmos DB. Lisez ceci pour obtenir des explications sur les deux modes.
leasePrefix	n/a	Préfixe de bail à utiliser dans toutes les fonctions d’une application.

Étapes suivantes

• 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)