Azure Cosmos DB output binding for Azure Functions 2.x and higher

Azure Functions 支援兩種 Python 程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

本文支援這兩種程序設計模型。

您可以使用下列其中一種 C# 模式來建立 C# 函式：

• 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 獨立工作程序必須支援在 LTS 及非 LTS 版本 .NET 與 .NET 框架上運行的 C# 函式。 孤立工作程序函式的擴充功能使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
• 同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。 進行中功能的擴充功能使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

目前這款綁定沒有 Go 支援。

• 佇列觸發程式，透過傳回值將訊息儲存至資料庫
• 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 functions 執行時函式庫 中使用寫入 Azure Cosmos DB 的參數 @CosmosDBOutput 註解。 註解參數類型應為 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 檔案中，從 函式傳回的對象會對應至EmployeeDocument資料庫中保存的物件。

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函數，請參見 Configuration 章節。

註釋

從 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# 形式。