适用于 Azure Functions 1.x 的 Azure Cosmos DB 绑定

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

备注

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

此绑定最初名为 DocumentDB。 在 Functions 版本 1.x 中,仅触发器已重命名为 Cosmos DB;输入绑定、输出绑定和 NuGet 包保留 DocumentDB 名称。

此参考信息面向 Azure Functions 开发人员。 Azure Functions 的新手请从以下资源入手:

备注

Azure Cosmos DB 绑定只能与 SQL API 配合使用。 对于所有其他的 Azure Cosmos DB API,应使用适用于 API 的静态客户端通过函数来访问数据库。API 包括 Azure Cosmos DB 的 API for MongoDBCassandra APIGremlin API表 API

包 - Functions 1.x

Microsoft.Azure.WebJobs.Extensions.DocumentDB NuGet 包 1.x 版中提供了适用于 Functions 1.x 版的 Azure Cosmos DB 绑定。 azure-webjobs-sdk-extensions GitHub 存储库中提供了此绑定的源代码。

下表说明了如何在每个开发环境中添加对此绑定的支持。

开发环境 添加支持
Functions 1.x
本地开发 - C# 类库 安装包
本地开发 - C# 脚本、JavaScript、F# 自动
门户开发 自动

触发器

Azure Cosmos DB 触发器使用 Azure Cosmos DB 更改源来侦听跨分区的插入和更新。 更改源发布插入和更新,不发布删除。

触发器 - 示例

以下示例演示了一个 C# 函数。当指定数据库和集合中存在插入或更新操作时,会调用该函数。

using Microsoft.Azure.Documents;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;

namespace CosmosDBSamplesV1
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "ToDoItems",
            collectionName: "Items",
            ConnectionStringSetting = "CosmosDBConnection",
            LeaseCollectionName = "leases",
            CreateLeaseCollectionIfNotExists = true)]IReadOnlyList<Document> documents,
            TraceWriter log)
        {
            if (documents != null && documents.Count > 0)
            {
                log.Info($"Documents modified: {documents.Count}");
                log.Info($"First document Id: {documents[0].Id}");
            }
        }
    }
}

触发器 - 特性

C# 类库中,使用 CosmosDBTrigger 特性。

该特性的构造函数采用数据库名称和集合名称。 有关这些设置以及可以配置的其他属性的信息,请参阅触发器 - 配置。 下面是某个方法签名中的 CosmosDBTrigger 特性示例:

    [FunctionName("DocumentUpdates")]
    public static void Run(
        [CosmosDBTrigger("database", "collection", ConnectionStringSetting = "myCosmosDB")]
    IReadOnlyList<Document> documents,
        TraceWriter log)
    {
        ...
    }

有关完整示例,请参阅触发器 - C# 示例

触发器 - 配置

下表解释了在 function.json 文件和 CosmosDBTrigger 特性中设置的绑定配置属性。

function.json 属性 Attribute 属性 说明
type 不适用 必须设置为 cosmosDBTrigger
direction 不适用 必须设置为 in。 在 Azure 门户中创建触发器时,会自动设置该参数。
name 不适用 函数代码中使用的变量名称,表示发生更改的文档列表。
connectionStringSetting ConnectionStringSetting 应用设置的名称,该应用设置包含用于连接到受监视的 Azure Cosmos DB 帐户的连接字符串。
databaseName DatabaseName 带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName CollectionName 受监视的集合的名称。
leaseConnectionStringSetting LeaseConnectionStringSetting (可选)应用设置的名称,该应用设置包含指向保留租用集合的服务的连接字符串。 未设置时,使用 connectionStringSetting 值。 在门户中创建绑定时,将自动设置该参数。 用于租用集合的连接字符串必须具有写入权限。
leaseDatabaseName LeaseDatabaseName (可选)数据库的名称,该数据库包含用于存储租用的集合。 未设置时,使用 databaseName 设置的值。 在门户中创建绑定时,将自动设置该参数。
leaseCollectionName LeaseCollectionName (可选)用于存储租用的集合的名称。 未设置时,使用值 leases
createLeaseCollectionIfNotExists CreateLeaseCollectionIfNotExists (可选)设置为 true 时,如果租用集合并不存在,将自动创建该集合。 默认值是 false
leasesCollectionThroughput LeasesCollectionThroughput (可选)在创建租用集合时,定义要分配的请求单位的数量。 仅当 createLeaseCollectionIfNotExists 设置为 true 时,才会使用该设置。 使用门户创建绑定时,将自动设置该参数。
leaseCollectionPrefix LeaseCollectionPrefix (可选)设置后,此项向在此 Function 的“租用”集合中创建的租用添加一个前缀,实际上就是允许两个不同的 Azure Functions(使用不同的前缀)共享同一“租用”集合。
feedPollDelay FeedPollDelay (可选)设置后,此项以毫秒为单位定义在所有当前更改均耗尽后,源上新更改的分区轮询间的延迟。 默认为 5000(5 秒)。
leaseAcquireInterval LeaseAcquireInterval (可选)设置后,此项以毫秒为单位定义启动一个计算任务的时间间隔(前提是分区在已知的主机实例中均匀分布)。 默认为 13000(13 秒)。
leaseExpirationInterval LeaseExpirationInterval (可选)设置后,此项以毫秒为单位定义在表示分区的租用上进行租用的时间间隔。 如果在此时间间隔内不续订租用,则该租用会过期,分区的所有权会转移到另一个实例。 默认为 60000(60 秒)。
leaseRenewInterval LeaseRenewInterval (可选)设置后,此项以毫秒为单位定义当前由实例拥有的分区的所有租用的续订时间间隔。 默认为 17000(17 秒)。
checkpointFrequency CheckpointFrequency (可选)设置后,此项以毫秒为单位定义租用检查点的时间间隔。 默认为始终在进行每个 Function 调用之后进行检查。
maxItemsPerInvocation MaxItemsPerInvocation (可选)设置后,此项对每次 Function 调用收到的项目的最大数目进行自定义。
startFromBeginning StartFromBeginning (可选)设置时,它会告诉触发器从集合历史记录的开头而不是当前时间开始读取更改。 这仅在触发器第一次启动时起作用,因为在后续运行中,已存储检查点。 如果已经创建租约,则将此值设置为 true 无效。

在本地进行开发时,应用设置将取 local.settings.json 文件的值。

触发器 - 用法

触发器需要第二个集合,该集合用于存储各分区的 租用 。 必须提供受监视的集合和包含租用的集合,触发器才能正常工作。

重要

如果多个函数都配置为对同一集合使用 Cosmos DB 触发器,则每个函数都应使用专用租用集合,否则应该为每个函数指定不同的 LeaseCollectionPrefix。 否则,将只触发其中一个函数。 有关前缀的信息,请参阅“配置”部分

该触发器并不指示是更新还是插入文档,它仅提供文档本身。 如果需要以不同方式处理更新和插入,可通过实现用于插入或更新的时间戳字段来执行该操作。

输入

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

输入 - 示例

本部分包含以下示例:

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

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

队列触发器,从 JSON 查找 ID

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

namespace CosmosDBSamplesV1
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }
    }
}
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}")]ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId}");

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

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

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

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

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static HttpResponseMessage Run(
            [HttpTrigger(
                AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}")] ToDoItem toDoItem,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            if (toDoItem == null)
            {
                log.Info($"ToDo item not found");
            }
            else
            {
                log.Info($"Found ToDo item, Description={toDoItem.Description}");
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

跳过输入示例

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

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")] IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

跳过输入示例

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

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

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using System.Net;
using System.Net.Http;

namespace CosmosDBSamplesV1
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static HttpResponseMessage Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.Info(toDoItem.Description);
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

跳过输入示例

HTTP 触发器,使用 DocumentClient 获取多个文档 (C#)

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

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 System;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]HttpRequestMessage req,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");
            string searchterm = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "searchterm", true) == 0)
                .Value;

            if (searchterm == null)
            {
                return req.CreateResponse(HttpStatusCode.NotFound);
            }

            log.Info($"Searching for word: {searchterm} using Uri: {collectionUri.ToString()}");
            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.Info(result.Description);
                }
            }
            return req.CreateResponse(HttpStatusCode.OK);
        }
    }
}

输入 - 特性

C# 类库中,使用 DocumentDB 特性。

该特性的构造函数采用数据库名称和集合名称。 有关这些设置以及可以配置的其他属性的信息,请参阅下面的“配置”部分

输入 - 配置

下表解释了在 function.json 文件和 DocumentDB 特性中设置的绑定配置属性。

function.json 属性 Attribute 属性 说明
type 不适用 必须设置为 documentdb
direction 不适用 必须设置为 in
name 不适用 表示函数中的文档的绑定参数的名称。
databaseName DatabaseName 包含文档的数据库。
collectionName CollectionName 包含文档的集合的名称。
id Id 要检索的文档的 ID。 此属性支持绑定表达式。 不要同时设置 idsqlQuery 属性。 如果上述两个属性都未设置,则会检索整个集合。
sqlQuery SqlQuery 用于检索多个文档的 Azure Cosmos DB SQL 查询。 该属性支持运行时绑定,如以下示例中所示:SELECT * FROM c where c.departmentId = {departmentId}。 不要同时设置 idsqlQuery 属性。 如果上述两个属性都未设置,则会检索整个集合。
连接 ConnectionStringSetting 内含 Azure Cosmos DB 连接字符串的应用设置的名称。
partitionKey PartitionKey 指定用于查找分区键值。 可以包含绑定参数。

在本地进行开发时,应用设置将取 local.settings.json 文件的值。

输入 - 用法

函数成功退出时,通过命名输入参数对输入文档所做的任何更改都会自动保存。

输出

Azure Cosmos DB 输出绑定允许使用 SQL API 将新文档写入 Azure Cosmos DB 数据库。

输出 - 示例

本部分包含以下示例:

  • 队列触发器,写入一个文档
  • 队列触发器,使用 IAsyncCollector 写入文档

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

namespace CosmosDBSamplesV1
{
    public class ToDoItem
    {
        public string Id { get; set; }
        public string Description { get; set; }
    }
}

队列触发器,写入一个文档

以下示例演示一个使用队列存储消息中提供的数据,将文档添加到数据库的 C# 函数

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System;

namespace CosmosDBSamplesV1
{
    public static class WriteOneDoc
    {
        [FunctionName("WriteOneDoc")]
        public static void Run(
            [QueueTrigger("todoqueueforwrite")] string queueMessage,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]out dynamic document,
            TraceWriter log)
        {
            document = new { Description = queueMessage, id = Guid.NewGuid() };

            log.Info($"C# Queue trigger function inserted one row");
            log.Info($"Description={queueMessage}");
        }
    }
}

队列触发器,使用 IAsyncCollector 来写入文档

以下示例演示了一个 C# 函数,该函数使用以队列消息 JSON 格式提供的数据将文档集添加到数据库。

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using System.Threading.Tasks;

namespace CosmosDBSamplesV1
{
    public static class WriteDocsIAsyncCollector
    {
        [FunctionName("WriteDocsIAsyncCollector")]
        public static async Task Run(
            [QueueTrigger("todoqueueforwritemulti")] ToDoItem[] toDoItemsIn,
            [DocumentDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")]
                IAsyncCollector<ToDoItem> toDoItemsOut,
            TraceWriter log)
        {
            log.Info($"C# Queue trigger function processed {toDoItemsIn?.Length} items");

            foreach (ToDoItem toDoItem in toDoItemsIn)
            {
                log.Info($"Description={toDoItem.Description}");
                await toDoItemsOut.AddAsync(toDoItem);
            }
        }
    }
}

输出 - 特性

C# 类库中,使用 DocumentDB 特性。

该特性的构造函数采用数据库名称和集合名称。 有关这些设置以及可以配置的其他属性的信息,请参阅输出 - 配置。 下面是某个方法签名中的 DocumentDB 特性示例:

    [FunctionName("QueueToDocDB")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "AzureWebJobsStorage")] string myQueueItem,
        [DocumentDB("ToDoList", "Items", Id = "id", ConnectionStringSetting = "myCosmosDB")] out dynamic document)
    {
        ...
    }

有关完整示例,请参阅输出

输出 - 配置

下表解释了在 function.json 文件和 DocumentDB 特性中设置的绑定配置属性。

function.json 属性 Attribute 属性 说明
type 不适用 必须设置为 documentdb
direction 不适用 必须设置为 out
name 不适用 表示函数中的文档的绑定参数的名称。
databaseName DatabaseName 包含在其中创建文档的集合的数据库。
collectionName CollectionName 包含在其中创建文档的集合的名称。
createIfNotExists CreateIfNotExists 一个用于指示是否创建集合(如果不存在)的布尔值。 默认值为 false ,因为新集合是使用保留的吞吐量创建的,具有成本方面的隐含意义。 有关详细信息,请参阅定价页
partitionKey PartitionKey CreateIfNotExists 为 true 时,将定义所创建集合的分区键路径。
collectionThroughput CollectionThroughput CreateIfNotExists 为 true 时,将定义所创建集合的吞吐量
连接 ConnectionStringSetting 内含 Azure Cosmos DB 连接字符串的应用设置的名称。

在本地进行开发时,应用设置将取 local.settings.json 文件的值。

输出 - 用法

默认情况下,当写入函数中的输出参数时,将在数据库中创建一个文档。 本文档将自动生成的 GUID 作为文档 ID。 可以通过在传递给输出参数的 JSON 对象中指定 id 属性来指定输出文档的文档 ID。

备注

如果指定现有文档的 ID,它会被新的输出文档覆盖。

异常和返回代码

绑定 参考
CosmosDB CosmosDB 错误代码

后续步骤