适用于 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 Functions 2.x 及更高版本。 若要了解如何在 Functions 1.x 中使用这些绑定,请参阅适用于 Azure Functions 1.x 的 Azure Cosmos DB 绑定

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

受支持的 API

Azure Cosmos DB 绑定只能与 SQL API 配合使用。 从扩展 5.x 开始,通过使用表存储绑定来提供对表 API 的支持。 对于所有其他的 Azure Cosmos DB API,应使用适用于 API 的静态客户端通过函数来访问数据库。API 包括 Azure Cosmos DB API for MongoDBCassandra APIGremlin API

安装扩展

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

函数在与函数主机相同的进程中执行。 若要了解详细信息,请参阅使用 Azure Functions 开发 C# 类库函数

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

使用触发器和绑定需要引用相应的 NuGet 包。 安装 NuGet 包版本 3.x。

安装捆绑包

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

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

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

由于 Azure Cosmos DB SDK 中的架构发生更改,Java 函数当前不支持 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)"
  }
}

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


异常和返回代码

绑定 参考
CosmosDB CosmosDB 错误代码

host.json 设置

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

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}
属性 默认 说明
connectionMode Gateway 连接到 Azure Cosmos DB 服务时该函数使用的连接模式。 选项为 DirectGateway
protocol Https 连接到 Azure Cosmos DB 服务时该函数使用的连接协议。 请参阅此文,了解两种模式的说明。
leasePrefix 不适用 应用中所有函数要使用的租用前缀。

后续步骤