适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 输入绑定

项目
09/27/2022

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

有关设置和配置详细信息，请参阅概述。

注意

当集合已分区时，查找操作还必须指定分区键值。

示例

除非另有说明，否则本文中的示例针对的都是 Azure Cosmos DB 扩展的版本 3.x。若要与扩展版本 4.x 一起使用，需要将 collection 属性和属性名称中的字符串替换为 container。

可以使用以下 C# 模式之一创建 C# 函数：

进程内类库：编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。
独立进程类库：编译的 C# 函数，该函数在独立于运行时的进程中运行。支持在 .NET 5.0 上运行的 C# 函数需要独立的进程。
C# 脚本：主要在 Azure 门户中创建 C# 函数时使用。

本部分包含的以下示例演示如何将进程内 C# 类库函数与扩展版本 3.x 配合使用：

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

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

namespace CosmosDBSamplesV2
{
    public class ToDoItem
    {
        [JsonProperty("id")]
        public string Id { get; set; }

        [JsonProperty("partitionKey")]
        public string PartitionKey { get; set; }

        public string Description { get; set; }
    }
}

队列触发器，从 JSON 查找 ID

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

namespace CosmosDBSamplesV2
{
    public class ToDoItemLookup
    {
        public string ToDoItemId { get; set; }

        public string ToDoItemPartitionKeyValue { get; set; }
    }
}

using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromJSON
    {
        [FunctionName("DocByIdFromJSON")]
        public static void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{ToDoItemId}",
                PartitionKey = "{ToDoItemPartitionKeyValue}")]ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation($"C# Queue trigger function processed Id={toDoItemLookup?.ToDoItemId} Key={toDoItemLookup?.ToDoItemPartitionKeyValue}");

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

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

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

注意

HTTP 查询字符串参数区分大小写。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromQueryString
    {
        [FunctionName("DocByIdFromQueryString")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{Query.id}",
                PartitionKey = "{Query.partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteData
    {
        [FunctionName("DocByIdFromRouteData")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems/{partitionKey}/{id}")]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                Id = "{id}",
                PartitionKey = "{partitionKey}")] ToDoItem toDoItem,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

以下示例演示如何在 SqlQuery 参数中使用绑定表达式。可以将路由数据传递至所示的 SqlQuery 参数，但目前无法传递查询字符串值。

注意

如果需要只按 ID 进行查询，则建议使用查找（如以前的示例所示），因为该查找消耗较少的请求单位。点读取操作 (GET) 比按 ID 进行的查询更高效。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocByIdFromRouteDataUsingSqlQuery
    {
        [FunctionName("DocByIdFromRouteDataUsingSqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = "todoitems2/{id}")]HttpRequest req,
            [CosmosDB("ToDoItems", "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "select * from ToDoItems r where r.id = {id}")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

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

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

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;
using System.Collections.Generic;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsBySqlQuery
    {
        [FunctionName("DocsBySqlQuery")]
        public static IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]
                HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection",
                SqlQuery = "SELECT top 2 * FROM c order by c._ts desc")]
                IEnumerable<ToDoItem> toDoItems,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");
            foreach (ToDoItem toDoItem in toDoItems)
            {
                log.LogInformation(toDoItem.Description);
            }
            return new OkResult();
        }
    }
}

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

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

注意

还可以使用 IDocumentClient 接口来简化测试。

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
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 Microsoft.Extensions.Logging;
using System;
using System.Linq;
using System.Threading.Tasks;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingDocumentClient
    {
        [FunctionName("DocsByUsingDocumentClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                collectionName: "Items",
                ConnectionStringSetting = "CosmosDBConnection")] DocumentClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"];
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Uri collectionUri = UriFactory.CreateDocumentCollectionUri("ToDoItems", "Items");

            log.LogInformation($"Searching for: {searchterm}");

            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.LogInformation(result.Description);
                }
            }
            return new OkResult();
        }
    }
}

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

以下示例演示检索文档列表的 C# 函数。此函数由 HTTP 请求触发。此代码使用 Azure Cosmos DB 绑定（在扩展版本 4.x 中提供）提供的 CosmosClient 实例来读取文档列表。 CosmosClient 实例也可用于写入操作。

using System.Linq;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Cosmos;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Host;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Extensions.Logging;

namespace CosmosDBSamplesV2
{
    public static class DocsByUsingCosmosClient
    {  
        [FunctionName("DocsByUsingCosmosClient")]
        public static async Task<IActionResult> Run(
            [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post",
                Route = null)]HttpRequest req,
            [CosmosDB(
                databaseName: "ToDoItems",
                containerName: "Items",
                Connection = "CosmosDBConnection")] CosmosClient client,
            ILogger log)
        {
            log.LogInformation("C# HTTP trigger function processed a request.");

            var searchterm = req.Query["searchterm"].ToString();
            if (string.IsNullOrWhiteSpace(searchterm))
            {
                return (ActionResult)new NotFoundResult();
            }

            Container container = client.GetDatabase("ToDoItems").GetContainer("Items");

            log.LogInformation($"Searching for: {searchterm}");

            QueryDefinition queryDefinition = new QueryDefinition(
                "SELECT * FROM items i WHERE CONTAINS(i.Description, @searchterm)")
                .WithParameter("@searchterm", searchterm);
            using (FeedIterator<ToDoItem> resultSet = container.GetItemQueryIterator<ToDoItem>(queryDefinition))
            {
                while (resultSet.HasMoreResults)
                {
                    FeedResponse<ToDoItem> response = await resultSet.ReadNextAsync();
                    ToDoItem item = response.First();
                    log.LogInformation(item.Description);
                }
            }

            return new OkResult();
        }
    }
}

本部分包含需要 3.x 版 Azure Cosmos DB 扩展和 5.x 版 Azure 存储扩展的示例。如果你的函数应用中尚不存在对以下 NuGet 包的引用，请添加它们：

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

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.

using System;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Extensions.CosmosDB
{
    /// <summary>
    /// Sample function app which has a azure storage queue trigger and CosmosDb input binding.
    /// The CosmosDb input binding is using the values from the queue trigger payload
    /// to query the cosmos db item.
    /// </summary>

    //<docsnippet_qtrigger_with_cosmosdb_inputbinding>
    public class CosmosDbInputBindingFunction
    {
        private readonly ILogger _logger;

        public CosmosDbInputBindingFunction(ILogger<CosmosDbInputBindingFunction> logger)
        {
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        }

        [Function("DocByIdFromJSON")]
        public void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDBInput(databaseName: "ToDoItems",
                           collectionName: "Items",
                           ConnectionStringSetting = "CosmosConnection",
                           Id ="{ToDoItemId}",
                           PartitionKey ="{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
        {
            if (toDoItem == null)
            {
                _logger.LogInformation("ToDo item not found");
            }
            else
            {
                _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }

    public record ToDoItemLookup(string ToDoItemId, string ToDoItemPartitionKeyValue);
    //</docsnippet_qtrigger_with_cosmosdb_inputbinding>

    //<docsnippet_qtrigger_with_cosmosdb_inputbinding_todo_model>
    public class ToDoItem
    {
        public string Id { get; set; }
        public string PartitionKey { get; set; }
        public string Description { get; set; }
    }
    //</docsnippet_qtrigger_with_cosmosdb_inputbinding_todo_model>
}

队列触发器，从 JSON 查找 ID

以下示例显示了一个检索单个文档的函数。该函数由存储队列中的 JSON 消息触发。队列触发器将 JSON 分析为 ToDoItemLookup 类型的对象，其中包含要检索的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中返回一个 ToDoItem 文档。

// Copyright (c) .NET Foundation. All rights reserved.
// Licensed under the MIT License. See License.txt in the project root for license information.

using System;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Extensions.CosmosDB
{
    /// <summary>
    /// Sample function app which has a azure storage queue trigger and CosmosDb input binding.
    /// The CosmosDb input binding is using the values from the queue trigger payload
    /// to query the cosmos db item.
    /// </summary>

    //<docsnippet_qtrigger_with_cosmosdb_inputbinding>
    public class CosmosDbInputBindingFunction
    {
        private readonly ILogger _logger;

        public CosmosDbInputBindingFunction(ILogger<CosmosDbInputBindingFunction> logger)
        {
            _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        }

        [Function("DocByIdFromJSON")]
        public void Run(
            [QueueTrigger("todoqueueforlookup")] ToDoItemLookup toDoItemLookup,
            [CosmosDBInput(databaseName: "ToDoItems",
                           collectionName: "Items",
                           ConnectionStringSetting = "CosmosConnection",
                           Id ="{ToDoItemId}",
                           PartitionKey ="{ToDoItemPartitionKeyValue}")] ToDoItem toDoItem)
        {
            if (toDoItem == null)
            {
                _logger.LogInformation("ToDo item not found");
            }
            else
            {
                _logger.LogInformation($"Found ToDo item, Description={toDoItem.Description}");
            }
        }
    }

    public record ToDoItemLookup(string ToDoItemId, string ToDoItemPartitionKeyValue);
    //</docsnippet_qtrigger_with_cosmosdb_inputbinding>

    //<docsnippet_qtrigger_with_cosmosdb_inputbinding_todo_model>
    public class ToDoItem
    {
        public string Id { get; set; }
        public string PartitionKey { get; set; }
        public string Description { get; set; }
    }
    //</docsnippet_qtrigger_with_cosmosdb_inputbinding_todo_model>
}

本部分包含以下示例：

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

HTTP 触发器示例引用简单的 ToDoItem 类型：

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

队列触发器，从字符串查找 ID

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

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

{
    "name": "inputDocument",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger}",
    "partitionKey": "{partition key value}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
}

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

C# 脚本代码如下所示：

    using System;

    // Change input document contents using Azure Cosmos DB input binding
    public static void Run(string myQueueItem, dynamic inputDocument)
    {
      inputDocument.text = "This has changed.";
    }

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

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

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

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

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

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

C# 脚本代码如下所示：

    public static void Run(QueuePayload myQueueItem, IEnumerable<dynamic> documents)
    {
        foreach (var doc in documents)
        {
            // operate on each document
        }
    }

    public class QueuePayload
    {
        public string departmentId { get; set; }
    }

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

以下示例演示检索单个文档的 C# 脚本函数。此函数由 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": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey" : "{Query.partitionKeyValue}"
    }
  ],
  "disabled": false
}

C# 脚本代码如下所示：

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

function.json 文件如下所示：

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

C# 脚本代码如下所示：

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, ToDoItem toDoItem, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

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

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

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

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "sqlQuery": "SELECT top 2 * FROM c order by c._ts desc"
    }
  ],
  "disabled": false
}

C# 脚本代码如下所示：

using System.Net;
using Microsoft.Extensions.Logging;

public static HttpResponseMessage Run(HttpRequestMessage req, IEnumerable<ToDoItem> toDoItems, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    foreach (ToDoItem toDoItem in toDoItems)
    {
        log.LogInformation(toDoItem.Description);
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

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

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

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "client",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "inout"
    }
  ],
  "disabled": false
}

C# 脚本代码如下所示：

#r "Microsoft.Azure.Documents.Client"

using System.Net;
using Microsoft.Azure.Documents.Client;
using Microsoft.Azure.Documents.Linq;
using Microsoft.Extensions.Logging;

public static async Task<HttpResponseMessage> Run(HttpRequestMessage req, DocumentClient client, ILogger log)
{
    log.LogInformation("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.LogInformation($"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.LogInformation(result.Description);
        }
    }
    return req.CreateResponse(HttpStatusCode.OK);
}

本部分包含以下示例：

HTTP 触发器，从查询字符串查找 ID - 字符串参数
HTTP 触发器，从查询字符串查找 ID - POJO 参数
HTTP 触发器，从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据查找 ID
HTTP 触发器，使用 SqlQuery 从路由数据获取多个文档（C# 脚本）

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

public class ToDoItem {

  private String id;
  private String description;

  public String getId() {
    return id;
  }

  public String getDescription() {
    return description;
  }

  @Override
  public String toString() {
    return "ToDoItem={id=" + id + ",description=" + description + "}";
  }
}

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

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于以字符串形式从指定的数据库和集合中检索文档。

public class DocByIdFromQueryString {

    @FunctionName("DocByIdFromQueryString")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

在 Java 函数运行时库中，对其值将来自 Cosmos DB 的函数参数使用 @CosmosDBInput 注释。可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

HTTP 触发器，从查询字符串查找 ID - POJO 参数

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的查询字符串用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索文档。然后将该文档转换为先前创建的 ToDoItem POJO 实例，并作为参数传递给该函数。

public class DocByIdFromQueryStringPojo {

    @FunctionName("DocByIdFromQueryStringPojo")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{Query.id}",
              partitionKey = "{Query.partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Item from the database is " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

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

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用的路由参数用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索文档，将它作为 Optional<String> 返回。

public class DocByIdFromRoute {

    @FunctionName("DocByIdFromRoute")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems/{partitionKeyValue}/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              id = "{id}",
              partitionKey = "{partitionKeyValue}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            Optional<String> item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("String from the database is " + (item.isPresent() ? item.get() : null));

        // Convert and display
        if (!item.isPresent()) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            // return JSON from Cosmos. Alternatively, we can parse the JSON string
            // and return an enriched JSON object.
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item.get())
                          .build();
        }
    }
}

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

以下示例展示了检索单个文档的 Java 函数。此函数由 HTTP 请求触发，该请求使用路由参数指定要查找的 ID。该 ID 用于从指定的数据库和集合中检索文档，将结果集转换为 ToDoItem[]，因为可能会返回许多文档，具体取决于查询条件。

注意

如果需要只按 ID 进行查询，则建议使用查找（如以前的示例所示），因为该查找消耗较少的请求单位。点读取操作 (GET) 比按 ID 进行的查询更高效。

public class DocByIdFromRouteSqlQuery {

    @FunctionName("DocByIdFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems2/{id}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where r.id = {id}",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] item,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Items from the database are " + item);

        // Convert and display
        if (item == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("Document not found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(item)
                          .build();
        }
    }
}

HTTP 触发器，使用 SqlQuery 从路由数据获取多个文档

以下示例演示了检索多个文档的 Java 函数。该函数由 HTTP 请求触发，该请求使用路由参数 desc 指定要在 description 字段中搜索的字符串。搜索项用于从指定的数据库和集合中检索文档集合，将结果集转换为 ToDoItem[] 并将其作为参数传递给函数。

public class DocsFromRouteSqlQuery {

    @FunctionName("DocsFromRouteSqlQuery")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET},
              authLevel = AuthorizationLevel.ANONYMOUS,
              route = "todoitems3/{desc}")
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBInput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              sqlQuery = "select * from Items r where contains(r.description, {desc})",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            ToDoItem[] items,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());
        context.getLogger().info("Number of items from the database is " + (items == null ? 0 : items.length));

        // Convert and display
        if (items == null) {
            return request.createResponseBuilder(HttpStatus.BAD_REQUEST)
                          .body("No documents found.")
                          .build();
        }
        else {
            return request.createResponseBuilder(HttpStatus.OK)
                          .header("Content-Type", "application/json")
                          .body(items)
                          .build();
        }
    }
}

此部分包含的以下示例可以通过指定各种源提供的 ID 值来读取单个文档：

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

队列触发器，从 JSON 查找 ID

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

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

{
    "name": "inputDocumentIn",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "inputDocumentOut",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "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": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "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);
    }
};

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

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

function.json 文件如下所示：

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "methods": [
        "get",
        "post"
      ],
      "route":"todoitems/{partitionKeyValue}/{id}"
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "type": "cosmosDB",
      "name": "toDoItem",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{id}",
      "PartitionKey": "{partitionKeyValue}"
    }
  ],
  "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": "cosmosDB",
    "direction": "in",
    "databaseName": "MyDb",
    "collectionName": "MyCollection",
    "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}",
    "connectionStringSetting": "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
  }
};

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

队列触发器，从 JSON 查找 ID

下面的示例演示如何读取和更新单个 Cosmos DB 文档。文档的唯一标识符通过队列消息中的 JSON 值提供。

Cosmos DB 输入绑定在函数配置文件 (function.json) 中提供的绑定列表中首先列出。

{
  "name": "InputDocumentIn",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "id": "{queueTrigger_payload_property}",
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "in"
},
{
  "name": "InputDocumentOut",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": false,
  "partitionKey": "{queueTrigger_payload_property}",
  "connectionStringSetting": "CosmosDBConnection",
  "direction": "out"
}

run.ps1 文件包含 PowerShell 代码，该代码读取传入的文档并输出更改。

param($QueueItem, $InputDocumentIn, $TriggerMetadata)

$Document = $InputDocumentIn 
$Document.text = 'This was updated!'

Push-OutputBinding -Name InputDocumentOut -Value $Document

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

下面的示例演示如何通过 Web API 读取和更新单个 Cosmos DB 文档。文档的唯一标识符通过 HTTP 请求中的 querystring 参数提供，如绑定的 "Id": "{Query.Id}" 属性所定义。

Cosmos DB 输入绑定在函数配置文件 (function.json) 中提供的绑定列表中首先列出。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{Query.id}", 
      "PartitionKey": "{Query.partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ] 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    },
  ], 
  "disabled": false 
}

run.ps1 文件包含 PowerShell 代码，该代码读取传入的文档并输出更改。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else {

    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

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

下面的示例演示如何通过 Web API 读取和更新单个 Cosmos DB 文档。文档的唯一标识符通过 route 参数提供。 route 参数在 HTTP 请求绑定的 route 属性中定义，并在 Cosmos DB "Id": "{Id}" 绑定属性中引用。

Cosmos DB 输入绑定在函数配置文件 (function.json) 中提供的绑定列表中首先列出。

{ 
  "bindings": [ 
    { 
      "type": "cosmosDB", 
      "name": "ToDoItem", 
      "databaseName": "ToDoItems", 
      "collectionName": "Items", 
      "connectionStringSetting": "CosmosDBConnection", 
      "direction": "in", 
      "Id": "{id}", 
      "PartitionKey": "{partitionKeyValue}" 
    },
    { 
      "authLevel": "anonymous", 
      "name": "Request", 
      "type": "httpTrigger", 
      "direction": "in", 
      "methods": [ 
        "get", 
        "post" 
      ], 
      "route": "todoitems/{partitionKeyValue}/{id}" 
    }, 
    { 
      "name": "Response", 
      "type": "http", 
      "direction": "out" 
    }
  ], 
  "disabled": false 
}

run.ps1 文件包含 PowerShell 代码，该代码读取传入的文档并输出更改。

using namespace System.Net

param($Request, $ToDoItem, $TriggerMetadata)

Write-Host 'PowerShell HTTP trigger function processed a request'

if (-not $ToDoItem) { 
    Write-Host 'ToDo item not found'

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::NotFound 
        Body = $ToDoItem.Description 
    })

} else { 
    Write-Host "Found ToDo item, Description=$($ToDoItem.Description)"

    Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{ 
        StatusCode = [HttpStatusCode]::OK 
        Body = $ToDoItem.Description 
    }) 
}

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

下面的示例演示如何读取多个 Cosmos DB 文档。函数的配置文件 (function.json) 定义了包含 sqlQuery 的绑定属性。提供给 sqlQuery 属性的 SQL 语句选择提供给函数的文档集。

{ 
  "name": "Documents", 
  "type": "cosmosDB", 
  "direction": "in", 
  "databaseName": "MyDb", 
  "collectionName": "MyCollection", 
  "sqlQuery": "SELECT * from c where c.departmentId = {departmentId}", 
  "connectionStringSetting": "CosmosDBConnection" 
}

run1.ps 文件包含 PowerShell 代码，该代码读取传入的文档。

param($QueueItem, $Documents, $TriggerMetadata)

foreach ($Document in $Documents) { 
    # operate on each document 
}

此部分包含的以下示例可以通过指定各种源提供的 ID 值来读取单个文档：

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

队列触发器，从 JSON 查找 ID

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

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

{
    "name": "documents",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "id" : "{queueTrigger_payload_property}",
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "in"
},
{
    "name": "$return",
    "type": "cosmosDB",
    "databaseName": "MyDatabase",
    "collectionName": "MyCollection",
    "createIfNotExists": false,
    "partitionKey": "{queueTrigger_payload_property}",
    "connectionStringSetting": "MyAccount_COSMOSDB",
    "direction": "out"
}

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

下面是 Python 代码：

import azure.functions as func

def main(queuemsg: func.QueueMessage, documents: func.DocumentList) -> func.Document:
    if documents:
        document = documents[0]
        document['text'] = 'This was updated!'
        return document

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

以下示例展示了检索单个文档的 Python 函数。此函数由 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": "cosmosDB",
      "name": "todoitems",
      "databaseName": "ToDoItems",
      "collectionName": "Items",
      "connectionStringSetting": "CosmosDBConnection",
      "direction": "in",
      "Id": "{Query.id}",
      "PartitionKey": "{Query.partitionKeyValue}"
    }
  ],
  "scriptFile": "__init__.py"
}

下面是 Python 代码：

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])

    return 'OK'

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

以下示例展示了检索单个文档的 Python 函数。此函数由 HTTP 请求触发，该请求使用的路由数据用于指定要查找的 ID 和分区键值。该 ID 和分区键值用于从指定的数据库和集合中检索 ToDoItem 文档。

function.json 文件如下所示：

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

下面是 Python 代码：

import logging
import azure.functions as func

def main(req: func.HttpRequest, todoitems: func.DocumentList) -> str:
    if not todoitems:
        logging.warning("ToDo item not found")
    else:
        logging.info("Found ToDo item, Description=%s",
                     todoitems[0]['description'])
    return 'OK'

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

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

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

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

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

特性

进程内和独立进程 C# 库使用特性来定义函数。 C# 脚本改为使用 function.json 配置文件。

Attribute 属性	说明
ConnectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
DatabaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
CollectionName	受监视的集合的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，“中国北部,中国北部,中国北部”。

Attribute 属性	说明
Connection	应用设置或设置集合的名称，用于指定如何连接到所查询的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
DatabaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
ContainerName	要监视的容器的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

Attribute 属性	说明
ConnectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
DatabaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
CollectionName	受监视的集合的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，“中国北部,中国北部,中国北部”。

Attribute 属性	说明
Connection	应用设置或设置集合的名称，用于指定如何连接到所查询的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
DatabaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
ContainerName	要监视的容器的名称。
PartitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
Id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
SqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `Id` 和 `SqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
PreferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
connectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName	受监视的集合的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
连接	应用设置或设置容器的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
containerName	要监视的容器的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

批注

在 Java 函数运行时库中，对从 Azure Cosmos DB 读取数据的参数使用 @CosmosDBInput 注释。此注释支持以下属性：

配置

下表解释了在 function.json 文件中设置的绑定配置属性，其中属性因扩展版本而异。

Functions 2.x+
扩展 4.x+（预览版）

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
connectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName	受监视的集合的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
连接	应用设置或设置容器的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
containerName	要监视的容器的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

有关完整示例的信息，请参阅示例部分。

使用情况

事件网格触发器支持的参数类型取决于函数运行时版本、扩展包版本以及使用的 C# 形式。

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

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
connectionStringSetting	应用设置或设置集合的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的集合的 Azure Cosmos DB 数据库的名称。
collectionName	受监视的集合的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的集合中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个集合。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

function.json 属性	说明
type	必须设置为 `cosmosDBTrigger`。
direction	必须设置为 `in`。
name	函数代码中使用的变量名称，表示发生更改的文档列表。
连接	应用设置或设置容器的名称，用于指定如何连接到受监视的 Azure Cosmos DB 帐户。有关详细信息，请参阅连接。
databaseName	带有受监视的容器的 Azure Cosmos DB 数据库的名称。
containerName	要监视的容器的名称。
partitionKey	指定用于查找分区键值。可以包含绑定参数。它是在分区的容器中进行查询所需的。
id	要检索的文档的 ID。此属性支持绑定表达式。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
sqlQuery	用于检索多个文档的 Azure Cosmos DB SQL 查询。该属性支持运行时绑定，如以下示例中所示：`SELECT * FROM c where c.departmentId = {departmentId}`。不要同时设置 `id` 和 `sqlQuery` 属性。如果上述两个属性都未设置，则会检索整个容器。
preferredLocations	（可选）为 Azure Cosmos DB 服务中的异地复制数据库帐户定义首选位置（区域）。值应以逗号分隔。例如，`China North,China North,China North`。

在 Java 函数运行时库中，@CosmosDBInput 注释向函数公开 Cosmos DB 数据。可以将此注释与本机 Java 类型、POJO 或使用了 Optional<T> 的可为 null 的值一起使用。

函数退出时不会自动进行更新。请改用 context.bindings.<documentName>In 和 context.bindings.<documentName>Out 进行更新。有关更多详细信息，请参阅 JavaScript 示例。

函数退出时不会自动对文档进行更新。若要在函数中更新文档，请使用输出绑定。有关更多详细信息，请参阅 PowerShell 示例。

数据通过 DocumentList 参数提供给函数。不会自动保留对文档所做的更改。

连接

connectionStringSetting/connection 和 leaseConnectionStringSetting/leaseConnection 属性是对指定应用应该如何连接到 Azure Cosmos DB 的环境配置的引用。这些属性可以指定：

包含连接字符串的应用程序设置的名称
多个应用程序设置的共享前缀的名称，共同定义基于标识的连接。此选项仅适用于 4.x 或更高版本的扩展中的 connection 和 leaseConnection 版本。

如果配置的值既是单个设置的完全匹配，也是其他设置的前缀匹配，则使用完全匹配。

连接字符串

数据库帐户的连接字符串应存储在应用程序设置中，其名称与绑定配置的 connection 属性指定的值匹配。

基于标识的连接

如果使用 4.x 或更高版本的扩展，则无需将连接字符串与机密一起使用，可以使应用使用 Azure Active Directory 标识。为此，需要定义公共前缀下的设置，该前缀映射到触发器和绑定配置中的 connection 属性。

在此模式下，扩展需要以下属性：

属性	环境变量模板	说明	示例值
帐户终结点	`<CONNECTION_NAME_PREFIX>__accountEndpoint`	Azure Cosmos DB 帐户终结点 URI。	https://<数据库帐户名称>.documents.azure.cn:443/

可以设置其他属性来自定义连接。请参阅基于标识的连接的通用属性。

在 Azure Functions 服务中托管时，基于标识的连接将使用托管标识。默认情况下使用系统分配的标识，但可以使用 credential 和 clientID 属性来指定用户分配的标识。在其他上下文（如本地开发）中运行时，将改用开发人员标识，尽管可以进行自定义。请参阅使用基于标识的连接进行本地开发。

向标识授予权限

无论使用何种标识，都必须具有执行所需操作的权限。需要使用内置角色或者提供这些权限的自定义角色在 Azure RBAC 中分配角色。

重要

某些权限可能由并非所有上下文都需要的目标服务公开。尽可能遵循最低权限原则，仅授予标识所需的权限。例如，如果应用只需要从数据源进行读取即可，则使用仅具有读取权限的角色。分配一个也具有该服务写入权限的角色并不恰当，因为对于读取操作来说，写入是多余的权限。同样，你也希望确保角色分配的范围仅限于需要读取的资源。

你将需要创建一个角色分配，以便在运行时提供对数据库帐户的访问权限。所有者等管理角色还不够。下表显示了在正常操作中使用 Cosmos DB 扩展时建议使用的内置角色。根据所编写的代码，应用程序可能需要具有其他权限。

绑定类型	内置角色示例
触发器	Cosmos DB 内置数据参与者
输入绑定	Cosmos DB 内置数据读取者
输出绑定	Cosmos DB 内置数据参与者

适用于 Azure Functions 2.x 及更高版本的 Azure Cosmos DB 输入绑定

示例

队列触发器，从 JSON 查找 ID

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

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

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

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

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

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

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

HTTP 触发器，从查询字符串查找 ID - POJO 参数

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

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

HTTP 触发器，使用 SqlQuery 从路由数据获取多个文档

队列触发器，从 JSON 查找 ID

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

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

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

队列触发器，从 JSON 查找 ID

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

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

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

队列触发器，从 JSON 查找 ID

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

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

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

特性

批注

配置

使用情况

连接

连接字符串

基于标识的连接

向标识授予权限

后续步骤