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

Azure Functions 支持两种 Python 编程模型。 定义绑定的方式取决于选择的编程模型。

本文同时支持两个编程模型。

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

• 独立辅助角色模型：编译的 C# 函数，该函数在独立于运行时的工作进程中运行。 需要独立工作进程才能支持在 LTS 和非 LTS 版 .NET 和 .NET Framework 上运行的 C# 函数。 独立工作进程函数的扩展使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空间。
• 进程内模型：编译的 C# 函数，该函数在与 Functions 运行时相同的进程中运行。 在此模型的变体中，可以使用 C# 脚本运行 Functions，该脚本主要用于 C# 门户编辑。 进程内函数的扩展使用 Microsoft.Azure.WebJobs.Extensions.* 命名空间。

• 队列触发器，通过返回值将消息保存到数据库
• HTTP 触发器，通过返回值将文件保存到数据库
• HTTP 触发器，通过 OutputBinding 将一个文档保存到数据库
• HTTP 触发器，通过 OutputBinding 将多个文档保存到数据库

队列触发器，通过返回值将消息保存到数据库

以下示例展示了一个 Java 函数，它向数据库中添加一个文档，该文档包含来自队列存储中消息的数据。

@FunctionName("getItem")
@CosmosDBOutput(name = "database",
  databaseName = "ToDoList",
  collectionName = "Items",
  connectionStringSetting = "AzureCosmosDBConnection")
public String cosmosDbQueryById(
    @QueueTrigger(name = "msg",
      queueName = "myqueue-items",
      connection = "AzureWebJobsStorage")
    String message,
    final ExecutionContext context)  {
     return "{ id: \"" + System.currentTimeMillis() + "\", Description: " + message + " }";
   }

HTTP 触发器，通过返回值将文件保存到数据库

以下示例显示了 Java 函数，其签名使用 @CosmosDBOutput 注释，并且返回值类型为 String。 函数返回的 JSON 文档会自动写入相应的 Azure Cosmos DB 集合。

    @FunctionName("WriteOneDoc")
    @CosmosDBOutput(name = "database",
      databaseName = "ToDoList",
      collectionName = "Items",
      connectionStringSetting = "Cosmos_DB_Connection_String")
    public String run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            final ExecutionContext context) {

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        return jsonDocument;
    }

HTTP 触发器，通过 OutputBinding 将一个文档保存到数据库

以下示例显示了 Java 函数，该函数通过 OutputBinding<T> 输出参数将文档写入 Azure Cosmos DB。 在此示例中，需要使用 outputItem 为 @CosmosDBOutput 参数提供注释，而不要使用函数签名。 使用 OutputBinding<T>，让函数可以利用绑定将文档写入 Azure Cosmos DB，同时还可向函数调用者返回不同的值，例如 JSON 或 XML 文档。

    @FunctionName("WriteOneDocOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<String> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate random ID
        final int id = Math.abs(new Random().nextInt());

        // Generate document
        final String jsonDocument = "{\"id\":\"" + id + "\", " +
                                    "\"description\": \"" + name + "\"}";

        context.getLogger().info("Document to be saved: " + jsonDocument);

        // Set outputItem's value to the JSON document to be saved
        outputItem.setValue(jsonDocument);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Document created successfully.")
                      .build();
    }

HTTP 触发器，通过 OutputBinding 将多个文档保存到数据库

以下示例显示了 Java 函数，该函数通过 OutputBinding<T> 输出参数将多个文档写入 Azure Cosmos DB。 在此示例中，需使用 outputItem 为 @CosmosDBOutput 参数提供注释，而不要使用函数签名。 输出参数 outputItem 有一个 ToDoItem 对象列表作为其模板参数类型。 使用 OutputBinding<T>，让函数可以利用绑定将文档写入 Azure Cosmos DB，同时还可向函数调用者返回不同的值，例如 JSON 或 XML 文档。

    @FunctionName("WriteMultipleDocsOutputBinding")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req",
              methods = {HttpMethod.GET, HttpMethod.POST},
              authLevel = AuthorizationLevel.ANONYMOUS)
            HttpRequestMessage<Optional<String>> request,
            @CosmosDBOutput(name = "database",
              databaseName = "ToDoList",
              collectionName = "Items",
              connectionStringSetting = "Cosmos_DB_Connection_String")
            OutputBinding<List<ToDoItem>> outputItem,
            final ExecutionContext context) {

        // Parse query parameter
        String query = request.getQueryParameters().get("desc");
        String name = request.getBody().orElse(query);

        // Item list
        context.getLogger().info("Parameters are: " + request.getQueryParameters());

        // Generate documents
        List<ToDoItem> items = new ArrayList<>();

        for (int i = 0; i < 5; i ++) {
          // Generate random ID
          final int id = Math.abs(new Random().nextInt());

          // Create ToDoItem
          ToDoItem item = new ToDoItem(String.valueOf(id), name);

          items.add(item);
        }

        // Set outputItem's value to the list of POJOs to be saved
        outputItem.setValue(items);
        context.getLogger().info("Document to be saved: " + items);

        // return a different document to the browser or calling client.
        return request.createResponseBuilder(HttpStatus.OK)
                      .body("Documents created successfully.")
                      .build();
    }

在 Java 函数运行时库中，对 @CosmosDBOutput 写入 Azure Cosmos DB 的参数使用注释。 注释参数类型应当为 OutputBinding<T>，其中 T 是本机 Java 类型或 POJO。

下面的示例演示如何使用输出绑定将数据写入 Azure Cosmos DB。 绑定在函数的配置文件 (functions.json) 中声明，并从队列消息中获取数据，然后写出到 Azure Cosmos DB 文档中。

{ 
  "name": "EmployeeDocument",
  "type": "cosmosDB",
  "databaseName": "MyDatabase",
  "collectionName": "MyCollection",
  "createIfNotExists": true,
  "connectionStringSetting": "MyStorageConnectionAppSetting",
  "direction": "out" 
} 

在 run.ps1 文件中，从函数返回的对象将映射到 对象，该对象将持久保存在数据库中。

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name EmployeeDocument -Value @{ 
    id = $QueueItem.name + '-' + $QueueItem.employeeId 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
} 

下面的示例演示如何将文档作为函数的输出写入 Azure Cosmos DB 数据库。 该示例取决于是使用 v1 还是 v2 Python 编程模型。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route()
@app.cosmos_db_output(arg_name="documents", 
                      database_name="DB_NAME",
                      collection_name="COLLECTION_NAME",
                      create_if_not_exists=True,
                      connection_string_setting="CONNECTION_SETTING")
def main(req: func.HttpRequest, documents: func.Out[func.Document]) -> func.HttpResponse:
    request_body = req.get_body()
    documents.set(func.Document.from_json(request_body))
    return 'OK'

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "cosmosDB",
      "direction": "out",
      "name": "doc",
      "databaseName": "demodb",
      "collectionName": "data",
      "createIfNotExists": "true",
      "connectionStringSetting": "AzureCosmosDBConnectionString"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    }
  ]
}

import azure.functions as func

def main(req: func.HttpRequest, doc: func.Out[func.Document]) -> func.HttpResponse:

    request_body = req.get_body()

    doc.set(func.Document.from_json(request_body))

    return 'OK'

特性

进程内和独立工作进程 C# 库使用特性来定义函数。 C# 脚本改用 function.json 配置文件，如 C# 脚本指南中所述。

修饰符

仅适用于 Python v2 编程模型。

对于使用修饰器定义的 Python v2 功能，支持 cosmos_db_output 上的以下属性：

对于使用 function.json 定义的 Python 函数，请参阅“配置”部分。

批注

在 Java 函数运行时库中，对写入 Azure Cosmos DB 的参数使用 @CosmosDBOutput 注释。 此注释支持以下属性：

• 名字
• connectionStringSetting
• databaseName
• collectionName
• createIfNotExists
• dataType
• partitionKey
• preferredLocations
• useMultipleWriteLocations（使用多个写入位置）

配置

仅适用于 Python v1 编程模型。

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

输出函数参数必须定义为 func.Out[func.Document]。 有关详细信息，请参阅输出示例。

Cosmos DB 输入绑定支持的参数类型取决于所用的 Functions 运行时版本、扩展包版本以及 C# 模态。