Azure Cosmos DB liaison d’entrée pour Azure Functions 2.x et versions ultérieures

La liaison d’entrée Azure Cosmos DB utilise l’API SQL pour récupérer un ou plusieurs documents Azure Cosmos DB et les transmet au paramètre d’entrée de la fonction. L’ID du document ou les paramètres de requête peuvent être déterminés en fonction du déclencheur qui appelle la fonction.

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

Notes

Lorsque la collection est partitionnée, les opérations de recherche doivent également spécifier la valeur de clé de partition.

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 de décorateurs directement dans votre code de fonction Python. Pour plus d’informations, consultez le guide du développeur Python.

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

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é et d’attribut par container.

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

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

Cette section contient des exemples qui nécessitent la version 3.x de l’extension Azure Cosmos DB et la version 5.x de l’extension stockage Azure. Si elle n’est pas déjà présente dans votre application de fonction, ajoutez une référence aux packages NuGet suivants :

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

Déclencheur de file d’attente, rechercher l’ID à partir de JSON

L’exemple suivant illustre une fonction qui récupère un document unique. La fonction est déclenchée par un message JSON dans la file d’attente de stockage. Le déclencheur de file d’attente analyse le code JSON dans un objet de type ToDoItemLookup qui contient l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Cette section contient les exemples suivants :

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

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

Déclencheur HTTP, recherche d’ID dans la chaîne de requête : paramètre String

L’exemple suivant montre une fonction Java qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document à partir de la base de données et de la collection spécifiées sous la forme d’une chaîne.

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Dans la bibliothèque runtime Java functions, utilisez l’annotation @CosmosDBInput sur les paramètres de fonction dont la valeur proviendrait de Azure Cosmos DB. Cette annotation peut être utilisée avec des types d’Java natifs, des objets de conversation ou des valeurs nullables à l’aide de Optional<T>.

Déclencheur HTTP, recherche d’ID dans la chaîne de requête : paramètre POJO

L’exemple suivant montre une fonction Java qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document à partir de la base de données et de la collection spécifiées. Le document est ensuite converti en une instance du POJO ToDoItem précédemment créé et passé en tant qu’argument à la fonction.

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire

L’exemple suivant montre une fonction Java qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise un paramètre de routage pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document à partir de la base de données et de la collection spécifiées, en le retournant comme Optional<String>.

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire, utilisation de SqlQuery

L’exemple suivant montre une fonction Java qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise un paramètre de routage afin de spécifier l’ID à rechercher. Cet ID est utilisé pour récupérer un document à partir de la base de données et de la collection spécifiées, en convertissant le jeu de résultats en ToDoItem[], étant donné que de nombreux documents peuvent être retournés, en fonction des critères de la requête.

Notes

Si vous devez interroger uniquement l’ID, il est recommandé d’utiliser une recherche, comme les exemples précédents, car elle consomme moins d’unités de requête. Les opérations de lecture à point (GET) sont plus efficaces que les requêtes par ID.

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

Déclencheur HTTP, obtention de plusieurs documents à partir de données d’itinéraire, utilisation de SqlQuery

L’exemple suivant montre une fonction Java qui récupère plusieurs documents. La fonction est déclenchée par une requête HTTP qui utilise un paramètre de routage desc afin de spécifier la chaîne à rechercher dans le champ description. Le terme recherché est utilisé pour récupérer une collection de documents à partir de la base de données et de la collection spécifiées, en convertissant le jeu de résultats en ToDoItem[] et en le passant en tant qu’argument à la fonction.

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

Cette section contient les exemples suivants qui lisent un document unique en spécifiant une valeur d’ID à partir de diverses sources :

Déclencheur de file d’attente, rechercher l’ID à partir de JSON

L’exemple suivant montre une fonction TypeScript qui lit un seul document, et met à jour la valeur de texte du document.

Déclencheur HTTP, rechercher l’ID à partir de la chaîne de requête

L’exemple suivant montre une fonction TypeScript qui récupère un seul document. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire

L’exemple suivant montre une fonction TypeScript qui récupère un seul document. La fonction est déclenchée par une requête HTTP qui utilise des données de routage pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Déclencheur de file d’attente, obtenir plusieurs documents, utilisation de SqlQuery

L’exemple suivant montre une fonction TypeScript qui récupère plusieurs documents spécifiés par une requête SQL, en utilisant un déclencheur de file d’attente pour personnaliser les paramètres de requête.

Le déclencheur de file d’attente fournit un paramètre departmentId. Un message de file d’attente de { "departmentId" : "Finance" } retourne tous les enregistrements du service financier.

Cette section contient les exemples suivants qui lisent un document unique en spécifiant une valeur d’ID à partir de diverses sources :

Déclencheur de file d’attente, rechercher l’ID à partir de JSON

L’exemple suivant montre une fonction JavaScript qui lit un seul document, et met à jour la valeur de texte du document.

Déclencheur HTTP, rechercher l’ID à partir de la chaîne de requête

L’exemple suivant illustre une fonction JavaScript qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire

L’exemple suivant illustre une fonction JavaScript qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise des données de routage pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Déclencheur de file d’attente, obtenir plusieurs documents, utilisation de SqlQuery

L’exemple suivant montre une fonction JavaScript qui récupère plusieurs documents spécifiés par une requête SQL, en utilisant un déclencheur de file d’attente pour personnaliser les paramètres de requête.

Le déclencheur de file d’attente fournit un paramètre departmentId. Un message de file d’attente de { "departmentId" : "Finance" } retourne tous les enregistrements du service financier.

Déclencheur de file d’attente, rechercher l’ID à partir de JSON

L’exemple suivant montre comment lire et mettre à jour un document Azure Cosmos DB unique. L’identificateur unique du document est fourni par la valeur JSON dans un message de file d’attente.

La liaison d'entrée Azure Cosmos DB est répertoriée en premier dans la liste des liaisons trouvées dans le fichier de configuration de la fonction (function.json).

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

Le fichier run.ps1 contient le code PowerShell permettant de lire les modifications apportées au document entrant et aux sorties.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

Déclencheur HTTP, rechercher l’ID à partir de la chaîne de requête

L’exemple suivant montre comment lire et mettre à jour un document Azure Cosmos DB unique à partir d’une API web. L’identificateur unique du document est fourni par le biais d’un paramètre querystring à partir de la requête HTTP, comme défini dans la propriété "Id": "{Query.Id}" de la liaison.

La liaison d'entrée Azure Cosmos DB est répertoriée en premier dans la liste des liaisons trouvées dans le fichier de configuration de la fonction (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

Le fichier run.ps1 contient le code PowerShell permettant de lire les modifications apportées au document entrant et aux sorties.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire

L’exemple suivant montre comment lire et mettre à jour un document Azure Cosmos DB unique à partir d’une API web. L’identificateur unique du document est fourni par le biais d’un paramètre d’itinéraire. Le paramètre de routage est défini dans la propriété route de la liaison de requête HTTP et référencée dans la propriété de liaison Azure Cosmos DB "Id": "{Id}".

La liaison d'entrée Azure Cosmos DB est répertoriée en premier dans la liste des liaisons trouvées dans le fichier de configuration de la fonction (function.json).

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

Le fichier run.ps1 contient le code PowerShell permettant de lire les modifications apportées au document entrant et aux sorties.

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

Déclencheur de file d’attente, obtenir plusieurs documents, utilisation de SqlQuery

L’exemple suivant montre comment lire plusieurs documents Azure Cosmos DB. Le fichier de configuration de la fonction (function.json) définit les propriétés de liaison, y compris sqlQuery. L’instruction SQL fournie à la propriété sqlQuery sélectionne l’ensemble de documents fourni à la fonction.

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

Le fichier run1.ps1 contient le code PowerShell qui lit les documents entrants.

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

Cette section contient les exemples suivants qui lisent un document unique en spécifiant une valeur d’ID à partir de diverses sources :

Les exemples dépendent de l’utilisation du modèle de programmation v1 ou v2 Python.

Utilisation de liaisons SDK-Type pour Cosmos DB (préversion)

Cet exemple utilise des types sdk pour accéder directement à l’objet CosmosClient sous-jacent fourni par la liaison d’entrée Cosmos DB :

La fonction effectue une boucle dans toutes les bases de données et enregistre leurs ID.

import logging
import azure.functions as func
import azurefunctions.extensions.bindings.cosmosdb as cosmos

app = func.FunctionApp(http_auth_level=func.AuthLevel.FUNCTION)

@app.route(route="cosmos")
@app.cosmos_db_input(arg_name="client",
                     connection="CosmosDBConnection",
                     database_name=None,
                     container_name=None)
def get_docs(req: func.HttpRequest, client: cosmos.CosmosClient):
    databases = client.list_databases()
    for db in databases:
        logging.info(f"Found database with ID: {db.get('id')}")

    return "ok"

Pour obtenir des exemples d’utilisation d’autres types de SDK, consultez les exemples ContainerProxy et DatabaseProxy. Pour obtenir un didacticiel pas à pas sur l’ajout de liaisons de type SDK dans votre application de fonction, suivez l’exemple Python SDK Bindings for CosmosDB Sample.

Pour en savoir plus, y compris les autres liaisons de type sdk prises en charge, consultez les liaisons de type sdk.

Déclencheur de file d’attente, rechercher l’ID à partir de JSON

L’exemple suivant montre une liaison d’entrée Azure Cosmos DB. La fonction lit un document unique et met à jour la valeur texte du document.

import logging
import azure.functions as func

app = func.FunctionApp()

@app.queue_trigger(arg_name="msg", 
                   queue_name="outqueue", 
                   connection="AzureWebJobsStorage")
@app.cosmos_db_input(arg_name="documents", 
                     database_name="MyDatabase",
                     collection_name="MyCollection",
                     id="{msg.payload_property}",
                     partition_key="{msg.payload_property}",
                     connection_string_setting="MyAccount_COSMOSDB")
@app.cosmos_db_output(arg_name="outputDocument", 
                      database_name="MyDatabase",
                      collection_name="MyCollection",
                      connection_string_setting="MyAccount_COSMOSDB")
def test_function(msg: func.QueueMessage,
                  inputDocument: func.DocumentList, 
                  outputDocument: func.Out[func.Document]):
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

Déclencheur HTTP, rechercher l’ID à partir de la chaîne de requête

L’exemple suivant illustre une fonction qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise une chaîne de requête pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Aucun exemple équivalent pour v2 pour le moment.

Déclencheur HTTP, rechercher l’ID à partir des données d’itinéraire

L’exemple suivant illustre une fonction qui récupère un document unique. La fonction est déclenchée par une requête HTTP qui utilise des données de routage pour spécifier l’ID et la valeur de clé de partition à rechercher. Cet ID et cette valeur de clé de partition permettent de récupérer un document ToDoItem à partir de la base de données et de la collection spécifiées.

Aucun exemple équivalent pour v2 pour le moment.

Déclencheur de file d’attente, obtenir plusieurs documents, utilisation de SqlQuery

L’exemple suivant montre une Azure Cosmos DB liaison d’entrée Python fonction qui utilise la liaison. La fonction récupère plusieurs documents spécifiés par une requête SQL, à l’aide d’un déclencheur de file d’attente pour personnaliser les paramètres de requête.

Le déclencheur de file d’attente fournit un paramètre departmentId. Un message de file d’attente de { "departmentId" : "Finance" } retourne tous les enregistrements du service financier.

Aucun exemple équivalent pour v2 pour le moment.

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

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 interrogé. 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é.
PartitionKey Spécifie la valeur de la clé de partition pour la recherche. Peut inclure des paramètres de liaison. Requis pour les recherches dans les conteneurs partitionnés.
Id ID du document à récupérer. Cette propriété prend en charge les expressions de liaison. Ne définissez pas à la fois les propriétés Id et SqlQuery. Si vous ne définissez aucun des deux, l’ensemble du conteneur est récupéré.
SqlQuery Requête SQL Azure Cosmos DB utilisée pour récupérer plusieurs documents. La propriété prend en charge les liaisons d’exécution, comme dans cet exemple : SELECT * FROM c where c.departmentId = {departmentId}. Ne définissez pas à la fois les propriétés Id et SqlQuery. Si vous ne définissez aucun des deux, l’ensemble du conteneur est récupéré.
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.

Décorateurs

Applies uniquement au modèle de programmation Python v2.

Python fonctions v2 sont définies à l’aide du décorateur cosmos_db_input, qui prend en charge ces propriétés, en fonction de la version de l’extension :

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 la collection surveillée.
container_name Nom de la collection Azure Cosmos DB en cours d’analyse.
connection Connection string du Azure Cosmos DB surveillé.
partition_key Clé de partition du Azure Cosmos DB surveillé.
id ID du document à récupérer.

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 @CosmosDBInput sur les paramètres qui lisent à partir de Azure Cosmos DB. L’annotation prend en charge les propriétés suivantes :

Paramétrage

Applies 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 input.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 Descriptif
type Cette propriété doit être définie sur cosmosDB.
direction Cette propriété doit être définie sur in.
nom Nom de variable utilisé dans le code de fonction, qui représente la liste des documents modifiés.
connexion Nom d’un paramètre d’application ou d’un conteneur 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é.
partitionKey Spécifie la valeur de la clé de partition pour la recherche. Peut inclure des paramètres de liaison. Requis pour les recherches dans les conteneurs partitionnés.
id ID du document à récupérer. Cette propriété prend en charge les expressions de liaison. Ne définissez pas à la fois les propriétés id et sqlQuery. Si vous ne définissez aucun des deux, l’ensemble du conteneur est récupéré.
sqlQuery Requête SQL Azure Cosmos DB utilisée pour récupérer plusieurs documents. La propriété prend en charge les liaisons d’exécution, comme dans cet exemple : SELECT * FROM c where c.departmentId = {departmentId}. Ne définissez pas à la fois les propriétés id et sqlQuery. Si vous ne définissez aucun des deux, l’ensemble du conteneur est récupéré.
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.

Pour obtenir des exemples complets, consultez la section Exemple.

Utilisation

Lorsque la fonction se termine correctement, toutes les modifications apportées au document d’entrée sont automatiquement conservées.

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

Lorsque vous souhaitez que la fonction traite un seul document, la liaison d’entrée de 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.

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

À partir de la bibliothèque runtime Java functions, l’annotation @CosmosDBInput expose Azure Cosmos DB données à la fonction. Cette annotation peut être utilisée avec des types d’Java natifs, des objets de conversation ou des valeurs nullables à l’aide de Optional<T>.

Accédez au document en utilisant context.extraInputs.get().

Les mises à jour des documents ne sont pas effectuées automatiquement une fois la fonction terminée. Pour mettre à jour des documents dans une fonction, utilisez une liaison de sortie. Pour plus d'informations, consultez l'exemple PowerShell.

Les données sont mises à la disposition de la fonction via un paramètre DocumentList. Les modifications apportées au document ne sont pas automatiquement conservées. Functions prend également en charge Python liaisons de type sdk pour Azure Cosmos, ce qui vous permet d’utiliser des données à l’aide de ces types de SDK sous-jacents :

Important

La prise en charge des types de SDK CosmosDB pour Python est disponible en préversion et n’est prise en charge que pour le modèle de programmation Python v2. Pour plus d’informations, consultez les types SDK dans Python.

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.

Étapes suivantes

  • Last updated on