Поделиться через

Входная привязка Azure Cosmos DB для Функций Azure 2.x и более поздних версий

  • Статья

Входная привязка Azure Cosmos DB извлекает один или несколько документов из Azure Cosmos DB и передает их входному параметру функции через API SQL. Идентификатор документа или параметры запроса можно определить по триггеру, который вызывает функцию.

Сведения об установке и настройке см. в обзорной статье.

Примечание.

Если коллекция секционирована, операции поиска должны также указывать значение ключа раздела.

Внимание

В этой статье используются вкладки для поддержки нескольких версий модели программирования Node.js. Модель версии 4 общедоступна и предназначена для более гибкого и интуитивно понятного интерфейса для разработчиков JavaScript и TypeScript. Дополнительные сведения о том, как работает модель версии 4, см. в руководстве разработчика по Функции Azure Node.js. Дополнительные сведения о различиях между версиями 3 и 4 см. в руководстве по миграции.

Функции Azure поддерживает две модели программирования для Python. Способ определения привязок зависит от выбранной модели программирования.

Модель программирования Python версии 2 позволяет определять привязки с помощью декораторов непосредственно в коде функции Python. Дополнительные сведения см. в руководстве разработчика Python.

Эта статья поддерживает обе модели программирования.

Пример

Если не указано иное, примеры в этой статье предназначены для расширения Azure Cosmos DB версии 3.x. Для использования с расширением версии 4.x необходимо изменить строку collection в именах свойств и атрибутов на container.

Функцию C# можно создать с помощью одного из следующих режимов C#:

  • Изолированная рабочая модель: скомпилированная функция C#, которая выполняется в рабочем процессе, изолированном от среды выполнения. Изолированный рабочий процесс необходим для поддержки функций C#, работающих в LTS и не LTS-версиях .NET и платформа .NET Framework. Расширения для изолированных рабочих процессов используют Microsoft.Azure.Functions.Worker.Extensions.* пространства имен.
  • Модель внутрипроцессного процесса: скомпилированная функция C#, которая выполняется в том же процессе, что и среда выполнения Функций. В варианте этой модели функции можно запускать с помощью скриптов C#, которая поддерживается главным образом для редактирования портала C#. Расширения для функций в процессе используют Microsoft.Azure.WebJobs.Extensions.* пространства имен.

Внимание

Поддержка будет завершена для модели в процессе 10 ноября 2026 г. Настоятельно рекомендуется перенести приложения в изолированную рабочую модель для полной поддержки.

В этом разделе приведены примеры, для которых требуется расширение Azure Cosmos DB версии 3.x и расширение служба хранилища Azure версии 5.x. Если ее еще нет в вашем приложении-функции, добавьте ссылку на следующие пакеты NuGet:

В примерах используется ToDoItem простого типа:

[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}");
    }
}

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция, которая получает один документ. Функция активируется сообщением JSON в очереди хранилища. Триггер очереди анализирует JSON в объект типа ToDoItemLookup, который содержит идентификатор и значение ключа раздела для получения. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

[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}");
    }
}

Этот раздел содержит следующие примеры.

В примерах используется ToDoItem простого типа:

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 + "}";
  }
}

Триггер HTTP, поисковый идентификатор из строки запроса — строковый параметр

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа из указанной базы данных и коллекции в формате String.

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

В библиотеке среды выполнения функций Java используйте заметку @CosmosDBInput для параметров функции, значение которых будет поступать из Azure Cosmos DB. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>.

Триггер HTTP, поисковый идентификатор из строки запроса — параметр POJO

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела использовались для получения документа из указанной базы данных и коллекции. Затем документ преобразуется в ранее созданный экземпляр POJO ToDoItem и передается функции в качестве аргумента.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция Java, которая получает один документ. Функция активируется HTTP-запросом, который использует параметр маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа из указанной базы данных и коллекции, возвращая его как 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();
        }
    }
}

Триггер HTTP, поисковый идентификатор из данных маршрута, используется SqlQuery

В следующем примере показана функция Java, которая получает один документ. Функция инициируется HTTP-запросом, в параметре маршрута которого указан идентификатор для поиска. Этот идентификатор используется для получения документа из указанной базы данных и коллекции. При этом результирующий набор преобразуется в ToDoItem[], так как может быть возвращено несколько документов в зависимости от критериев запроса.

Примечание.

Если необходимо выполнить запрос только по идентификатору, рекомендуется использовать поиск, как в предыдущих примерах, так как будет потребляться меньше единиц запроса. Операции чтения точки (GET) более эффективны, чем запросы по идентификатору.

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

Триггер HTTP, получение нескольких документов из данных маршрута, используется SqlQuery

В следующем примере показана функция Java, которая извлекает один документ. Эта функция инициируется HTTP-запросом, в параметре маршрута desc которого указана строка для поиска в поле description. Поисковый запрос используется для получения коллекции документов из указанной базы данных и коллекции. При этом результирующий набор преобразуется в ToDoItem[] и передается функции в качестве аргумента.

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

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция TypeScript, которая считывает один документ и обновляет текстовое значение документа.

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

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция TypeScript, извлекающая один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция TypeScript, извлекающая один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция TypeScript, которая извлекает несколько документов, указанных sql-запросом, с помощью триггера очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

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

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана функция JavaScript, которая считывает один документ и обновляет текстовое значение документа.

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

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция JavaScript, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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}`,
            };
        }
    },
});

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция JavaScript, которая получает один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

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}`,
            };
        }
    },
});

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция JavaScript, которая извлекает несколько документов, указанных sql-запросом, с помощью триггера очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

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

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB. Уникальный идентификатор документа предоставляется через значение JSON в сообщении очереди.

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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"
}

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

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

Push-OutputBinding -Name InputDocumentOut -Value $Document

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB из веб-API. Уникальный идентификатор документа предоставляется через параметр QueryString в HTTP-запросе, как определено в свойстве "Id": "{Query.Id}" привязки.

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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 
}

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

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

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показано, как считывать и обновлять один документ Azure Cosmos DB из веб-API. Уникальный идентификатор документа предоставляется с помощью параметра маршрута. Параметр маршрута определен в свойстве привязки HTTP-запроса и указан в свойстве привязки route Azure Cosmos DB "Id": "{Id}" .

Входная привязка Azure Cosmos DB сначала отображается в списке привязок, найденных в файле конфигурации функции (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 
}

Файл run.ps1 содержит код PowerShell, который считывает входящий документ и выводит изменения.

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

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показано, как считывать несколько документов Azure Cosmos DB. Файл конфигурации функции (function.json) определяет свойства привязки, включающие sqlQuery. Инструкция SQL, предоставляемая в свойство sqlQuery, выбирает набор документов, предоставленных в функцию.

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

Файл run1.ps1 содержит код PowerShell, который считывает входящие документы.

param($QueueItem, $Documents, $TriggerMetadata)

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

В этом разделе содержатся следующие примеры, в которых один документ считывается при указании значения идентификатора из разных источников:

Примеры зависят от того, используется ли модель программирования Python версии 1 или версии 2.

Триггер очереди, поисковый идентификатор из JSON

В следующем примере показана входная привязка Azure Cosmos DB. Функция считывает один документ и обновляет текстовое значение в документе.

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

Триггер HTTP, поисковый идентификатор из строки запроса

В следующем примере показана функция, которая получает один документ. Функция активируется HTTP-запросом, который использует строку запроса, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

В настоящее время нет эквивалентного примера для версии 2.

Триггер HTTP, поисковый идентификатор из данных маршрута

В следующем примере показана функция, которая получает один документ. Функция активируется HTTP-запросом, который использует данные маршрута, чтобы указать идентификатор и значение ключа раздела для поиска. Эти идентификатор и значение ключа раздела используются для получения документа ToDoItem из указанной базы данных и коллекции.

В настоящее время нет эквивалентного примера для версии 2.

Триггер очереди, получение нескольких документов, используется SqlQuery

В следующем примере показана функция входной привязки Python Для Azure Cosmos DB, которая использует привязку. Функция извлекает несколько документов, указанных SQL-запросом, используя триггер очереди для настройки параметров запроса.

Триггер очереди предоставляет параметр departmentId. Сообщение из очереди { "departmentId" : "Finance" } возвратит все записи для финансового отдела.

В настоящее время нет эквивалентного примера для версии 2.

Атрибуты

Библиотеки C# в процессе и изолированном рабочем процессе используют атрибуты для определения функции. Вместо этого скрипт C# использует файл конфигурации function.json, как описано в руководстве по скриптам C#.

Свойство атрибута Description
Соединение Имя параметра или коллекции параметров приложения, указывающих, как подключиться к учетной записи Azure Cosmos DB, к которой отправляются запросы. Дополнительные сведения см. в разделе Соединения.
DatabaseName Имя базы данных Azure Cosmos DB с отслеживаемым контейнером.
Имя контейнера Имя отслеживаемого контейнера.
PartitionKey Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных контейнерах.
Id Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
SqlQuery SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства Id и SqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
PreferredLocations (Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Декораторы

Применяется только к модели программирования Python версии 2.

Функции Python версии 2 определяются с помощью cosmos_db_input декоратора, который поддерживает эти свойства в зависимости от версии расширения:

Свойство Description
arg_name Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
database_name Имя базы данных Azure Cosmos DB с отслеживаемой коллекцией.
container_name Имя отслеживаемой коллекции Azure Cosmos DB.
connection Строка подключения отслеживаемой базы данных Azure Cosmos DB.
partition_key Ключ секции отслеживаемой базы данных Azure Cosmos DB.
id Идентификатор документа, который нужно получить.

Сведения о функциях Python, определенных с помощью function.json, см. в разделе "Конфигурация ".

Заметки

Используйте заметку @CosmosDBInput из библиотеки среды выполнения функций Java для параметров, которые будут выполнять считывание из Azure Cosmos DB. Эта заметка поддерживает следующие свойства:

Настройка

Применяется только к модели программирования Python версии 1.

В следующей таблице описываются свойства, которые можно задать для options объекта, переданного методу input.cosmosDB() . directionСвойства typeи name свойства не применяются к модели версии 4.

В следующей таблице описаны свойства конфигурации привязки, задаваемые в файле function.json, свойства в котором различаются по версии расширения:

Свойство в function.json Описание
type Должен иметь значениеcosmosDB.
direction Должен иметь значениеin.
name Имя переменной, используемое в коде функции, представляющей список документов с изменениями.
Подключение Имя параметра или контейнера параметров приложения, указывающих, как подключиться к отслеживаемой учетной записи Azure Cosmos DB. Дополнительные сведения см. в разделе Соединения.
databaseName Имя базы данных Azure Cosmos DB с отслеживаемым контейнером.
containerName Имя отслеживаемого контейнера.
partitionKey Задает значение ключа секции для поиска. Может включать параметры привязки. Он необходим для поиска в секционированных контейнерах.
id Идентификатор документа, который нужно получить. Это свойство поддерживает выражения привязок. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
sqlQuery SQL-запрос к Azure Cosmos DB, используемый для извлечения нескольких документов. Свойство поддерживает привязки времени выполнения, как показано в примере: SELECT * FROM c where c.departmentId = {departmentId}. Не задавайте свойства id и sqlQuery одновременно. Если не задать ни одного из них, извлекается весь контейнер.
preferredLocations (Необязательно.) Определяет предпочтительные расположения (регионы) для геореплицированных учетных записей базы данных в службе Azure Cosmos DB. Значения должны быть разделены запятыми. Например, East US,South Central US,North Europe.

Подробные примеры см. в разделе Примеры.

Использование

Любые изменения, внесенные во входной документ, сохраняются автоматически после успешного выхода из функции.

Тип параметра, поддерживаемый входной привязкой Cosmos DB, зависит от версии среды выполнения Функций, версии пакета расширения и используемой модальности C#.

Если требуется, чтобы функция обрабатывала один документ, входная привязка Cosmos DB может привязаться к следующим типам:

Тип Описание
Сериализуемые в JSON типы Функции пытаются десериализировать данные JSON документа в обычный тип объекта CLR (POCO).

Если требуется, чтобы функция обрабатывала несколько документов из запроса, входная привязка Cosmos DB может привязаться к следующим типам:

Тип Описание
IEnumerable<T>где T является сериализуемым типом JSON Перечисление сущностей, возвращаемых запросом. Каждая запись представляет один документ.
CosmosClient1 Клиент, подключенный к учетной записи Cosmos DB.
База данных1 Клиент, подключенный к базе данных Cosmos DB.
Контейнер1 Клиент, подключенный к контейнеру Cosmos DB.

1 Для использования этих типов необходимо ссылаться на Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 или более поздней версии , а также общие зависимости для привязок типов SDK.

Из библиотеки среды выполнения функций Java заметка @CosmosDBInput предоставляет данные Azure Cosmos DB функции. Эта заметка может использоваться с собственными типами Java, объектами POJO или значениями, допускающими значения NULL, используя Optional<T>.

Доступ к документу с помощью context.extraInputs.get().

При выходе функции не происходит автоматического обновления документов. Для обновления документов в функции используйте выходную привязку. Дополнительные сведения см. в примере PowerShell.

Данные становятся доступными для функции через параметр DocumentList. Изменения, вносимые в документ, не сохраняются автоматически.

Связи

Свойства connectionStringSetting/connection и leaseConnectionStringSetting/leaseConnection являются ссылками на конфигурацию среды, которая указывает, как приложение должно подключаться к Azure Cosmos DB. В них может быть указано следующее:

Если настроенное значение одновременно точно соответствует одному параметру и является префиксом для других параметров, то используется точное совпадение.

Connection string

Строка подключения для учетной записи базы данных должна храниться в параметре приложения с именем, соответствующим значению, которое указано свойством подключения конфигурации привязки.

Подключения на основе удостоверений

Если вы используете расширение версии 4.x или более поздней версии, вместо использования строка подключения с секретом, приложение может использовать удостоверение Microsoft Entra. Для этого необходимо определить параметры с общим префиксом, который соответствует свойству подключения в конфигурации триггера и привязки.

В этом режиме для расширения требуются следующие свойства:

Свойство Шаблон переменной среды Description Пример значения
Конечная точка учетной записи <CONNECTION_NAME_PREFIX>__accountEndpoint URI конечной точки учетной записи Azure Cosmos DB. https://<database_account_name>.documents.azure.com:443/

Для настройки подключения можно задать дополнительные свойства. См. раздел Общие свойства подключений на основе удостоверений.

При размещении в службе "Функции Azure" для подключений на основе удостоверений используется управляемое удостоверение. По умолчанию используется назначаемое системой удостоверение, однако вы можете указать назначаемое пользователем удостоверение с помощью свойств credential и clientID. Обратите внимание, что настройка назначаемого пользователем удостоверения с идентификатором ресурса не поддерживается. При выполнении в других контекстах, например при локальной разработке, вместо этого используется удостоверение разработчика, хотя это можно настроить. См. раздел Локальная разработка с использованием подключений на основе удостоверений.

Предоставление разрешения удостоверению

Любое используемое удостоверение должно иметь разрешения на выполнение предполагаемых действий. Для большинства служб Azure это означает, что необходимо назначить роль в Azure RBAC, используя встроенные или настраиваемые роли, которые предоставляют эти разрешения.

Внимание

Иногда целевая служба может предоставлять разрешения, которые не являются обязательными для всех контекстов. Там, где это возможно, придерживайтесь принципа минимальных привилегий, предоставляя удостоверению лишь самые необходимые привилегии. Например, если приложению требуется только возможность чтения из источника данных, используйте роль, которая имеет разрешение только на чтение. Было бы неуместным назначить роль, которая также разрешает запись в эту службу, так как это разрешение не требуется для операции чтения. Соответственно необходимо еще проверить, что область действия назначенной роли ограничена только теми ресурсами, которые необходимо прочитать.

Cosmos DB не использует Azure RBAC для операций с данными. Вместо этого она использует встроенную систему RBAC Cosmos DB, созданную на основе аналогичных концепций. Вам потребуется создать назначение ролей, которое предоставляет доступ к учетной записи базы данных во время выполнения. Роли управления Azure RBAC, такие как владелец , недостаточно. В следующей таблице показаны встроенные роли, которые рекомендуется использовать при использовании расширения Azure Cosmos DB в обычной работе. Приложению могут потребоваться дополнительные разрешения в зависимости от написанного кода.

Тип привязки Пример встроенных ролей1
Триггер2 Встроенный участник данных Cosmos DB
Входные привязки Встроенное средство чтения данных Cosmos DB
Выходные привязки Встроенный участник данных Cosmos DB

1 Эти роли нельзя использовать в назначении ролей RBAC Azure. Дополнительные сведения о назначении этих ролей см. в встроенной системной документации по RBAC Cosmos DB.

2 При использовании удостоверения Cosmos DB обрабатывает создание контейнера как операцию управления. Он недоступен в качестве операции плоскости данных для триггера. Перед настройкой функции необходимо создать контейнеры, необходимые триггеру (включая контейнер аренды).

Следующие шаги