你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 触发器和绑定概述

项目
11/23/2023

此系列文章介绍如何在 Azure Functions 2.x 及更高版本中使用 Azure Cosmos DB 绑定。 Azure Functions 支持 Azure Cosmos DB 的触发器、输入和输出绑定。

操作	类型
创建或修改 Azure Cosmos DB 文档时运行函数	触发器
读取 Azure Cosmos DB 文档	输入绑定
保存对 Azure Cosmos DB 文档的更改	输出绑定

注意

此参考适用于 Azure Functions 2.x 及更高版本。若要了解如何在 Functions 1.x 中使用这些绑定，请参阅适用于 Azure Functions 1.x 的 Azure Cosmos DB 绑定。

此绑定最初名为 DocumentDB。在 Azure Functions 2.x 及更高版本中，触发器、绑定和包均称为 Azure Cosmos DB。

受支持的 API

仅支持将 Azure Cosmos DB 绑定与 Azure Cosmos DB for NoSQL 配合使用。从扩展 5.x 开始，通过使用表存储绑定来提供对 Azure Cosmos DB for Table 的支持。对于所有其他的 Azure Cosmos DB API，应使用适用于 API 的静态客户端通过函数来访问数据库。API 包括 Azure Cosmos DB for MongoDB、Azure Cosmos DB for Cassandra 和 Azure Cosmos DB for Apache Gremlin。

安装扩展

你安装的扩展 NuGet 包取决于你在函数应用中使用的 C# 模式：

独立工作模型
进程模型

函数在独立的 C# 工作进程中执行。若要了解详细信息，请参阅有关在独立工作进程中运行 C# Azure Functions 的指南。

安装扩展的过程因扩展版本的不同而异：

本节介绍如何使用类库。对于 C# 脚本，需要改为安装扩展捆绑包版本 4.x。

此版 Azure Cosmos DB 绑定扩展引入了使用标识而不是机密进行连接的功能。有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

此版本还会更改你可绑定到的类型，并将 v2 SDK Microsoft.Azure.DocumentDB 中的类型替换为 v3 SDK Microsoft.Azure.Cosmos 中更新的类型。通过 SDK 迁移指南、触发器、输入绑定和输出绑定示例，详细了解这些新类型在哪些方面有变化以及如何迁移到这些新类型。

此扩展版本以 NuGet 包 4.x 版的形式提供。

通过安装 NuGet 包 4.x 版将扩展添加到项目。

如果要使用 F# 编写应用程序，则还必须将此扩展配置为应用的启动配置的一部分。在对 ConfigureFunctionsWorkerDefaults() 或 ConfigureFunctionsWebApplication() 的调用中，添加接受 IFunctionsWorkerApplication 参数的委托。然后在该委托的正文中，在对象上调用 ConfigureCosmosDBExtension()：

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

安装捆绑包

Azure Cosmos DB 绑定扩展是在 host.json 项目文件中指定的扩展捆绑包的一部分。你可能需要修改此捆绑包以更改绑定的版本，或者如果尚未安装捆绑包。若要了解详细信息，请参阅扩展捆绑包。

由于 Azure Cosmos DB SDK 中的架构发生更改，Azure Cosmos DB 扩展的 4.x 版需要适用于 Java 函数的 azure-functions-java-library V3.0.0。

捆绑包 v4.x
捆绑包 v2.x 和 v3.x

这个版本的捆绑包包含 Azure Cosmos DB 绑定扩展 4.x 版，该扩展引入了使用标识而不是机密进行连接的功能。有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。

可以通过在 host.json 文件中添加或替换以下代码，从预览版扩展捆绑包 v4 添加此扩展版本：

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.0.0, 5.0.0)"
  }
}

若要了解详细信息，请参阅更新扩展。

可以通过注册扩展捆绑包版本 2.x 或 3.x 在函数应用中安装此版本的扩展。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

绑定类型

.NET 支持的绑定类型取决于扩展版本和 C# 执行模式，可以是以下类型之一：

独立工作模型
进程模型

独立工作进程类库的已编译 C# 函数在独立于运行时的进程中运行。

请选择一个版本来查看模式和版本的绑定类型详细信息。

Azure Cosmos DB 扩展支持下表所示的参数类型。

绑定方案	参数类型
Cosmos DB 触发器（单个文档）	JSON 可序列化类型¹
Cosmos DB 触发器（批文档）	`IEnumerable<T>`，其中 `T` 是 JSON 可序列化类型¹
Cosmos DB 输入（单个文档）	JSON 可序列化类型¹
Cosmos DB 输入（返回多个文档的查询）	CosmosClient `IEnumerable<T>`，其中 `T` 是 JSON 可序列化类型¹
Cosmos DB 输出（单个文档）	JSON 可序列化类型¹
Cosmos DB 输出（多个文档）	`ICollector<T>` 或 `IAsyncCollector<T>`，其中 `T` 是 JSON 可序列化类型¹

¹ 包含 JSON 数据的文档可以反序列化为已知的普通旧 CLR 对象 (POCO) 类型。

独立工作进程支持下表所示的参数类型。支持在预览中绑定到 Microsoft.Azure.Cosmos 中的类型。

Cosmos DB 触发器

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

类型	说明
JSON 可序列化类型	函数尝试将文档的 JSON 数据从 Cosmos DB 更改源反序列化为普通的旧 CLR 对象 (POCO) 类型。

如果你希望函数处理一批文档，可将 Cosmos DB 触发器绑定到以下类型：

类型	说明
`IEnumerable<T>`，其中 `T` 是 JSON 序列化的类型	批处理中包含的实体的枚举。每个条目表示 Cosmos DB 更改源中的一个文档。

Cosmos DB 输入绑定

如果你希望函数处理单个文档，可将 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 类型绑定的常见依赖项。

Cosmos DB 输出绑定

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

类型	说明
JSON 可序列化类型	表示文档的 JSON 内容的对象。函数尝试将普通的旧 CLR 对象 (POCO) 类型序列化为 JSON 数据。

如果希望函数写入多个文档，Cosmos DB 输出绑定可以绑定到以下类型：

类型	说明
`T[]`，其中 `T` 是 JSON 可序列化类型	包含多个事件的数组。每个条目表示一个事件。

对于其他输出方案，请直接从 Microsoft.Azure.Cosmos 创建和使用类型。

异常和返回代码

绑定	参考
Azure Cosmos DB	Azure Cosmos DB 的 HTTP 状态代码

host.json 设置

本部分介绍版本 2.x 及更高版本中可用于此绑定的配置设置。 host.json 文件中的设置将应用于函数应用实例中的所有函数。下面的示例 host.json 文件仅包含此绑定的 2.x 版及更高版本设置。若要详细了解版本 2.x 及更高版本中的函数应用程序配置设置，请参阅 Azure Functions 的 host.json 参考。

扩展 4.x+
Functions 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

属性	默认	说明
connectionMode	`Gateway`	连接到 Azure Cosmos DB 服务时该函数使用的连接模式。选项为 `Direct` 和 `Gateway`
userAgentSuffix	不适用	将指定的字符串值添加到由触发器发出的所有请求，或将其绑定到服务。这样，你便可以更轻松地根据特定的函数应用跟踪 Azure Monitor 中的活动，并按 `User Agent` 对其进行筛选。

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

属性	默认	说明
connectionMode	`Gateway`	连接到 Azure Cosmos DB 服务时该函数使用的连接模式。选项为 `Direct` 和 `Gateway`
protocol	`Https`	连接到 Azure Cosmos DB 服务时该函数使用的连接协议。请参阅此文，了解两种模式的说明。
leasePrefix	不适用	应用中所有函数要使用的租用前缀。