Déclencheur Azure Cosmos DB pour Azure Functions 2.x et supérieur

Le déclencheur Azure Cosmos DB utilise le flux de modification Azure Cosmos DB pour écouter les insertions et mises à jour sur plusieurs partitions. Le flux de modification publie des éléments nouveaux et mis à jour, sans compter les mises à jour découlant de suppressions.

Pour plus d’informations sur les détails d’installation et de configuration, consultez la vue d’ensemble.

Les décisions de mise à l’échelle de Cosmos DB pour les plans Consommation et Premium sont effectuées au moyen de la mise à l’échelle basée sur la cible. Pour plus d’informations, consultez Mise à l’échelle basée sur la cible.

Important

Cet article utilise des onglets pour prendre en charge plusieurs versions du modèle de programmation Node.js. Le modèle v4 est en disponibilité générale. Il est conçu pour offrir une expérience plus flexible et intuitive aux développeurs JavaScript et TypeScript. Pour plus d’informations sur le fonctionnement du modèle v4, reportez-vous au guide du développeur Azure Functions Node.js. Pour plus d’informations sur les différences entre v3 et v4, consultez le guide de migration.

Azure Functions prend en charge deux modèles de programmation pour Python. La façon dont vous définissez vos liaisons dépend du modèle de programmation choisi.

Le modèle de programmation Python v2 vous permet de définir des liaisons à l'aide d’éléments décoratifs directement dans le code de votre fonction Python. Pour plus d’informations, consultez le guide des développeurs Python.

Cet article prend en compte les deux modèles de programmation.

Exemple

L’utilisation du déclencheur dépend de la version du package d’extension et de la modalité C# utilisée dans votre application de fonction, qui peut être l’une des suivantes :

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.

Les exemples suivants dépendent de la version d’extension pour le mode C# donné.

Cet exemple fait référence à un type simple ToDoItem :

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

La fonction suivante est appelée quand des insertions ou des mises à jour figurent dans la base de données et la collection spécifiées.

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

Cette fonction est appelée lorsqu’il existe des insertions ou des mises à jour dans la base de données et le conteneur spécifiés.

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.

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

Dans la bibliothèque du runtime des fonctions Java, utilisez l’annotation @CosmosDBTrigger sur les paramètres dont la valeur proviendrait d’Azure Cosmos DB. Vous pouvez utiliser cette annotation avec des types Java natifs, des objets POJO ou des valeurs Null à l’aide de Optional<T>.

L’exemple suivant montre une fonction TypeScript de déclencheur Azure Cosmos DB. La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont ajoutés ou modifiés.

import { app, InvocationContext } from '@azure/functions';

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

L’exemple suivant montre une fonction JavaScript de déclencheur Azure Cosmos DB. La fonction écrit des messages de journal quand des enregistrements Azure Cosmos DB sont ajoutés ou modifiés.

const { app } = require('@azure/functions');

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

L’exemple suivant montre comment exécuter une fonction lorsque des données sont modifiées dans Azure Cosmos DB.

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

Notez que certains noms d’attributs de liaison ont été modifiés dans la version 4.x de l’extension Azure Cosmos DB.

Dans le fichier run.ps1, vous avez accès au document qui déclenche la fonction avec le paramètre $Documents.

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

L’exemple suivant montre une liaison de déclencheur Azure Cosmos DB. L’exemple varie selon l’utilisation du modèle de programmation Python v1 ou v2.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

Attributs

Les bibliothèques C# in-process et de processus isolés utilisent l’attribut CosmosDBTriggerAttribute pour définir la fonction. Le script C# utilise à la place un fichier de configuration function.json comme décrit dans le guide de script C#.

Propriété d’attribut Description
Connection Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui est surveillé. Pour plus d’informations, consultez Connexions.
DatabaseName Nom de la base de données Azure Cosmos DB contenant le conteneur analysé.
ContainerName Nom du conteneur surveillé.
LeaseConnection (Facultatif) Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui détient le conteneur de baux.

S’il n’est pas défini, la valeur Connection est utilisée. Ce paramètre est automatiquement défini lorsque la liaison est créée dans le portail. La chaîne de connexion du conteneur de baux doit avoir des autorisations en écriture.
LeaseDatabaseName (Facultatif) Nom de la base de données contenant le conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur du paramètre databaseName est utilisée.
LeaseContainerName (Facultatif) Nom du conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur leases est utilisée.
CreateLeaseContainerIfNotExists (Facultatif) Lorsque la valeur est définie sur true, le conteneur de baux est créé automatiquement s’il n’existe pas. La valeur par défaut est false. Lorsque vous utilisez des identités Microsoft Entra, si vous définissez la valeur sur true, la création de conteneurs n’est pas une opération autorisée et votre fonction ne pourra pas démarrer.
LeasesContainerThroughput (Facultatif) Définit le nombre d’unités de requête à attribuer lors de la création du conteneur de baux. Ce paramètre est utilisé uniquement quand CreateLeaseContainerIfNotExists est défini sur true. Ce paramètre est automatiquement défini lors de la création de la liaison à l’aide du portail.
LeaseContainerPrefix (Facultatif) Lorsque cette valeur est définie, elle est ajoutée en tant que préfixe aux baux créés dans le conteneur de baux pour cette fonction. L’utilisation d’un préfixe permet à deux fonctions Azure distinctes de partager le même conteneur de baux grâce à des préfixes différents.
FeedPollDelay (Facultatif) Durée (en millisecondes) du délai s’écoulant entre le moment où toutes les modifications d’une partition sont purgées du flux et le moment où la partition est interrogée afin d’identifier de nouvelles modifications. La valeur par défaut est 5 000 millisecondes, soit 5 secondes.
LeaseAcquireInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle pour déclencher une tâche afin de calculer si les partitions sont réparties uniformément parmi les instances d’hôte connues. La valeur par défaut est 13 000 (13 secondes).
LeaseExpirationInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle selon lequel le bail est pris sur un bail représentant une partition. Si le bail n’est pas renouvelé dans cet intervalle, il expire et une autre instance devient propriétaire de la partition. La valeur par défaut est 60 000 (60 secondes).
LeaseRenewInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle de renouvellement de tous les baux pour les partitions actuellement détenues par une instance. La valeur par défaut est 17 000 (17 secondes).
MaxItemsPerInvocation (Facultatif) Quand cette propriété est définie, elle détermine le nombrer maximal d’éléments reçus par appel de fonction. Si des opérations du conteneur analysé sont effectuées par le biais de procédures stockées, l’étendue de transaction est préservée lors de la lecture des éléments à partir du flux de modification. Par conséquent, le nombre d’éléments reçus pourrait être supérieur à la valeur spécifiée de sorte que les éléments modifiés par la même transaction soient retournés dans le cadre d’un même lot atomique.
StartFromBeginning (Facultatif) Cette option indique au déclencheur de lire les modifications depuis le début de l’historique de modifications du conteneur au lieu de commencer à l’heure actuelle. La lecture depuis le début fonctionne uniquement au premier démarrage du déclencheur, car, lors des exécutions suivantes, les points de contrôle sont déjà stockés. La définition de cette option sur true quand des baux ont déjà été créés est sans effet.
StartFromTime (Facultatif) Obtient ou définit la date et l’heure à partir desquelles l’opération de lecture du flux de modification doit être initialisée. Le format recommandé est ISO 8601 avec le désignateur UTC, par exemple 2021-02-16T14:19:29Z. Utilisé uniquement pour définir l’état initial du déclencheur. Une fois que le déclencheur a un état de bail, la modification de cette valeur n’a aucun effet.
PreferredLocations (Facultatif) Définit les endroits par défaut (régions) des comptes de base de données géorépliqués dans le service Azure Cosmos DB. Les valeurs doivent être séparées par des virgules. Par exemple, « USA Est, USA Centre Sud, Europe Nord ».

Décorateurs

S’applique uniquement au modèle de programmation Python v2.

Pour les fonctions Python v2 définies à l’aide d’un élément décoratif, les propriétés suivantes sur cosmos_db_trigger :

Propriété Description
arg_name Nom de variable utilisé dans le code de fonction, qui représente la liste des documents modifiés.
database_name Nom de la base de données Azure Cosmos DB contenant la collection surveillée.
collection_name Le nom de la collection Azure Cosmos DB est surveillé.
connection Chaîne de connexion d’Azure Cosmos DB surveillée.

Pour les fonctions Python définies à l’aide de function.json, consultez la section Configuration.

Annotations

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.

Utilisez l’annotation @CosmosDBTrigger sur les paramètres qui lisent les données d’Azure Cosmos DB. L’annotation prend en charge les propriétés suivantes :

Propriété d’attribut Description
connection Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui est surveillé. Pour plus d’informations, consultez Connexions.
nom Nom de la fonction.
databaseName Nom de la base de données Azure Cosmos DB contenant le conteneur analysé.
containerName Nom du conteneur surveillé.
leaseConnectionStringSetting (Facultatif) Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui détient le conteneur de baux.

S’il n’est pas défini, la valeur Connection est utilisée. Ce paramètre est automatiquement défini lorsque la liaison est créée dans le portail. La chaîne de connexion du conteneur de baux doit avoir des autorisations en écriture.
leaseDatabaseName (Facultatif) Nom de la base de données contenant le conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur du paramètre databaseName est utilisée.
leaseContainerName (Facultatif) Nom du conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur leases est utilisée.
createLeaseContainerIfNotExists (Facultatif) Lorsque la valeur est définie sur true, le conteneur de baux est créé automatiquement s’il n’existe pas. La valeur par défaut est false. Lorsque vous utilisez des identités Microsoft Entra si vous définissez la valeur true, la création de conteneurs n’est pas autorisée et votre fonction ne démarre pas.
leasesContainerThroughput (Facultatif) Définit le nombre d’unités de requête à attribuer lors de la création du conteneur de baux. Ce paramètre est utilisé uniquement quand CreateLeaseContainerIfNotExists est défini sur true. Ce paramètre est automatiquement défini lors de la création de la liaison à l’aide du portail.
leaseContainerPrefix (Facultatif) Lorsque cette valeur est définie, elle est ajoutée en tant que préfixe aux baux créés dans le conteneur de baux pour cette fonction. L’utilisation d’un préfixe permet à deux fonctions Azure distinctes de partager le même conteneur de baux grâce à des préfixes différents.
feedPollDelay (Facultatif) Durée (en millisecondes) du délai s’écoulant entre le moment où toutes les modifications d’une partition sont purgées du flux et le moment où la partition est interrogée afin d’identifier de nouvelles modifications. La valeur par défaut est 5 000 millisecondes, soit 5 secondes.
leaseAcquireInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle pour déclencher une tâche afin de calculer si les partitions sont réparties uniformément parmi les instances d’hôte connues. La valeur par défaut est 13 000 (13 secondes).
leaseExpirationInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle selon lequel le bail est pris sur un bail représentant une partition. Si le bail n’est pas renouvelé dans cet intervalle, il expire et la propriété de la partition passe à une autre instance. La valeur par défaut est 60 000 (60 secondes).
leaseRenewInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle de renouvellement de tous les baux pour les partitions actuellement détenues par une instance. La valeur par défaut est 17 000 (17 secondes).
maxItemsPerInvocation (Facultatif) Quand cette propriété est définie, elle détermine le nombrer maximal d’éléments reçus par appel de fonction. Si des opérations du conteneur analysé sont effectuées par le biais de procédures stockées, l’étendue de transaction est préservée lors de la lecture des éléments à partir du flux de modification. Par conséquent, le nombre d’éléments reçus pourrait être supérieur à la valeur spécifiée de sorte que les éléments modifiés par la même transaction soient retournés dans le cadre d’un même lot atomique.
startFromBeginning (Facultatif) Cette option indique au déclencheur de lire les modifications depuis le début de l’historique de modifications du conteneur au lieu de commencer à l’heure actuelle. La lecture depuis le début fonctionne uniquement au premier démarrage du déclencheur, car, lors des exécutions suivantes, les points de contrôle sont déjà stockés. La définition de cette option sur true quand des baux ont déjà été créés est sans effet.
preferredLocations (Facultatif) Définit les endroits par défaut (régions) des comptes de base de données géorépliqués dans le service Azure Cosmos DB. Les valeurs doivent être séparées par des virgules. Par exemple, « USA Est, USA Centre Sud, Europe Nord ».

Configuration

S’applique uniquement au modèle de programmation Python v1.

Le tableau suivant explique les propriétés que vous pouvez définir pour l’objet options passé à la méthode app.cosmosDB(). Les propriétés type, direction et name ne s’appliquent pas au modèle v4.

Le tableau suivant décrit les propriétés de configuration de la liaison que vous définissez dans le fichier function.json, où les propriétés diffèrent selon la version de l’extension :

Propriété function.json Description
type Cette propriété doit être définie sur cosmosDBTrigger.
direction Cette propriété doit être définie sur in. Ce paramètre est défini automatiquement lorsque vous créez le déclencheur dans le portail Azure.
name Nom de variable utilisé dans le code de fonction, qui représente la liste des documents modifiés.
connection Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui est surveillé. Pour plus d’informations, consultez Connexions.
databaseName Nom de la base de données Azure Cosmos DB contenant le conteneur analysé.
containerName Nom du conteneur surveillé.
leaseConnection (Facultatif) Nom d’un paramètre d’application ou d’un conteneur de paramètres qui spécifie la façon de se connecter au compte Azure Cosmos DB qui détient le conteneur de baux.

S’il n’est pas défini, la valeur connection est utilisée. Ce paramètre est automatiquement défini lorsque la liaison est créée dans le portail. La chaîne de connexion du conteneur de baux doit avoir des autorisations en écriture.
leaseDatabaseName (Facultatif) Nom de la base de données contenant le conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur du paramètre databaseName est utilisée.
leaseContainerName (Facultatif) Nom du conteneur utilisé pour stocker des baux. S’il n’est pas défini, la valeur leases est utilisée.
createLeaseContainerIfNotExists (Facultatif) Lorsque la valeur est définie sur true, le conteneur de baux est créé automatiquement s’il n’existe pas. La valeur par défaut est false. Lorsque vous utilisez des identités Microsoft Entra, si vous définissez la valeur sur true, la création de conteneurs n’est pas une opération autorisée et votre fonction ne pourra pas démarrer.
leasesContainerThroughput (Facultatif) Définit le nombre d’unités de requête à attribuer lors de la création du conteneur de baux. Ce paramètre est utilisé uniquement quand createLeaseContainerIfNotExists est défini sur true. Ce paramètre est automatiquement défini lors de la création de la liaison à l’aide du portail.
leaseContainerPrefix (Facultatif) Lorsque cette valeur est définie, elle est ajoutée en tant que préfixe aux baux créés dans le conteneur de baux pour cette fonction. L’utilisation d’un préfixe permet à deux fonctions Azure distinctes de partager le même conteneur de baux grâce à des préfixes différents.
feedPollDelay (Facultatif) Durée (en millisecondes) du délai s’écoulant entre le moment où toutes les modifications d’une partition sont purgées du flux et le moment où la partition est interrogée afin d’identifier de nouvelles modifications. La valeur par défaut est 5 000 millisecondes, soit 5 secondes.
leaseAcquireInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle pour déclencher une tâche afin de calculer si les partitions sont réparties uniformément parmi les instances d’hôte connues. La valeur par défaut est 13 000 (13 secondes).
leaseExpirationInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle selon lequel le bail est pris sur un bail représentant une partition. Si le bail n’est pas renouvelé dans cet intervalle, il expire et une autre instance devient propriétaire de la partition. La valeur par défaut est 60 000 (60 secondes).
leaseRenewInterval (Facultatif) Quand ce paramètre est défini, il spécifie, en millisecondes, l’intervalle de renouvellement de tous les baux pour les partitions actuellement détenues par une instance. La valeur par défaut est 17 000 (17 secondes).
maxItemsPerInvocation (Facultatif) Quand cette propriété est définie, elle détermine le nombrer maximal d’éléments reçus par appel de fonction. Si des opérations du conteneur analysé sont effectuées par le biais de procédures stockées, l’étendue de transaction est préservée lors de la lecture des éléments à partir du flux de modification. Par conséquent, le nombre d’éléments reçus pourrait être supérieur à la valeur spécifiée de sorte que les éléments modifiés par la même transaction soient retournés dans le cadre d’un même lot atomique.
startFromBeginning (Facultatif) Cette option indique au déclencheur de lire les modifications depuis le début de l’historique de modifications du conteneur au lieu de commencer à l’heure actuelle. La lecture depuis le début fonctionne uniquement au premier démarrage du déclencheur, car, lors des exécutions suivantes, les points de contrôle sont déjà stockés. La définition de cette option sur true quand des baux ont déjà été créés est sans effet.
startFromTime (Facultatif) Obtient ou définit la date et l’heure à partir desquelles l’opération de lecture du flux de modification doit être initialisée. Le format recommandé est ISO 8601 avec le désignateur UTC, par exemple 2021-02-16T14:19:29Z. Utilisé uniquement pour définir l’état initial du déclencheur. Une fois que le déclencheur a un état de bail, la modification de cette valeur n’a aucun effet.
preferredLocations (Facultatif) Définit les endroits par défaut (régions) des comptes de base de données géorépliqués dans le service Azure Cosmos DB. Les valeurs doivent être séparées par des virgules. Par exemple, « USA Est, USA Centre Sud, Europe Nord ».

Pour obtenir des exemples complets, consultez la section Exemple.

Usage

Le déclencheur nécessite une deuxième collection qu’il utilise pour stocker des baux sur les partitions. La collection surveillée et la collection contenant les baux doivent être disponibles pour que le déclencheur fonctionne.

Important

Si plusieurs fonctions sont configurées pour utiliser un déclencheur Azure Cosmos DB pour la même collection, chacune de ces fonctions doit utiliser une collection de baux dédiée ou spécifier un LeaseCollectionPrefix différent pour chaque fonction. Sinon, une seule des fonctions est déclenchée. Pour plus d’informations sur le préfixe, consultez la section Attributs.

Important

Si plusieurs fonctions sont configurées pour utiliser un déclencheur Azure Cosmos DB pour la même collection, chacune de ces fonctions doit utiliser une collection de baux dédiée ou spécifier un leaseCollectionPrefix différent pour chaque fonction. Sinon, une seule des fonctions est déclenchée. Pour plus d’informations sur le préfixe, consultez la section Annotations.

Important

Si plusieurs fonctions sont configurées pour utiliser un déclencheur Azure Cosmos DB pour la même collection, chacune de ces fonctions doit utiliser une collection de baux dédiée ou spécifier un leaseCollectionPrefix différent pour chaque fonction. Sinon, une seule des fonctions est déclenchée. Pour plus d’informations sur le préfixe, consultez la section Configuration.

Le déclencheur n’indique pas si un document a été mis à jour ou inséré, il fournit simplement le document lui-même. Si vous avez besoin de gérer les mises à jour et insertions différemment, vous pouvez le faire en implémentant des champs d’horodatage pour l’insertion ou la mise à jour.

Le type de paramètre pris en charge par le déclencheur Azure Cosmos DB dépend de la version du runtime Functions, de la version du package d’extension et de la modalité C# utilisée.

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.

Connexions

Les propriétés connectionStringSetting/connection et leaseConnectionStringSetting/leaseConnection sont des références à la configuration de l’environnement qui spécifie la façon dont l’application doit se connecter à Azure Cosmos DB. Elles peuvent spécifier :

  • Le nom d’un paramètre d’application contenant une chaîne de connexion
  • Le nom d’un préfixe partagé pour plusieurs paramètres d’application, définissant ensemble une connexion basée sur l’identité. Cette option n’est disponible que pour les versions connection et leaseConnection de la connection.

Si la valeur configurée est à la fois une correspondance exacte pour un paramètre unique et une correspondance de préfixe pour d’autres paramètres, la correspondance exacte est utilisée.

Chaîne de connexion

La chaîne de connexion de votre compte de base de données doit être stockée dans un paramètre d’application dont le nom correspond à la valeur spécifiée par la propriété de connexion de la configuration de la liaison.

Connexions basées sur l’identité

Si vous utilisez la version 4.x ou ultérieure de l’extension, au lieu d’utiliser une chaîne de connexion avec un secret, vous pouvez faire en sorte que l’application utilise une identité Microsoft Entra. Pour ce faire, vous devez définir les paramètres sous un préfixe commun qui correspond à la propriété de connexion dans la configuration des déclencheurs et des liaisons.

Dans ce mode, l’extension nécessite les propriétés suivantes :

Propriété Modèle de variable d’environnement Description Valeur d'exemple
Point de terminaison de compte <CONNECTION_NAME_PREFIX>__accountEndpoint URI du point de terminaison du compte Azure Cosmos DB. https://<database_account_name>.documents.azure.com:443/

Des propriétés supplémentaires peuvent être définies pour personnaliser la connexion. Consultez Propriétés communes pour les connexions basées sur l’identité.

Quand elles sont hébergées dans le service Azure Functions, les connexions basées sur une identité utilisent une identité managée. L’identité attribuée par le système est utilisée par défaut, bien qu’une identité attribuée par l’utilisateur puisse être spécifiée avec les propriétés credential et clientID. Notez que la configuration d’une identité affectée par l’utilisateur avec un ID de ressource n’est pas prise en charge. Lors d’une exécution dans d’autres contextes, tels que le développement local, votre identité de développeur est utilisée à la place, même si cela peut être personnalisé. Consultez Développement local avec connexions basées sur une identité.

Accorder l’autorisation à l’identité

Quelle que soit l’identité utilisée, elle doit avoir les autorisations nécessaires pour effectuer les actions prévues. Pour la plupart des services Azure, cela signifie que vous devez attribuer un rôle dans Azure RBAC en utilisant des rôles intégrés ou personnalisés qui fournissent ces autorisations.

Important

Parmi les autorisations exposées par le service cible, certaines ne sont peut-être pas nécessaires pour tous les contextes. Dans la mesure du possible, adhérez au principe du privilège minimum, en accordant à l’identité uniquement les privilèges nécessaires. Par exemple, si l’application a juste besoin de pouvoir lire à partir d’une source de données, utilisez un rôle qui a uniquement l’autorisation de lecture. Il serait inapproprié d’attribuer un rôle qui autorise aussi l’écriture dans ce service, car ce serait une autorisation excessive pour une opération de lecture. De même, vous voudrez vous assurer que l’attribution de rôle est limitée aux seules ressources qui doivent être lues.

Cosmos DB n’utilise pas Azure RBAC pour les opérations de données. Au lieu de cela, il utilise un système RBAC intégré à Cosmos DB qui repose sur des concepts similaires. Vous devrez créer une attribution de rôle qui donne accès à votre compte de base de données au moment de l’exécution. Les rôles de gestion Azure RBAC comme Propriétaire ne sont pas suffisants. Le tableau suivant présente les rôles intégrés qui sont recommandés lors de l’utilisation de l’extension Azure Cosmos DB dans le cadre d’un fonctionnement normal. Votre application peut nécessiter des autorisations supplémentaires en fonction du code que vous écrivez.

Type de liaison Exemples de rôles intégrés1
Déclencheur2 Contributeur de données intégré Cosmos DB
Liaison d’entrée Lecteur de données intégré Cosmos DB
Liaison de sortie Contributeur de données intégré Cosmos DB

1 Ces rôles ne peuvent pas être utilisés dans une attribution de rôle Azure RBAC. Pour plus d’informations sur l’attribution de ces rôles, consultez la documentation du Système RBAC intégré à Cosmos DB.

2 Lors de l’utilisation de l’identité, Cosmos DB traite la création de conteneurs comme une opération de gestion. Il n’est pas disponible en tant qu’opération de plan de données pour le déclencheur. Vous devez vous assurer de créer les conteneurs nécessaires au déclencheur (y compris le conteneur de bail) avant de configurer votre fonction.

Étapes suivantes