通过

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

Azure Functions 的 Azure Cosmos DB 触发器和绑定概述

这组文章介绍如何在 Azure Functions 中使用 Azure Cosmos DB 绑定。 Azure Functions 支持 Azure Cosmos DB 的触发器、输入和输出绑定。

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

重要

此版本的 Azure Cosmos DB 绑定扩展支持 Azure Functions 版本 4.x。 如果应用仍使用 Functions 运行时版本 1.x，请参阅 适用于 Azure Functions 1.x 的 Azure Cosmos DB 绑定。 在 Functions v1.x 运行时中，此绑定最初命名 DocumentDB。

受支持的 API

此表指示如何从函数代码连接到各种 Azure Cosmos DB API：

API 建议
用于 NoSQL 的 Azure Cosmos DB 使用 Azure Cosmos DB 绑定扩展
用于 MongoDB 的 Azure Cosmos DB （vCore） 使用 Azure Cosmos DB for MongoDB 绑定扩展，该扩展目前以预览版提供。
用于表的 Azure Cosmos DB 使用 Azure 表绑定扩展版本 5.x 或更高版本。
适用于 Apache Cassandra 的 Azure Cosmos DB 使用本机客户端 SDK。
用于 Apache Gremlin 的 Azure Cosmos DB （图形 API） 使用本机客户端 SDK
Azure Cosmos DB for PostgreSQL 使用本机客户端 SDK。

安装扩展

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

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

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

此版 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

安装捆绑包

若要能够在应用中使用此绑定扩展，请确保项目的根目录中 host.json 文件包含以下 extensionBundle 引用：

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

在此示例中，version[4.0.0, 5.0.0)值指示 Functions 主机使用至少4.0.0小于但小于5.0.0的捆绑包版本，其中包括所有可能的 4.x 版本。 此表示法有效地在 v4.x 扩展捆绑包的最新可用次要版本上维护应用。

如果可能，应使用最新的扩展捆绑包主版本，并允许运行时自动维护最新的次要版本。 可以在 扩展捆绑包发布页上查看最新捆绑包的内容。 有关详细信息，请参阅 Azure Functions 扩展捆绑包。

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

绑定类型

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

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

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

独立工作进程支持下表所示的参数类型。 支持在预览中绑定到 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 序列化的类型 查询返回的实体的枚举。 每个条目表示一个事件。
CosmosClient1 连接到 Cosmos DB 帐户的客户端。
数据库1 连接到 Cosmos DB 数据库的客户端。
容器1 连接到 Cosmos DB 容器的客户端。

1 若要使用这些类型，需要引用 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 创建 CosmosClient 并将其用于其他类型。 有关使用依赖项注入从 Azure SDK 创建客户端类型的示例，请参阅 “注册 Azure 客户端 ”。

SDK 绑定类型

Azure Cosmos 的 SDK 类型支持为预览版。 按照 适用于 CosmosDB 的 Python SDK 绑定示例 开始使用 Python 中的适用于 Cosmos 的 SDK 类型。

重要

使用 SDK 类型绑定需要 Python v2 编程模型。

绑定 参数类型 示例
CosmosDB 输入 ContainerProxy、
CosmosClient，
DatabaseProxy
 ContainerProxy,
CosmosClient,
DatabaseProxy

异常和返回代码

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

host.json 设置

本部分介绍版本 2.x 及更高版本中此绑定可用的配置设置。 host.json 文件中的设置将应用于函数应用实例中的所有函数。 有关函数应用配置设置的详细信息，请参阅 Azure Functions 的host.json 参考。

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}
属性 默认 说明
connectionMode Gateway 连接到 Azure Cosmos DB 服务时该函数使用的连接模式。 选项： Direct 通过 TCP 直接连接到后端副本，可以提供较低的延迟，并通过 Gateway HTTPS 通过前端网关路由请求。 有关详细信息，请参阅 Azure Cosmos DB SDK 连接模式。
userAgentSuffix 不适用 将指定的字符串值添加到由触发器发出的所有请求，或将其绑定到服务。 这样，你便可以更轻松地根据特定的函数应用跟踪 Azure Monitor 中的活动，并按 User Agent 对其进行筛选。

后续步骤