liaison de sortie Azure Cosmos DB pour Azure Functions 2.x et versions ultérieures

La liaison de sortie Azure Cosmos DB vous permet d’écrire un nouveau document dans une base de données Azure Cosmos DB à l’aide de l’API SQL.

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

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.

v2

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

v1

Le modèle de programmation Python v1 vous oblige à définir des liaisons dans un fichier function.json distinct dans le dossier de fonction. Pour plus d’informations, consultez le guide du développeur Python.

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

Une fonction C# peut être créée à l’aide de l’un des modes C# suivants :

• Modèle worker isolé : fonction C# compilée exécutée dans un processus worker isolé du runtime. Le processus de travail isolé est nécessaire pour prendre en charge les fonctions C# s’exécutant sur les versions LTS et non LTS .NET et .NET Framework. Les extensions pour les fonctions de processus worker isolées utilisent des espaces de noms Microsoft.Azure.Functions.Worker.Extensions.*.
• Modèle In-process : fonction C# compilée exécutée dans le même processus que le runtime 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#. Les extensions pour les fonctions in-process utilisent des espaces de noms Microsoft.Azure.WebJobs.Extensions.*.

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

Exemple

Sauf indication contraire, des exemples de cet article ciblent la version 3.x de l’extension Azure Cosmos DB. Pour une utilisation avec l’extension version 4.x, vous devez remplacer la chaîne collection dans les noms de propriétés et d’attributs par container et connection_string_setting par connection.

Le support Go n’est pas disponible pour ce liaison pour le moment.

Modèle de worker isolé

Le code suivant définit un type MyDocument :

Dans l’exemple suivant, le type de retour est un IReadOnlyList<T>, qui est une liste de documents modifiée à partir du paramètre de liaison du déclencheur :

Modèle in-process

Cette section contient les exemples suivants :

• Déclencheur de file d’attente, écrire un document
• Déclencheur de file d’attente, écrire un document (extension v4)
• Déclencheur de file d’attente, écrire des documents à l’aide d’IAsyncCollector

Les exemples font référence à un type ToDoItem simple :

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

Déclencheur de la file d’attente, écriture d’un document

L’exemple suivant montre une fonction C# qui ajoute un document à une base de données, à l’aide des données fournies dans le message de Stockage File d’attente.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Déclencheur de file d’attente, écrire un document (extension v4)

Les applications utilisant Azure Cosmos DB extension version 4.x ou ultérieure ont des propriétés d’attribut différentes qui sont indiquées ci-dessous. L’exemple suivant montre une fonction C# qui ajoute un document à une base de données, à l’aide des données fournies dans le message de Stockage File d’attente.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;

namespace CosmosDBSamplesV2
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")]out dynamic document,
            ILogger log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.LogInformation($"C# Queue trigger function inserted one row");
            log.LogInformation($"Description={queueMessage}");
        }
    }
}

Déclencheur de la file d’attente, écriture de documents à l’aide d’IAsyncCollector

L’exemple suivant montre une fonction C# qui ajoute une collection de documents à une base de données, à l’aide de données fournies dans un JSON de message de file d’attente.

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.LogInformation($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

• Déclencheur de file d’attente, enregistrer le message dans la base de données via la valeur de retour
• Déclencheur HTTP, enregistrer un document dans la base de données via la valeur de retour
• Déclencheur HTTP, enregistrer un document dans la base de données via OutputBinding
• Déclencheur HTTP, enregistrer plusieurs documents dans la base de données via OutputBinding

Déclencheur de file d’attente, enregistrer un message dans un base de données via une valeur de retour

L’exemple suivant montre une fonction Java qui ajoute un document à une base de données avec des données d’un message dans le stockage file d’attente.

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

Déclencheur HTTP, enregistrer un document dans une base de données via une valeur de retour

L’exemple suivant montre une fonction Java dont la signature est annotée avec @CosmosDBOutput et a la valeur de retour de type String. Le document JSON retourné par la fonction est automatiquement écrit dans la collection Azure Cosmos DB correspondante.

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

Déclencheur HTTP, enregistrer un document dans une base de données via OutputBinding

L’exemple suivant montre une fonction Java qui écrit un document dans Azure Cosmos DB via un paramètre de sortie OutputBinding<T>. Dans cet exemple, le paramètre outputItem doit être annoté avec @CosmosDBOutput, non la signature de la fonction. L’utilisation de OutputBinding<T> permet à votre fonction de tirer parti de la liaison pour écrire le document dans Azure Cosmos DB tout en permettant de retourner une valeur différente à l’appelant de fonction, comme un document JSON ou XML.

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

Déclencheur HTTP, enregistrer plusieurs documents dans une base de données via OutputBinding

L’exemple suivant montre une fonction Java qui écrit plusieurs documents dans Azure Cosmos DB via un paramètre de sortie OutputBinding<T>. Dans cet exemple, le paramètre outputItem est annoté avec @CosmosDBOutput, non la signature de la fonction. Le paramètre de sortie, outputItem, possède une liste d’objets ToDoItem comme type de paramètre de modèle. L’utilisation de OutputBinding<T> permet à votre fonction de tirer parti de la liaison pour écrire les documents dans Azure Cosmos DB tout en permettant de retourner une valeur différente à l’appelant de fonction, comme un document JSON ou XML.

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

Dans la bibliothèque runtime Java functions, utilisez l’annotation @CosmosDBOutput sur les paramètres écrits dans Azure Cosmos DB. Le type de paramètre d’annotation doit être OutputBinding<T>, où T est un type Java natif ou un POJO.

Modèle v4

L’exemple ci-dessous montre une fonction TypeScript déclenchée par une file d’attente de stockage pour une file d’attente qui reçoit des données JSON au format suivant :

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

La fonction crée Azure Cosmos DB documents au format suivant pour chaque enregistrement :

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Voici le code TypeScript :

Pour sortir plusieurs documents, retournez un tableau au lieu d’un seul objet. Par exemple :

Modèle v3

Les exemples TypeScript ne sont pas documentés pour le modèle v3.

Modèle v4

L’exemple ci-dessous montre une fonction JavaScript déclenchée par une file d’attente de stockage pour une file d’attente qui reçoit des données JSON au format suivant :

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

La fonction crée Azure Cosmos DB documents au format suivant pour chaque enregistrement :

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Voici le code JavaScript :

Pour sortir plusieurs documents, retournez un tableau au lieu d’un seul objet. Par exemple :

Modèle v3

L’exemple suivant montre une liaison de sortie Azure Cosmos DB dans un fichier function.json et une fonction JavaScript qui utilise la liaison. La fonction utilise une liaison d’entrée de file d’attente pour une file d’attente qui reçoit le code JSON au format suivant :

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

La fonction crée Azure Cosmos DB documents au format suivant pour chaque enregistrement :

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

Voici les données de liaison dans le fichier function.json :

{
    "name": "employeeDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

La section configuration décrit ces propriétés.

Voici le code JavaScript :

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

Pour l’insertion en bloc, commencez par former les objets, puis exécutez la fonction stringify. Voici le code JavaScript :

    module.exports = async function (context) {

        context.bindings.employeeDocument = JSON.stringify([
        {
            "id": "John Henry-123456",
            "name": "John Henry",
            "employeeId": "123456",
            "address": "A town nearby"
        },
        {
            "id": "John Doe-123457",
            "name": "John Doe",
            "employeeId": "123457",
            "address": "A town far away"
        }]);
    };

L’exemple suivant montre comment écrire des données dans Azure Cosmos DB à l’aide d’une liaison de sortie. La liaison est déclarée dans le fichier de configuration de la fonction (functions.json) et récupère les données d'un message de file d'attente et écrit dans un document Azure Cosmos DB.

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
} 

Dans le fichier run.ps1, l’objet retourné par la fonction est mis en correspondance avec un objet EmployeeDocument, qui est conservé dans la base de données.

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
} 

L’exemple suivant montre comment écrire un document dans une base de données Azure Cosmos DB comme sortie d’une fonction. L’exemple dépend de l’utilisation du modèle de programmation v1 ou v2 Python.

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

v1

Une définition de liaison est définie dans function.json , où Type possède la valeur cosmosDB.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

Pour écrire dans la base de données, transmettez un objet de document à la méthode set du paramètre Base de données.

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

Attributs

Les bibliothèques C# in-process et de processus Worker isolé utilisent des attributs 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#.

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

Propriété d’attribut	Descriptif
Connexion	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
BaseDeDonnées	Nom de la base de données Azure Cosmos DB avec le conteneur surveillé.
ContainerName	Nom du conteneur surveillé.
CreateIfNotExists	Valeur booléenne indiquant si le conteneur doit être créé s’il n’existe pas encore. La valeur par défaut est false, car les nouveaux conteneurs sont créés avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
PartitionKey	Lorsque CreateIfNotExists a la valeur true, définit le chemin de la clé de partition pour le conteneur créé. Peut inclure des paramètres de liaison.
ContainerThroughput	Lorsque CreateIfNotExists a la valeur true, définit le débit du conteneur créé.
PreferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.

Functions 2.x et versions ultérieures

Propriété d’attribut	Descriptif
ConnectionStringSetting	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
BaseDeDonnées	Nom de la base de données Azure Cosmos DB avec la collection surveillée.
CollectionName	Nom de la collection surveillée.
CreateIfNotExists	Valeur booléenne indiquant si la collection doit être créée si elle n’existe pas déjà. La valeur par défaut est false car les nouvelles collections sont créées avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
PartitionKey	Lorsque CreateIfNotExists a la valeur true, définit le chemin de la clé de partition pour la collection créée. Peut inclure des paramètres de liaison.
CollectionThroughput	Lorsque CreateIfNotExists a la valeur true, définit le débit de la collection créée.
PreferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.
UtiliserPlusieursEmplacementsD'Écriture	(Facultatif) Quand la valeur est true avec PreferredLocations, prend en charge les écritures multirégion dans le service Azure Cosmos DB.

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

Propriété d’attribut	Descriptif
Connexion	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
BaseDeDonnées	Nom de la base de données Azure Cosmos DB avec le conteneur surveillé.
ContainerName	Nom du conteneur surveillé.
CreateIfNotExists	Valeur booléenne indiquant si le conteneur doit être créé s’il n’existe pas encore. La valeur par défaut est false, car les nouveaux conteneurs sont créés avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
PartitionKey	Lorsque CreateIfNotExists a la valeur true, définit le chemin de la clé de partition pour le conteneur créé. Peut inclure des paramètres de liaison.
ContainerThroughput	Lorsque CreateIfNotExists a la valeur true, définit le débit du conteneur créé.
PreferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.

Functions 2.x et versions ultérieures

Propriété d’attribut	Descriptif
ConnectionStringSetting	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
BaseDeDonnées	Nom de la base de données Azure Cosmos DB avec la collection surveillée.
CollectionName	Nom de la collection surveillée.
CreateIfNotExists	Valeur booléenne indiquant si la collection doit être créée si elle n’existe pas déjà. La valeur par défaut est false car les nouvelles collections sont créées avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
PartitionKey	Lorsque CreateIfNotExists a la valeur true, définit le chemin de la clé de partition pour la collection créée. Peut inclure des paramètres de liaison.
CollectionThroughput	Lorsque CreateIfNotExists a la valeur true, définit le débit de la collection créée.
PreferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.
UtiliserPlusieursEmplacementsD'Écriture	(Facultatif) Quand la valeur est true avec PreferredLocations, prend en charge les écritures multirégion dans le service Azure Cosmos DB.

Décorateurs

Applies uniquement au modèle de programmation Python v2.

Pour Python fonctions v2 définies à l’aide d’un décorateur, les propriétés suivantes sur le cosmos_db_output :

Propriété	Descriptif
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 avec le conteneur surveillé.
container_name	Nom du conteneur Azure Cosmos DB surveillé.
create_if_not_exists	Valeur booléenne qui indique si la base de données et la collection doivent être créées si elles n’existent pas.
connection_string_setting	Connection string du Azure Cosmos DB surveillé.

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

Commentaires

À partir de la bibliothèque runtime Java functions, utilisez l’annotation @CosmosDBOutput sur les paramètres qui écrivent dans Azure Cosmos DB. L’annotation prend en charge les propriétés suivantes :

• nom
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• Datatype
• partitionKey
• preferredLocations
• useMultipleWriteLocations

Paramétrage

Applies uniquement au modèle de programmation Python v1.

Modèle v4

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

Modèle v3

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 :

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 :

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

Propriété function.json	Descriptif
connexion	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
databaseName	Nom de la base de données Azure Cosmos DB avec le conteneur surveillé.
containerName	Nom du conteneur surveillé.
createIfNotExists	Valeur booléenne indiquant si le conteneur doit être créé s’il n’existe pas encore. La valeur par défaut est false, car les nouveaux conteneurs sont créés avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
partitionKey	Lorsque createIfNotExists a la valeur true, définit le chemin de la clé de partition pour le conteneur créé. Peut inclure des paramètres de liaison.
containerThroughput	Lorsque createIfNotExists a la valeur true, définit le débit du conteneur créé.
preferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.

Functions 2.x et versions ultérieures

Propriété function.json	Descriptif
connectionStringSetting	Nom d’un paramètre d’application ou d’une collection de paramètres qui spécifie comment se connecter au compte Azure Cosmos DB en cours d’analyse. Pour plus d’informations, consultez Connexions.
databaseName	Nom de la base de données Azure Cosmos DB avec la collection surveillée.
collectionName	Nom de la collection surveillée.
createIfNotExists	Valeur booléenne indiquant si la collection doit être créée si elle n’existe pas déjà. La valeur par défaut est false car les nouvelles collections sont créées avec un débit réservé, ce qui a des conséquences sur la tarification. Pour plus d’informations, consultez la page relative aux prix appliqués.
partitionKey	Lorsque createIfNotExists a la valeur true, définit le chemin de la clé de partition pour la collection créée. Peut inclure des paramètres de liaison.
collectionThroughput	Lorsque createIfNotExists a la valeur true, définit le débit de la collection créée.
preferredLocations	(Facultatif) Définit les emplacements préférés (régions) pour les 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 : East US,South Central US,North Europe.
useMultipleWriteLocations	(Facultatif) Quand la valeur est true avec preferredLocations, prend en charge les écritures multirégion dans le service Azure Cosmos DB.

Pour obtenir des exemples complets, consultez la section Exemple.

Utilisation

Par défaut, lorsque vous écrivez dans le paramètre de sortie de votre fonction, un document est créé dans votre base de données. Vous devez spécifier l’ID du document de sortie en spécifiant la propriété id dans l’objet JSON transmis au paramètre de sortie.

Remarque

Lorsque vous spécifier l’ID d’un document existant, il est remplacé par le nouveau document de sortie.

Le paramètre de fonction de sortie doit être défini en tant que func.Out[func.Document]. Pour plus d’informations, reportez-vous à l’exemple de sortie .

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

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

Voir Types de liaison pour obtenir une liste des types supportés.

Functions 2.x et versions ultérieures

Voir Types de liaison pour obtenir une liste des types supportés.

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

Lorsque vous souhaitez que la fonction écrive dans un seul document, la liaison de sortie de 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 Register Azure clients 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

Voir Types de liaison pour obtenir une liste des types supportés.

Connexions

Les connection propriétés et leaseConnection sont définies sur des clés dans les paramètres d’application qui retournent les valeurs utilisées par l’exécution Functions pour se connecter aux points de terminaison du compte Azure Cosmos DB utilisés par l’extension. La valeur de ces paramètres de propriété dépend du type de connexion :

• Connexion d’identité gérée : La connection propriété est <CONNECTION_NAME_PREFIX> partagée par un groupe de paramètres qui définissent ensemble une connexion basée sur l’identité avec le compte. Pour plus d’informations, voir Définir les connexions identités.
• Référence Key Vault : Le connection paramètre de propriété renvoie une référence Azure Key Vault à l’emplacement où la chaîne de connexion est centralisée. Pour plus d’informations, voir Définir les connexions Key Vault.
• Référence App Configuration : Le connection paramètre de propriété renvoie une référence Azure App Configuration qui renvoie une chaîne de connexion ou une référence Key Vault. Pour plus d’informations, consultez Azure App Configuration dans l’article sur les connexions.
• Connection string : Le connection réglage de propriété renvoie la chaîne de connexion réelle du compte. Parce que la chaîne de connexion contient des clés secrètes partagées, vous devriez envisager d’utiliser une connexion d’identité gérée, lorsque c’est possible. Pour plus d’informations, voir Définir les connexions.

Pour en savoir plus sur les connexions de liaisons, consultez Gérer la connexion dans Azure Functions. Pour obtenir une chaîne de connexion, allez dans votre compte Azure Cosmos DB, sélectionnez Clés, puis copiez les valeurs de PRIMARY CONNECTION STRING ou SECONDARY CONNECTION STRING. Ces chaînes de connexion contiennent des clés secrètes partagées et doivent être sécurisées.

Dans les versions antérieures de l’extension, les propriétés de connexion étaient nommées connectionStringSetting et leaseConnectionStringSetting.

Exceptions et codes de retour

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

Étapes suivantes

• Exécuter une fonction lorsqu’un document Azure Cosmos DB est créé ou modifié (Déclencheur)
• Lire un document Azure Cosmos DB (liaison d’entrée)