适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 输入绑定

Azure Cosmos DB 输入绑定会使用 SQL API 检索一个或多个 Azure Cosmos DB 文档，并将其传递给函数的输入参数。可根据调用函数的触发器确定文档 ID 或查询参数。

有关设置和配置详细信息，请参阅概述。

注意

当集合已分区时，查找操作还必须指定分区键值。

重要

本文使用选项卡来支持多个版本的 Node.js 编程模型。 v4 模型已正式发布，旨在为 JavaScript 和 TypeScript 开发人员提供更为灵活和直观的体验。有关 v4 模型工作原理的更多详细信息，请参阅 Azure Functions Node.js 开发人员指南。要详细了解 v3 和 v4 之间的差异，请参阅迁移指南。

Azure Functions 支持两种 Python 编程模型。定义绑定的方式取决于选择的编程模型。

使用 Python v2 编程模型，可以直接在 Python 函数代码中使用修饰器定义绑定。有关详细信息，请参阅 Python 开发人员指南。

本文同时支持两个编程模型。

示例

除非另有说明，否则本文中的示例针对的都是 Azure Cosmos DB 扩展的版本 3.x。若要与扩展版本 4.x 一起使用，需要将 collection 属性和属性名称中的字符串替换为 container。

可使用以下 C# 模式之一来创建 C# 函数：

独立辅助角色模型：编译的 C# 函数，该函数在独立于运行时的工作进程中运行。需要独立工作进程才能支持在 LTS 和非 LTS 版 .NET 和 .NET Framework 上运行的 C# 函数。独立工作进程函数的扩展使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空间。
进程内模型：编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。在此模型的变体中，可以使用 C# 脚本运行 Functions，该脚本主要用于 C# 门户编辑。进程内函数的扩展使用 Microsoft.Azure.WebJobs.Extensions.* 命名空间。

重要

对进程内模型的支持将于 2026 年 11 月 10 日结束。为获得完全支持，强烈建议将应用迁移到独立工作模型。

独立工作模型
进程模型

本部分包含需要 3.x 版 Azure Cosmos DB 扩展和 5.x 版 Azure 存储扩展的示例。如果你的函数应用中尚不存在对以下 NuGet 包的引用，请添加它们：

这些示例引用简单的 ToDoItem 类型：

队列触发器，从 JSON 查找 ID

以下示例显示了一个检索单个文档的函数。该函数由存储队列中的 JSON 消息触发。队列触发器将 JSON 分析为 ToDoItemLookup 类型的对象，其中包含要检索的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中返回一个 ToDoItem 文档。

本部分包含的以下示例演示如何将进程内 C# 类库函数与扩展版本 3.x 配合使用：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 获取多个文档
HTTP 触发器，使用 DocumentClient 获取多个文档
HTTP 触发器，使用 CosmosClient（v4 扩展）获取多个文档

这些示例引用简单的 ToDoItem 类型：

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        [JsonProperty("id")]
        public string Id { get; set; }

        [JsonProperty("partitionKey")]
        public string PartitionKey { get; set; }

        public string Description { get; set; }
    }
}

队列触发器，从 JSON 查找 ID

以下示例演示检索单个文档的 C# 函数。该函数由包含 JSON 对象的队列消息触发。队列触发器将 JSON 分析为 ToDoItemLookup 类型的对象，其中包含要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

namespace CosmosDBSamplesV2
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }

        public string ToDoItemPartitionKeyValue { get; set; }
    }
}

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

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}",
                PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

HTTP 触发器，从查询字符串查找 ID

以下示例演示检索单个文档的 C# 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

注意

HTTP 查询字符串参数区分大小写。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}",
                PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

HTTP 触发器，从路由数据查找 ID

以下示例演示检索单个文档的 C# 函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}",
                PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

HTTP 触发器，使用 SqlQuery 从路由数据查找 ID

以下示例演示检索单个文档的 C# 函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID。该 ID 用于从指定的数据库和集合检索 ToDoItem 文档。

以下示例演示如何在 SqlQuery 参数中使用绑定表达式。可以将路由数据传递至所示的 SqlQuery 参数，但目前无法传递查询字符串值。

注意

如果需要仅按 ID 进行查询，建议使用查找（如前面的示例），因为它消耗的请求单位更少。点读取操作 (GET) 比按 ID 进行的查询更高效。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequest req,
            [CosmosDB("ToDoItems", "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

HTTP 触发器，使用 SqlQuery 获取多个文档

以下示例演示检索文档列表的 C# 函数。此函数由 HTTP 请求触发。此查询在 SqlQuery 特性属性中指定。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

HTTP 触发器，使用 DocumentClient 获取多个文档

以下示例演示检索文档列表的 C# 函数。此函数由 HTTP 请求触发。此代码使用 Azure Cosmos DB 绑定提供的 DocumentClient 实例来读取文档列表。 DocumentClient 实例也可用于写入操作。

注意

还可以使用 IDocumentClient 接口来简化测试。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"];
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");

            log.LogInformation($"Searching for: {searchterm}");

            IDocumentQuery<ToDoItem> query = client.CreateDocumentQuery<ToDoItem>(collectionUri)
                .Where(p => p.Description.Contains(searchterm))
                .AsDocumentQuery();

            while (query.HasMoreResults)
            {
                foreach (ToDoItem result in await query.ExecuteNextAsync())
                {
                    log.LogInformation(result.Description);
                }
            }
            return new OkResult();
        }
    }
}

HTTP 触发器，使用 CosmosClient 获取多个文档

以下示例演示检索文档列表的 C# 函数。此函数由 HTTP 请求触发。此代码使用 Azure Cosmos DB 绑定（在CosmosClient 中提供）提供的实例来读取文档列表。 CosmosClient 实例也可用于写入操作。

using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingCosmosClient
    {  
        [FunctionName("DocsByUsingCosmosClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")] CosmosClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"].ToString();
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Container container = client.GetDatabase("ToDoItems").GetContainer("Items");

            log.LogInformation($"Searching for: {searchterm}");

            QueryDefinition queryDefinition = new QueryDefinition(
                "SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
                .WithParameter("@searchterm", searchterm);
            using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
            {
                while (resultSet.HasMoreResults)
                {
                    FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
                    ToDoItem item = response.First();
                    log.LogInformation(item.Description);
                }
            }

            return new OkResult();
        }
    }
}

本部分包含以下示例：

HTTP 触发器，从查询字符串查找 ID - 字符串参数
HTTP 触发器，从查询字符串查找 ID - POJO 参数
HTTP 触发器，从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据获取多个文档（C# 脚本）

这些示例引用简单的 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 触发器，从查询字符串查找 ID - 字符串参数

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于以字符串形式从指定的数据库和集合中检索文档。

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 函数运行时库中，对其值将来自 Azure Cosmos DB 的函数参数使用 @CosmosDBInput 注释。可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

HTTP 触发器，从查询字符串查找 ID - POJO 参数

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索文档。然后将该文档转换为先前创建的 ToDoItem POJO 实例，并作为参数传递给该函数。

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 触发器，从路由数据查找 ID

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的路由参数用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索文档，将它作为 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 从路由数据查找 ID

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用路由参数指定要查找的 ID。该 ID 用于从指定的数据库和集合中检索文档，将结果集转换为 ToDoItem[]，因为可能会返回许多文档，具体取决于查询条件。

注意

如果需要仅按 ID 进行查询，建议使用查找（如前面的示例），因为它消耗的请求单位更少。点读取操作 (GET) 比按 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();
        }
    }
}

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

此部分包含的以下示例可以通过指定各种源提供的 ID 值来读取单个文档：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

下面的示例演示 TypeScript 函数，该函数读取单个文档并更新文档的文本值。

模型 v4
模型 v3

HTTP 触发器，从查询字符串查找 ID

以下示例演示检索单个文档的 TypeScript 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

模型 v4
模型 v3

HTTP 触发器，从路由数据查找 ID

以下示例演示检索单个文档的 TypeScript 函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

模型 v4
模型 v3

队列触发器，使用 SqlQuery 获取多个文档

以下示例演示了一个 TypeScript 函数，该函数使用队列触发器来自定义查询参数，以检索 SQL 查询指定的多个文档。

队列触发器提供参数 departmentId。 { "departmentId" : "Finance" } 的队列消息将返回财务部的所有记录。

模型 v4
模型 v3

此部分包含的以下示例可以通过指定各种源提供的 ID 值来读取单个文档：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

以下示例演示了一个 JavaScript 函数，该函数读取单个文档并更新文档的文本值。

模型 v4
模型 v3

下面是 function.json 文件中的绑定数据：

{
    "name": "inputDocumentIn",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

HTTP 触发器，从查询字符串查找 ID

以下示例演示检索单个文档的 JavaScript 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

模型 v4
模型 v3

function.json 文件如下所示：

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

JavaScript 代码如下所示：

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

HTTP 触发器，从路由数据查找 ID

以下示例演示检索单个文档的 JavaScript 函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

模型 v4
模型 v3

function.json 文件如下所示：

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

JavaScript 代码如下所示：

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

队列触发器，使用 SqlQuery 获取多个文档

以下示例演示了一个 JavaScript 函数，该函数使用队列触发器自定义查询参数来检索 SQL 查询指定的多个文档。

队列触发器提供参数 departmentId。 { "departmentId" : "Finance" } 的队列消息将返回财务部的所有记录。

模型 v4
模型 v3

下面是 function.json 文件中的绑定数据：

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

配置部分解释了这些属性。

JavaScript 代码如下所示：

module.exports = async function (context, input) {
  var documents = context.bindings.documents;
  for (const document of documents) {
    // operate on each document
  }
};

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

下面的示例演示如何读取和更新单个 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 触发器，从查询字符串查找 ID

下面的示例演示如何通过 Web API 读取和更新单个 Azure Cosmos DB 文档。文档的唯一标识符通过 HTTP 请求中的 querystring 参数提供，如绑定的 "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 触发器，从路由数据查找 ID

下面的示例演示如何通过 Web API 读取和更新单个 Azure Cosmos DB 文档。文档的唯一标识符通过 route 参数提供。 route 参数在 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 的绑定属性。提供给 sqlQuery 属性的 SQL 语句选择提供给函数的文档集。

{ 
  "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 
}

此部分包含的以下示例可以通过指定各种源提供的 ID 值来读取单个文档：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
队列触发器，使用 SqlQuery 获取多个文档

示例取决于使用的是 v1 还是 v2 Python 编程模型。

为 Cosmos DB 使用 SDK-Type 绑定（预览版）

此示例使用 SDK 类型直接访问 Cosmos DB 输入绑定提供的基础 CosmosClient 对象：

该函数遍历所有数据库并记录其 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"

有关使用其他 SDK 类型的示例，请参阅 ContainerProxy 和 DatabaseProxy 示例。有关如何在函数应用中包括 SDK 类型绑定的分步教程，请遵循适用于 CosmosDB 的 Python SDK 绑定示例。

若要了解详细信息，包括支持其他 SDK 类型绑定的内容，请参阅 SDK 类型绑定。

队列触发器，从 JSON 查找 ID

以下示例演示了 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]):
     doc = inputDocument[0]
     doc["text"] = "This was updated!"
     outputDocument.set(doc)
     print(f"Updated document.")

下面是 function.json 文件中的绑定数据：

{
    "name": "documents",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "$return",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

配置部分解释了这些属性。

下面是 Python 代码：

import azure.functions as func

def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Document:
    if documents:
        document = documents[0]
        document['text'] = 'This was updated!'
        return document

HTTP 触发器，从查询字符串查找 ID

以下示例显示了一个检索单个文档的函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

目前没有 v2 的等效样本。

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "scriptFile": "__init__.py"
}

下面是 Python 代码：

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])

    return 'OK'

HTTP 触发器，从路由数据查找 ID

以下示例显示了一个检索单个文档的函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

目前没有 v2 的等效样本。

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "disabled": false,
  "scriptFile": "__init__.py"
}

下面是 Python 代码：

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])
    return 'OK'

队列触发器，使用 SqlQuery 获取多个文档

以下示例显示了使用绑定的 Azure Cosmos DB 输入绑定 Python 函数。该函数使用队列触发器自定义查询参数检索 SQL 查询指定的多个文档。

队列触发器提供参数 departmentId。 { "departmentId" : "Finance" } 的队列消息将返回财务部的所有记录。

目前没有 v2 的等效样本。

下面是 function.json 文件中的绑定数据：

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

特性

进程内和独立工作进程 C# 库使用特性来定义函数。 C# 脚本改用 function.json 配置文件，如 C# 脚本指南中所述。

Attribute 属性	说明
连接	应用设置或设置集合的名称，用于指定如何连接到所查询的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
数据库名称	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
ContainerName	要监视的容器的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

Attribute 属性	说明
ConnectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
数据库名称	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
CollectionName	受监视的集合的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，“中国北部,中国北部,中国北部”。

Attribute 属性	说明
连接	应用设置或设置集合的名称，用于指定如何连接到所查询的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
数据库名称	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
ContainerName	要监视的容器的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

Attribute 属性	说明
ConnectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
数据库名称	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
CollectionName	受监视的集合的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，“中国北部,中国北部,中国北部”。

修饰符

仅适用于 Python v2 编程模型。

Python v2 函数可使用 cosmos_db_input 修饰器定义，该修饰器支持以下属性，具体取决于扩展版本：

扩展 4.x+
函数 2.x+

properties	说明
`arg_name`	函数代码中使用的变量名称，表示发生更改的文档列表。
`database_name`	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
`container_name`	受到监视的 Azure Cosmos DB 集合的名称。
`connection`	受到监视的 Azure Cosmos DB 的连接字符串。
`partition_key`	正在监视的 Azure Cosmos DB 的分区键。
`id`	要检索的文档的 ID。

properties	说明
`arg_name`	函数代码中使用的变量名称，表示发生更改的文档列表。
`database_name`	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
`collection_name`	受到监视的 Azure Cosmos DB 集合的名称。
`connection_string_setting`	受到监视的 Azure Cosmos DB 的连接字符串。
`partition_key`	正在监视的 Azure Cosmos DB 的分区键。
`id`	要检索的文档的 ID。

对于使用 function.json 定义的 Python 函数，请参阅“配置”部分。

批注

在 Java 函数运行时库中，对从 Azure Cosmos DB 读取数据的参数使用 @CosmosDBInput 注释。此注释支持以下属性：

配置

仅适用于 Python v1 编程模型。

模型 v4
模型 v3

下表说明了可以在传递给方法“options”的对象“input.cosmosDB()”上设置的属性。 type、direction 和 name 属性不适用于 v4 模型。

下表解释了在 function.json 文件中设置的绑定配置属性，其中属性因扩展版本而异。

扩展 4.x+
函数 2.x+

function.json 属性	说明
类型	必须设置为 `cosmosDB`。
方向	必须设置为 `in`。
名字	函数代码中使用的变量名称，表示发生更改的文档列表。
连接	应用设置或设置容器的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
containerName	要监视的容器的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China East,China North,China North 2`。

function.json 属性	说明
类型	必须设置为 `cosmosDBTrigger`。
方向	必须设置为 `in`。
名字	函数代码中使用的变量名称，表示发生更改的文档列表。
connectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName	受监视的集合的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

有关完整示例的信息，请参阅示例部分。

使用情况

函数成功退出时，对输入文档所做的任何更改都会自动保存。

Cosmos DB 输入绑定支持的参数类型取决于所用的 Functions 运行时版本、扩展包版本以及 C# 模态。

如果你希望函数处理单个文档，可将 Cosmos DB 输入绑定绑到以下类型：

类型	说明
JSON 可序列化类型	Functions 会尝试将文档的 JSON 数据反序列化为普通的旧 CLR 对象 (POCO) 类型。

如果你希望函数处理查询中的多个文档，可将 Cosmos DB 输入绑定绑到以下类型：

类型	说明
`IEnumerable<T>`，其中 `T` 是 JSON 序列化的类型	查询返回的实体的枚举。每个条目表示一个事件。
CosmosClient¹	连接到 Cosmos DB 帐户的客户端。
数据库¹	连接到 Cosmos DB 数据库的客户端。
容器¹	连接到 Cosmos DB 容器的客户端。

¹ 若要使用这些类型，需要引用 Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 或更高版本以及 SDK 类型绑定的常见依赖项。

在 Java 函数运行时库中，@CosmosDBInput 注释向函数公开 Azure Cosmos DB 数据。可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

模型 v4
模型 v3

使用 context.extraInputs.get() 访问文档。

函数退出时不会自动对文档进行更新。若要在函数中更新文档，请使用输出绑定。有关更多详细信息，请参阅 PowerShell 示例。

数据通过 DocumentList 参数提供给函数。不会自动保留对文档所做的更改。 Functions 还支持适用于 Azure Cosmos 的 Python SDK 类型绑定，该绑定允许使用以下基础 SDK 类型处理数据：

重要

Python 的 CosmosDB SDK 类型支持为预览版，并且仅支持 Python v2 编程模型。有关详细信息，请参阅 Python 中的 SDK 类型。

连接

connection和leaseConnection属性在应用设置中设置为键，返回函数运行时用于连接Azure Cosmos DB账户端点的数值。这些属性设置的价值取决于连接类型：

管理身份连接：该 connection 属性是由 <CONNECTION_NAME_PREFIX> 一组设置共享的，这些设置共同定义了基于身份的账户连接。更多信息请参见定义身份连接。
密钥保管库引用：connection属性设置返回一个 Azure 密钥保管库引用，指向该连接字符串中心维护的位置。更多信息请参见定义密钥保管库连接。
App Configuration 引用：connection属性设置返回一个 Azure 应用程序配置引用，返回一个连接字符串或密钥保管库引用。更多信息请参见连接文章中的 Azure 应用程序配置。
Connection string：属性设置返回connection实际账户的连接字符串。由于连接字符串包含共享的秘密密钥，你应尽量考虑使用管理身份连接。更多信息请参见定义连接。

欲了解更多关于绑定连接的信息，请参见 Azure Functions 中的 Manage connection 。要获取连接字符串，请进入你的Azure Cosmos DB账户，选择Keys，然后复制PRIMARY CONNECTION STRING或SECONDARY CONNECTION STRING的值。这些连接字符串包含共享的秘密密钥，必须保持安全。

在扩展的早期版本中，连接性质被命名为 connectionStringSetting 和 leaseConnectionStringSetting。

后续步骤

Last updated on 2026-08-13

适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 输入绑定

示例

队列触发器，从 JSON 查找 ID

HTTP 触发器，从查询字符串查找 ID - 字符串参数

HTTP 触发器，从查询字符串查找 ID - POJO 参数

HTTP 触发器，从路由数据查找 ID

HTTP 触发器，使用 SqlQuery 从路由数据查找 ID

HTTP 触发器，使用 SqlQuery 从路由数据获取多个文档

队列触发器，从 JSON 查找 ID

HTTP 触发器，从查询字符串查找 ID

HTTP 触发器，从路由数据查找 ID

队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

HTTP 触发器，从查询字符串查找 ID

HTTP 触发器，从路由数据查找 ID

队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

HTTP 触发器，从查询字符串查找 ID

HTTP 触发器，从路由数据查找 ID

队列触发器，使用 SqlQuery 获取多个文档

为 Cosmos DB 使用 SDK-Type 绑定（预览版）

队列触发器，从 JSON 查找 ID

HTTP 触发器，从查询字符串查找 ID

HTTP 触发器，从路由数据查找 ID

队列触发器，使用 SqlQuery 获取多个文档

特性

修饰符

批注

配置

使用情况

连接

后续步骤

其他資源