Enlace de entrada de Azure Cosmos DB para Azure Functions 2.x y versiones superiores

  • Artículo

El enlace de entrada de Azure Cosmos DB usa SQL API para recuperar uno o varios documentos de Azure Cosmos DB y los pasa al parámetro de entrada de la función. Se puede determinar el identificador de documento o los parámetros de consulta según el desencadenador que invoca la función.

Para obtener información sobre los detalles de instalación y configuración, vea la información general.

Nota

Cuando la colección tiene particiones, las operaciones de búsqueda también tienen que especificar el valor de la clave de partición.

Importante

En este artículo se usan pestañas para admitir varias versiones del modelo de programación de Node.js. El modelo v4 está disponible de forma general y está diseñado para que los desarrolladores de JavaScript y TypeScript tengan una experiencia más flexible e intuitiva. Para más detalles acerca de cómo funciona el modelo v4, consulte la Guía para desarrolladores de Node.js de Azure Functions. Para más información sobre las diferencias entre v3 y v4, consulte la Guía de migración.

Azure Functions admite dos modelos de programación para Python. La forma en que defina los enlaces depende del modelo de programación seleccionado.

El modelo de programación de Python v2 permite definir enlaces mediante decoradores directamente en el código de función de Python. Para más información, consulte la Guía para desarrolladores de Python.

En este artículo se admiten los modelos de programación.

Ejemplo

A menos que se indique lo contrario, los ejemplos de este artículo tienen como destino la versión 3.x de la extensión de Azure Cosmos DB. Para su uso con la versión 4.x de la extensión, debe reemplazar la cadena collection en los nombres de propiedad y atributo por container.

Se puede crear una función C# mediante uno de los siguientes modos de C#:

  • Modelo de trabajo aislado: función compilada en C# que se ejecuta en un proceso trabajador aislado del tiempo de ejecución. Se requiere un proceso de trabajo aislado para admitir funciones de C# ejecutándose en versiones de .NET que son y no son LTS y .NET Framework. Las extensiones para las funciones de proceso de trabajo aisladas usan espacios de nombres Microsoft.Azure.Functions.Worker.Extensions.*.
  • Modelo en curso: función C# compilada que se ejecuta en el mismo proceso que el tiempo de ejecución de Functions. En una variación de este modelo, Functions se puede ejecutar mediante el scripting de C#, que se admite principalmente para la edición del portal de C#. Las extensiones para funciones en proceso utilizan espacios de nombres Microsoft.Azure.WebJobs.Extensions.*.

Importante

La compatibilidad finalizará para el modelo en proceso el 10 de noviembre de 2026. Se recomienda encarecidamente migrar las aplicaciones al modelo de trabajo aislado para obtener compatibilidad completa.

Esta sección contiene ejemplos que requieren la versión 3.x de la extensión de Azure Cosmos DB y 5.x de la extensión de Azure Storage. Si aún no está presente en la aplicación de funciones, agregue una referencia a los siguientes paquetes de NuGet:

Los ejemplos hacen referencia a un tipo de ToDoItem simple:

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

Desencadenador de cola, buscar identificador a partir de un JSON

En el ejemplo siguiente se muestra una función que recupera un documento individual. La función se desencadena mediante un mensaje JSON en la cola de almacenamiento. El desencadenador de la cola analiza el JSON en un objeto del tipo ToDoItemLookup, que contiene el identificador y el valor de la clave de partición que se va a recuperar. El identificador y el valor de la clave de partición se utilizan para devolver un documento ToDoItem de la base de datos y colección especificadas.

[Function(nameof(DocByIdFromJSON))]
public void DocByIdFromJSON(
    [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
    [CosmosDBInput(
        databaseName: "ToDoItems",
        containerName: "Items",
        Connection  = "CosmosDBConnection",
        Id = "{ToDoItemId}",
        PartitionKey = "{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
{
    _logger.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

    if (toDoItem == null)
    {
        _logger.LogInformation($"ToDo item not found");
    }
    else
    {
        _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
    }
}

En esta sección se incluyen los ejemplos siguientes:

Los ejemplos hacen referencia a un tipo de 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 + "}";
  }
}

Desencadenador HTTP, buscar identificador en la cadena de consulta: parámetro de cadena

En el ejemplo siguiente se muestra una función de Java que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza una cadena de consulta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento de la base de datos y colección especificadas, en forma de cadena.

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();
        }
    }
}

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @CosmosDBInput en los parámetros de la función cuyo valor provendría de Azure Cosmos DB. Esta anotación se puede usar con tipos nativos de Java, POJO o valores que aceptan valores NULL mediante Optional<T>.

Desencadenador HTTP, buscar identificador en la cadena de consulta: parámetro POJO

En el ejemplo siguiente se muestra una función de Java que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza una cadena de consulta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento de la base de datos y colección especificadas. A continuación, el documento se convierte en una instancia de la anotación ToDoItem POJO creada previamente y se pasa como argumento a la función.

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();
        }
    }
}

Desencadenador de HTTP, buscar identificador a partir de datos de ruta

En el ejemplo siguiente se muestra una función de Java que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza un parámetro de ruta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento de la base de datos y colección especificadas, que se devuelve como un objeto 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();
        }
    }
}

Desencadenador de HTTP, buscar identificador a partir de datos de ruta mediante SqlQuery

En el ejemplo siguiente se muestra una función de Java que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza un parámetro de ruta para especificar el identificador que se va a buscar. Ese identificador se usa para recuperar un documento de la base de datos y la colección especificadas, convirtiendo el conjunto de resultados en una anotación ToDoItem[], ya que pueden devolverse muchos documentos, en función de los criterios de consulta.

Nota

Si tiene que realizar una consulta solo con el identificador, se recomienda utilizar una búsqueda, como en los ejemplos anteriores, ya que consumirá menos unidades de solicitud. Las operaciones de lectura de punto (GET) son más eficaces que las consultas por identificador.

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();
        }
    }
}

Desencadenador HTTP, obtener varios documentos de los datos de ruta, mediante SqlQuery

En el ejemplo siguiente se muestra una función de Java que recupera varios documentos. La función la desencadena una solicitud HTTP que utiliza un parámetro de ruta desc para especificar la cadena que se va a buscar en el campo description. El término de búsqueda se usa para recuperar una colección de documentos de la base de datos y de la colección especificadas, lo que convierte el conjunto de resultados en una anotación ToDoItem[] y la pasa como un argumento a la función.

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();
        }
    }
}

Esta sección contiene los siguientes ejemplos que leen un solo documento mediante la especificación de un valor de identificación desde varios orígenes:

Desencadenador de cola, buscar identificador a partir de un JSON

En el ejemplo siguiente se muestra una función de TypeScript que lee un único documento y actualiza el valor de texto del documento.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

interface MyDocument {
    text: string;
}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const doc = <MyDocument>context.extraInputs.get(cosmosInput);
    doc.text = 'This was updated!';
    context.extraOutputs.set(cosmosOutput, doc);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: storageQueueTrigger1,
});

Desencadenador de HTTP, buscar identificador a partir de una cadena de consulta

En el ejemplo siguiente se muestra una función de TypeScript que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza una cadena de consulta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Desencadenador de HTTP, buscar identificador a partir de datos de ruta

En el ejemplo siguiente se muestra una función de TypeScript que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza datos de ruta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface ToDoDocument {
    description: string;
}

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const toDoItem = <ToDoDocument>context.extraInputs.get(cosmosInput);
    if (!toDoItem) {
        return {
            status: 404,
            body: 'ToDo item not found',
        };
    } else {
        return {
            body: `Found ToDo item, Description=${toDoItem.description}`,
        };
    }
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: httpTrigger1,
});

Desencadenador de colas, obtener varios documentos mediante SqlQuery

En el ejemplo siguiente se muestra una función de TypeScript que recupera varios documentos especificados por una consulta SQL mediante un desencadenador de cola para personalizar los parámetros de la consulta.

El desencadenador de cola proporciona un parámetro departmentId. Un mensaje de la cola de { "departmentId" : "Finance" } devolvería todos los registros para el departamento de finanzas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

interface MyDocument {}

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    const documents = <MyDocument[]>context.extraInputs.get(cosmosInput);
    for (const document of documents) {
        // operate on each document
    }
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: storageQueueTrigger1,
});

Esta sección contiene los siguientes ejemplos que leen un solo documento mediante la especificación de un valor de identificación desde varios orígenes:

Desencadenador de cola, buscar identificador a partir de un JSON

En el ejemplo siguiente se muestra una función de JavaScript que lee un único documento y actualiza el valor de texto del documento.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    id: '{queueTrigger}',
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

const cosmosOutput = output.cosmosDB({
    databaseName: 'MyDatabase',
    collectionName: 'MyCollection',
    createIfNotExists: false,
    partitionKey: '{queueTrigger}',
    connectionStringSetting: 'MyAccount_COSMOSDB',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    extraOutputs: [cosmosOutput],
    handler: (queueItem, context) => {
        const doc = context.extraInputs.get(cosmosInput);
        doc.text = 'This was updated!';
        context.extraOutputs.set(cosmosOutput, doc);
    },
});

Desencadenador de HTTP, buscar identificador a partir de una cadena de consulta

En el ejemplo siguiente se muestra una función de JavaScript que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza una cadena de consulta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{Query.id}',
    partitionKey: '{Query.partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Desencadenador de HTTP, buscar identificador a partir de datos de ruta

En el ejemplo siguiente se muestra una función de JavaScript que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza datos de ruta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'ToDoItems',
    collectionName: 'Items',
    id: '{id}',
    partitionKey: '{partitionKeyValue}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    route: 'todoitems/{partitionKeyValue}/{id}',
    extraInputs: [cosmosInput],
    handler: (request, context) => {
        const toDoItem = context.extraInputs.get(cosmosInput);
        if (!toDoItem) {
            return {
                status: 404,
                body: 'ToDo item not found',
            };
        } else {
            return {
                body: `Found ToDo item, Description=${toDoItem.Description}`,
            };
        }
    },
});

Desencadenador de colas, obtener varios documentos mediante SqlQuery

En el ejemplo siguiente se muestra una función de JavaScript que recupera varios documentos especificados por una consulta SQL mediante un desencadenador de cola para personalizar los parámetros de la consulta.

El desencadenador de cola proporciona un parámetro departmentId. Un mensaje de la cola de { "departmentId" : "Finance" } devolvería todos los registros para el departamento de finanzas.

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

const cosmosInput = input.cosmosDB({
    databaseName: 'MyDb',
    collectionName: 'MyCollection',
    sqlQuery: 'SELECT * from c where c.departmentId = {departmentId}',
    connectionStringSetting: 'CosmosDBConnection',
});

app.storageQueue('storageQueueTrigger1', {
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
    extraInputs: [cosmosInput],
    handler: (queueItem, context) => {
        const documents = context.extraInputs.get(cosmosInput);
        for (const document of documents) {
            // operate on each document
        }
    },
});

Desencadenador de cola, buscar identificador a partir de un JSON

En el ejemplo siguiente se muestra cómo leer y actualizar un solo documento de Azure Cosmos DB. El identificador único del documento se proporciona a través del valor JSON en un mensaje de cola.

El enlace de entrada de Azure Cosmos DB se muestra en primer lugar en la lista de enlaces que se encuentra en el archivo de configuración de la función (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"
}

El archivo run.ps1 tiene el código de PowerShell que lee el documento entrante y genera los cambios.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Desencadenador de HTTP, buscar identificador a partir de una cadena de consulta

En el ejemplo siguiente se muestra cómo leer y actualizar un único documento de Azure Cosmos DB desde una API web. El identificador único del documento se proporciona a través de un parámetro de cadena de consulta de la solicitud HTTP, tal y como se define en la propiedad "Id": "{Query.Id}" del enlace.

El enlace de entrada de Azure Cosmos DB se muestra en primer lugar en la lista de enlaces que se encuentra en el archivo de configuración de la función (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 
}

El archivo run.ps1 tiene el código de PowerShell que lee el documento entrante y genera los cambios.

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

Desencadenador de HTTP, buscar identificador a partir de datos de ruta

En el ejemplo siguiente se muestra cómo leer y actualizar un único documento de Azure Cosmos DB desde una API web. El identificador único del documento se proporciona a través de un parámetro de ruta. El parámetro route se define en la propiedad route del enlace de la solicitud HTTP y se hace referencia a este en la propiedad de enlace "Id": "{Id}" de Azure Cosmos DB.

El enlace de entrada de Azure Cosmos DB se muestra en primer lugar en la lista de enlaces que se encuentra en el archivo de configuración de la función (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 
}

El archivo run.ps1 tiene el código de PowerShell que lee el documento entrante y genera los cambios.

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

Desencadenador de colas, obtener varios documentos mediante SqlQuery

En el ejemplo siguiente se muestra cómo leer varios documentos de Azure Cosmos DB. El archivo de configuración de la función (function.json) define las propiedades de enlace, que incluyen la propiedad sqlQuery. La instrucción SQL que se proporciona para la propiedad sqlQuery selecciona el conjunto de documentos proporcionados para la función.

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

El archivo run1.ps1 tiene el código de PowerShell que lee los documentos entrantes.

param($QueueItem, $Documents, $TriggerMetadata)

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

Esta sección contiene los siguientes ejemplos que leen un solo documento mediante la especificación de un valor de identificación desde varios orígenes:

Los ejemplos dependen de si usa el modelo de programación de Python v1 o v2.

Desencadenador de cola, buscar identificador a partir de un JSON

En el ejemplo siguiente se muestra un enlace de entrada de Azure Cosmos DB. La función lee un solo documento y actualiza el valor de texto del documento.

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]):
     document = documents[id]
     document["text"] = "This was updated!"
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

Desencadenador de HTTP, buscar identificador a partir de una cadena de consulta

En el ejemplo siguiente se muestra una función que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza una cadena de consulta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

No hay ningún ejemplo equivalente para v2 en este momento.

Desencadenador de HTTP, buscar identificador a partir de datos de ruta

En el ejemplo siguiente se muestra una función que recupera un documento individual. La función la desencadena una solicitud HTTP que utiliza datos de ruta para especificar el identificador y el valor de la clave de partición que se van a buscar. El identificador y el valor de la clave de partición se utilizan para recuperar un documento ToDoItem de la base de datos y colección especificadas.

No hay ningún ejemplo equivalente para v2 en este momento.

Desencadenador de colas, obtener varios documentos mediante SqlQuery

En el ejemplo siguiente se muestra un enlace de entrada de Azure Cosmos DB a una función de Python que usa dicho enlace. La función recupera varios documentos especificados por una consulta SQL con un desencadenador de cola para personalizar los parámetros de la consulta.

El desencadenador de cola proporciona un parámetro departmentId. Un mensaje de la cola de { "departmentId" : "Finance" } devolvería todos los registros para el departamento de finanzas.

No hay ningún ejemplo equivalente para v2 en este momento.

Atributos

Las bibliotecas de C# en proceso y de proceso de trabajo aislado usan atributos para definir la función. En su lugar, el script de C# usa un archivo de configuración function.json como se describe en la guía de scripting de C#.

Propiedad de atributo Descripción
Connection Nombre de una configuración de aplicación o colección de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a consultar. Para obtener más información, consulte Conexiones.
DatabaseName Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
ContainerName Nombre del contenedor que se está supervisando.
PartitionKey Especifica el valor de la clave de partición para la búsqueda. Puede incluir parámetros de enlace. Se requiere para las búsquedas en contenedores con particiones.
Id Identificador del documento que se va a recuperar. Esta propiedad es compatible con expresiones de enlace. No establezca las propiedades Id y SqlQuery a la vez. Si no establece alguna de ellas, se recupera todo el contenedor.
SqlQuery Consulta SQL de Azure Cosmos DB que se usa para recuperar varios documentos. La propiedad es compatible con los enlaces en tiempo de ejecución, como en este ejemplo: SELECT * FROM c where c.departmentId = {departmentId}. No establezca las propiedades Id y SqlQuery a la vez. Si no establece alguna de ellas, se recupera todo el contenedor.
PreferredLocations (Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, East US,South Central US,North Europe.

Elementos Decorator

Solo se aplica al modelo de programación de Python v2.

Para las funciones de Python v2 definidas mediante un decorador, se aplican las siguientes propiedades en cosmos_db_input:

Propiedad Descripción
arg_name Nombre de la variable que se utiliza en el código de función y que representa la lista de documentos con los cambios.
database_name Nombre de la base de datos de Azure Cosmos DB con la colección que se está supervisando.
collection_name Nombre de la colección de Azure Cosmos DB que se está supervisando.
connection_string_setting Cadena de conexión de Azure Cosmos DB que se está supervisando.
partition_key Clave de partición de Azure Cosmos DB que se está supervisando.
id Identificador del documento que se va a recuperar.

Para las funciones de Python definidas mediante function.json, consulte la sección Configuración.

anotaciones

En la biblioteca en tiempo de ejecución de funciones de Java, utilice la anotación @CosmosDBInput en los parámetros que leen de Azure Cosmos DB. La anotación admite las propiedades siguientes:

Configuración

Solo se aplica al modelo de programación de Python v1.

En la tabla siguiente se explican las propiedades que puede establecer en el objeto options que se pasa al métodoinput.cosmosDB(). Las propiedades type, direction y name no se aplican al modelo v4.

En la siguiente tabla se explican las propiedades de configuración de enlace que se definen en el archivo function.json, donde las propiedades difieren en la versión de la extensión:

Propiedad de function.json Descripción
type Se debe establecer en cosmosDB.
direction Se debe establecer en in.
name Nombre de la variable que se utiliza en el código de función y que representa la lista de documentos con los cambios.
connection Nombre de una configuración de aplicación o contenedor de configuraciones que especifica cómo conectarse a la cuenta de Azure Cosmos DB que se va a supervisar. Para obtener más información, consulte Conexiones.
databaseName Nombre de la base de datos de Azure Cosmos DB con el contenedor que se está supervisando.
containerName Nombre del contenedor que se está supervisando.
partitionKey Especifica el valor de la clave de partición para la búsqueda. Puede incluir parámetros de enlace. Se requiere para las búsquedas en contenedores con particiones.
id Identificador del documento que se va a recuperar. Esta propiedad es compatible con expresiones de enlace. No establezca las propiedades id y sqlQuery a la vez. Si no establece alguna de ellas, se recupera todo el contenedor.
sqlQuery Consulta SQL de Azure Cosmos DB que se usa para recuperar varios documentos. La propiedad es compatible con los enlaces en tiempo de ejecución, como en este ejemplo: SELECT * FROM c where c.departmentId = {departmentId}. No establezca las propiedades id y sqlQuery a la vez. Si no establece alguna de ellas, se recupera todo el contenedor.
preferredLocations (Opcional) Defina las ubicaciones preferidas (regiones) para las cuentas de base de datos con replicación geográfica en el servicio de Azure Cosmos DB. Los valores deben estar separados por comas. Por ejemplo, East US,South Central US,North Europe.

Consulte la sección de ejemplos para ver ejemplos completos.

Uso

Cuando se sale de la función correctamente, los cambios realizados en el documento de entrada se conservan automáticamente.

El tipo de parámetro admitido por el enlace de entrada de Cosmos DB depende de la versión del tiempo de ejecución de Functions, la versión del paquete de extensión y la modalidad de C# utilizada.

Cuando quiera que la función procese un único documento, el enlace de entrada de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo Descripción
Tipos serializables con JSON Functions intenta deserializar los datos JSON del documento en un tipo de objeto CLR antiguo y sin formato (POCO).

Cuando quiera que la función procese varios documentos desde una consulta, el enlace de entrada de Cosmos DB puede enlazarse a los siguientes tipos:

Tipo Descripción
IEnumerable<T> donde T es un tipo JSON serializable Una enumeración de entidades devueltas por la consulta. Cada entrada representa un documento.
CosmosClient1 Un cliente conectado a la cuenta de Cosmos DB.
Database1 Un cliente conectado a la base de datos de Cosmos DB.
Container1 Un cliente conectado al contenedor de Cosmos DB.

1 Para usar estos tipos, debe hacer referencia a Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 o posterior y a las dependencias comunes para los enlaces de tipo de SDK.

En la biblioteca en tiempo de ejecución de funciones de Java, la anotación @CosmosDBInput expone los datos de Azure Cosmos DB a la función. Esta anotación se puede usar con tipos nativos de Java, POJO o valores que aceptan valores NULL mediante Optional<T>.

Acceda al documento mediante context.extraInputs.get().

Las actualizaciones en los documentos no se realizan automáticamente al cerrar la función. Para actualizar documentos en una función, use un enlace de salida. Consulte el ejemplo de PowerShell para más detalles.

Los datos se ponen a disposición de la función mediante un parámetro DocumentList. Los cambios realizados en el documento no se conservan automáticamente.

Conexiones

Las propiedades connectionStringSetting/connection y leaseConnectionStringSetting/leaseConnection son referencias a la configuración del entorno que especifica cómo se debe conectar la aplicación a Azure Cosmos DB. Pueden especificar:

Si el valor configurado es tanto una coincidencia exacta de una única configuración como una coincidencia de prefijo de otras configuraciones, se usa la coincidencia exacta.

Cadena de conexión

La cadena de conexión de la cuenta de base de datos debe almacenarse en una configuración de la aplicación con un nombre que coincida con el valor especificado por la propiedad de conexión de la configuración de enlace.

Conexiones basadas en identidades

Si usa la versión 4.x o posterior de la extensión, en lugar de usar una cadena de conexión con un secreto, puede hacer que la aplicación use una identidad de Microsoft Entra. Para ello, defina la configuración con un prefijo común que se asigne a la propiedad de conexión en la configuración de desencadenador y enlace.

En este modo, la extensión requiere las siguientes propiedades:

Propiedad Plantilla de variable de entorno Descripción Valor de ejemplo
Punto de conexión de la cuenta <CONNECTION_NAME_PREFIX>__accountEndpoint El identificador URI del punto de conexión de la cuenta de Azure Cosmos DB. https://<database_account_name>.documents.azure.com:443/

Se pueden establecer propiedades adicionales para personalizar la conexión. Consulte Propiedades comunes para conexiones basadas en identidades.

Cuando se hospeda en el servicio de Azure Functions, las conexiones basadas en identidades usan una identidad administrada. La identidad asignada por el sistema se usa de manera predeterminada, aunque se puede especificar una identidad asignada por el usuario con las propiedades credential y clientID. Tenga en cuenta que no se admite la configuración de una identidad asignada por el usuario con un identificador de recurso. Cuando se ejecuta en otros contextos, como el de desarrollo local, se usa en su lugar la identidad del desarrollador, aunque se puede personalizar. Consulte Desarrollo local con conexiones basadas en identidades.

Concesión de permiso a la identidad

Cualquier identidad que se utilice debe tener permisos para realizar las acciones previstas. Para la mayoría de los servicios de Azure, esto significa que debe asignar un rol en Azure RBAC mediante roles integrados o personalizados que proporcionen esos permisos.

Importante

Es posible que el servicio de destino muestre algunos permisos que no son necesarios para todos los contextos. Siempre que sea posible, respete el principio de privilegios mínimos y conceda solo los privilegios necesarios a la identidad. Por ejemplo, si la aplicación solo necesita poder leer desde un origen de datos, use un rol que solo tenga permiso de lectura. Sería inadecuado asignar un rol que también permita escribir en ese servicio, ya que sería un permiso excesivo para una operación de lectura. De forma similar, le interesa asegurarse de que la asignación de roles esté limitada solo a los recursos que se deben leer.

Cosmos DB no usa Azure RBAC para las operaciones de datos. En su lugar, usa un sistema de RBAC integrado de Cosmos DB que se basa en conceptos similares. Deberá crear una asignación de roles que proporcione acceso a la cuenta de base de datos en tiempo de ejecución. Los roles de administración de Azure RBAC, como Propietario, no son suficientes. En la tabla siguiente se muestran los roles integrados que se recomiendan al usar la extensión de Azure Cosmos DB en funcionamiento normal. Puede que la aplicación precise permisos adicionales en función del código que escriba.

Tipo de enlace Roles integrados de ejemplo1
Desencadenador2 Colaborador de datos integrado de Cosmos DB
Enlace de entrada Lector de datos integrado de Cosmos DB
Enlace de salida Colaborador de datos integrado de Cosmos DB

1 Estos roles no se pueden usar en una asignación de roles de RBAC de Azure. Consulte la documentación del sistema de RBAC integrado de Cosmos DB para más información sobre cómo asignar estos roles.

2 Cuando se usa la identidad, Cosmos DB trata la creación de contenedores como una operación de administración. No está disponible como una operación de plano de datos para el desencadenador. Deberá asegurarse de crear los contenedores necesarios para el desencadenador (incluido el contenedor de concesión) antes de configurar la función.

Pasos siguientes