适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 触发器和绑定概述
此系列文章介绍如何在 Azure Functions 2.x 及更高版本中使用 Azure Cosmos DB 绑定。 Azure Functions 支持 Azure Cosmos DB 的触发器、输入和输出绑定。
| 操作 |
类型 |
| 创建或修改 Azure Cosmos DB 文档时运行函数 |
触发器 |
| 读取 Azure Cosmos DB 文档 |
输入绑定 |
| 保存对 Azure Cosmos DB 文档的更改 |
输出绑定 |
仅支持将 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# 模式：
安装扩展的过程因扩展版本的不同而异：
此版 Azure Cosmos DB 绑定扩展引入了使用标识而不是机密进行连接的功能。 有关使用托管标识配置函数应用的教程，请参阅使用基于标识的连接创建函数应用教程。
通过安装 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 绑定扩展 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# 函数在独立于运行时的进程中运行。
进程内类库是编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。
请选择一个版本来查看模式和版本的绑定类型详细信息。
Azure Cosmos DB 扩展支持下表所示的参数类型。
| 绑定方案 |
参数类型 |
| Cosmos DB 触发器（单个文档） |
JSON 可序列化类型1 |
| Cosmos DB 触发器（批文档） |
IEnumerable<T>，其中 T 是 JSON 可序列化类型1 |
| Cosmos DB 输入（单个文档） |
JSON 可序列化类型1
|
| Cosmos DB 输入（返回多个文档的查询） |
CosmosClient
IEnumerable<T>，其中 T 是 JSON 可序列化类型1 |
| Cosmos DB 输出（单个文档） |
JSON 可序列化类型1 |
| Cosmos DB 输出（多个文档） |
ICollector<T> 或 IAsyncCollector<T>，其中 T 是 JSON 可序列化类型1 |
1 包含 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 |
（预览版1）
连接到 Cosmos DB 帐户的客户端。 |
| Database |
（预览版1）
连接到 Cosmos DB 数据库的客户端。 |
| 容器 |
（预览版1）
连接到 Cosmos DB 容器的客户端。 |
1 若要使用这些类型，需要引用 Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.3.1-preview1 或更高版本以及 SDK 类型绑定的常见依赖项。
Cosmos DB 输出绑定
如果希望函数写入单个文档，Cosmos DB 输出绑定可以绑定到以下类型：
| 类型 |
说明 |
| JSON 可序列化类型 |
表示文档的 JSON 内容的对象。 函数尝试将普通的旧 CLR 对象 (POCO) 类型序列化为 JSON 数据。 |
如果希望函数写入多个文档，Cosmos DB 输出绑定可以绑定到以下类型：
| 类型 |
说明 |
T[]，其中 T 是 JSON 可序列化类型 |
包含多个事件的数组。 每个条目表示一个事件。 |
对于其他输出方案，请直接从 Microsoft.Azure.Cosmos 创建和使用类型。
独立工作进程中早期版本的扩展仅支持绑定到可 JSON 序列化类型。 扩展 4.x 及更高版本可以使用其他选项。
本部分介绍版本 2.x 及更高版本中可用于此绑定的配置设置。 host.json 文件中的设置将应用于函数应用实例中的所有函数。 下面的示例 host.json 文件仅包含此绑定的 2.x 版及更高版本设置。 若要详细了解版本 2.x 及更高版本中的函数应用程序配置设置，请参阅 Azure Functions 的 host.json 参考。
{
"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 |
不适用 |
应用中所有函数要使用的租用前缀。 |