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

项目
08/21/2024

重要

对 Azure Functions 运行时 1.x 版的支持将于 2026 年 9 月 14 日结束。强烈建议将应用迁移到版本 4.x 以获得完全支持。

本文介绍如何在 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。在 Azure Functions 版本 1.x 中，仅触发器已重命名为 Azure Cosmos DB；输入绑定、输出绑定和 NuGet 包保留 DocumentDB 名称。

注意

Azure Cosmos DB 绑定只能与 SQL API 配合使用。对于所有其他的 Azure Cosmos DB API，应使用适用于 API 的静态客户端通过函数来访问数据库，其中包括 Azure Cosmos DB for MongoDB、Azure Cosmos DB for Apache Cassandra、Azure Cosmos DB for Apache Gremlin 和 Azure Cosmos DB for Table。

包 - 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}");
            }
        }
    }
}

以下示例演示 function.json 文件中的 Azure Cosmos DB 触发器绑定以及使用该绑定的 JavaScript 函数。修改 Azure Cosmos DB 记录时，该函数会写入日志消息。

下面是 function.json 文件中的绑定数据：

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": true
}

JavaScript 代码如下所示：

    module.exports = async function (context, documents) {
        context.log('First document Id modified : ', documents[0].id);
    }

触发器 - 特性

C#
JavaScript

对于进程内 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` 无效。

在本地开发时，需要将应用程序设置添加到 Values 集合中的 local.settings.json 文件中。

触发器 - 用法

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

重要

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

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

输入

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

输入 - 示例

C#
JavaScript

本部分包含以下示例：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 获取多个文档
HTTP 触发器，使用 DocumentClient 获取多个文档

这些示例引用简单的 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

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);
        }
    }
}

本部分包含以下示例：

队列触发器，从 JSON 查找 ID
HTTP 触发器，从查询字符串查找 ID
HTTP 触发器，从路由数据查找 ID
队列触发器，使用 SqlQuery 获取多个文档

队列触发器，从 JSON 查找 ID

以下示例演示 function.json 文件中的一个 Azure Cosmos DB 输入绑定以及使用该绑定的 JavaScript 函数。该函数读取单个文档，并更新文档的文本值。

下面是 function.json 文件中的绑定数据：

{
    "name": "inputDocumentIn",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

    // Change input document contents using Azure Cosmos DB input binding, using context.bindings.inputDocumentOut
    module.exports = async function (context) {
        context.bindings.inputDocumentOut = context.bindings.inputDocumentIn;
        context.bindings.inputDocumentOut.text = "This was updated!";
    };

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

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

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}"
    }
  ],
  "disabled": true
}

JavaScript 代码如下所示：

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

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

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "documentDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connection": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}"
    }
  ],
  "disabled": false
}

JavaScript 代码如下所示：

module.exports = async function (context, req, toDoItem) {
    context.log('JavaScript queue trigger function processed work item');
    if (!toDoItem)
    {
        context.log("ToDo item not found");
    }
    else
    {
        context.log("Found ToDo item, Description=" + toDoItem.Description);
    }
};

队列触发器，使用 SqlQuery 获取多个文档

以下示例演示 function.json 文件中的一个 Azure Cosmos DB 输入绑定以及使用该绑定的 JavaScript 函数。该函数使用队列触发器自定义查询参数检索 SQL 查询指定的多个文档。

队列触发器提供参数 departmentId。 { "departmentId" : "Finance" } 的队列消息将返回财务部的所有记录。

下面是 function.json 文件中的绑定数据：

{
    "name": "documents",
    "type": "documentdb",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connection": "CosmosDBConnection"
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

    module.exports = async function (context, input) {
        var documents = context.bindings.documents;
        for (var i = 0; i < documents.length; i++) {
            var document = documents[i];
            // operate on each document
        }
    };

输入 - 特性

C#
JavaScript

在进程内 C# 类库中，请使用 DocumentDB 特性。

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

输入 - 配置

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

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

在本地开发时，需要将应用程序设置添加到 Values 集合中的 local.settings.json 文件中。

输入 - 用法

C#
JavaScript

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

输出

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

输出 - 示例

C#
JavaScript

本部分包含以下示例：

队列触发器，写入一个文档
队列触发器，使用 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);
            }
        }
    }
}

以下示例演示 function.json 文件中的一个 Azure Cosmos DB 输出绑定以及使用该绑定的 JavaScript 函数。该函数使用一个用于某个队列的队列输入绑定，该队列以下列格式接收 JSON：

{
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

该函数按下列格式为每个记录创建 Azure Cosmos DB 文档：

{
    "id": "John Henry-123456",
    "name": "John Henry",
    "employeeId": "123456",
    "address": "A town nearby"
}

下面是 function.json 文件中的绑定数据：

{
    "name": "employeeDocument",
    "type": "documentDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": true,
    "connection": "MyAccount_COSMOSDB",
    "direction": "out"
}

配置部分解释了这些属性。

JavaScript 代码如下所示：

    module.exports = async function (context) {

      context.bindings.employeeDocument = JSON.stringify({
        id: context.bindings.myQueueItem.name + "-" + context.bindings.myQueueItem.employeeId,
        name: context.bindings.myQueueItem.name,
        employeeId: context.bindings.myQueueItem.employeeId,
        address: context.bindings.myQueueItem.address
      });
    };

输出 - 特性

C#
JavaScript

在进程内 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 连接字符串的应用设置的名称。

在本地开发时，需要将应用程序设置添加到 Values 集合中的 local.settings.json 文件中。

输出 - 用法

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

注意

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

异常和返回代码

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

通过

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

包 - Functions 1.x

触发器

触发器 - 示例

触发器 - 特性

触发器 - 配置

触发器 - 用法

输入

输入 - 示例

队列触发器，从 JSON 查找 ID

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

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

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

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

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

队列触发器，从 JSON 查找 ID

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

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

队列触发器，使用 SqlQuery 获取多个文档

输入 - 特性

输入 - 配置

输入 - 用法

输出

输出 - 示例

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

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

输出 - 特性

输出 - 配置

输出 - 用法

异常和返回代码

后续步骤

其他资源