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

• Version 1
• Versions 2 et ultérieures

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 :

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.

Extension 4.x et versions ultérieures

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

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.

Offre groupée v4.x

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.

Bundle v2.x et v3.x

Vous pouvez installer cette version de l’extension dans votre application de fonction en inscrivant l’offre groupée d’extension, version 2.x ou 3.x.

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

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.

Extension 4.x et versions ultérieures

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.

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

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.

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 4.x et ultérieures de l’extension

{
    "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.

Functions 2.x et versions ultérieures

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

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.
protocol	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)