適用於 Azure Functions 2.x 和更新版本的 Azure Cosmos DB 觸發程式

Azure Cosmos DB 觸發程式會使用 Azure Cosmos DB 變更摘要 來接聽分割區的插入和更新。 變更摘要會發佈新的和更新的專案，不包括刪除的更新。

如需安裝和組態詳細數據的詳細資訊，請參閱概 觀。

取用和 進階版 方案的 Cosmos DB 調整決策是透過以目標為基礎的調整來完成。 如需詳細資訊，請參閱 以目標為基礎的調整。

重要

本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。 如需 v4 模型運作方式的詳細資訊，請參閱 Azure Functions Node.js開發人員指南。 若要深入瞭解 v3 與 v4 之間的差異，請參閱 移轉指南。

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

v2

Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。

v1

Python v1 程式設計模型需要您在函式資料夾中的個別 function.json 檔案中定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。

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

範例

觸發程式的使用方式取決於函式應用程式中所使用的擴充套件版本和 C# 形式，這可以是下列其中一項：

隔離式背景工作角色模型

已編譯 C# 函式的隔離背景工作進程類別庫會在與運行時間隔離的進程中執行。

內含式模型

重要

支援將於 2026 年 11 月 10 日結束進程模型。 強烈建議您將 應用程式移轉至隔離的背景工作模型 ，以取得完整支援。

同進程類別庫是在與 Functions 執行時間相同的進程中執行的已編譯 C# 函式。

下列範例取決於指定 C# 模式的延伸模組版本。

Extension 4.x+

使用 Azure Cosmos DB 擴充功能 4.x 版或更高版本的應用程式有不同的屬性屬性，如下所示。 此範例會參考簡單的 ToDoItem 類型。

namespace CosmosDBSamplesV2
{
    // Customize the model with your own desired properties
    public class ToDoItem
    {
        public string id { get; set; }
        public string Description { get; set; }
    }
}

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

namespace CosmosDBSamplesV2
{
    public static class CosmosTrigger
    {
        [FunctionName("CosmosTrigger")]
        public static void Run([CosmosDBTrigger(
            databaseName: "databaseName",
            containerName: "containerName",
            Connection = "CosmosDBConnectionSetting",
            LeaseContainerName = "leases",
            CreateLeaseContainerIfNotExists = true)]IReadOnlyList<ToDoItem> input, ILogger log)
        {
            if (input != null && input.Count > 0)
            {
                log.LogInformation("Documents modified " + input.Count);
                log.LogInformation("First document Id " + input[0].id);
            }
        }
    }
}

Functions 2.x+

下列範例示範 在指定的資料庫和集合中有插入或更新時叫用的 C# 函 式。

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

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

Extension 4.x+

此範例會參考簡單的 ToDoItem 類型：

public class ToDoItem
{
    public string? Id { get; set; }
    public string? Description { get; set; }
}

當指定的資料庫和集合中有插入或更新時，會叫用下列函式。

[Function("CosmosTrigger")]
public void Run([CosmosDBTrigger(
    databaseName: "ToDoItems",
    containerName:"TriggerItems",
    Connection = "CosmosDBConnection",
    LeaseContainerName = "leases",
    CreateLeaseContainerIfNotExists = true)] IReadOnlyList<ToDoItem> todoItems,
    FunctionContext context)
{
    if (todoItems is not null && todoItems.Any())
    {
        foreach (var doc in todoItems)
        {
            _logger.LogInformation("ToDoItem: {desc}", doc.Description);
        }
    }
}

Functions 2.x+

下列程式代碼會 MyDocument 定義類型：

public class MyDocument
{
    public string Id { get; set; }

    public string Text { get; set; }

    public int Number { get; set; }

    public bool Boolean { get; set; }
}

IReadOnlyList<T>使用 作為下列範例中的 Azure Cosmos DB 觸發程式係結參數：

[Function(nameof(CosmosDBFunction))]
[ExponentialBackoffRetry(5, "00:00:04", "00:15:00")]
[CosmosDBOutput("%CosmosDb%", "%CosmosContainerOut%", Connection = "CosmosDBConnection", CreateIfNotExists = true)]
public object Run(
    [CosmosDBTrigger(
        "%CosmosDb%",
        "%CosmosContainerIn%",
        Connection = "CosmosDBConnection",
        LeaseContainerName = "leases",
        CreateLeaseContainerIfNotExists = true)] IReadOnlyList<MyDocument> input,
    FunctionContext context)
{
    if (input != null && input.Any())
    {
        foreach (var doc in input)
        {
            _logger.LogInformation("Doc Id: {id}", doc.Id);
        }

        // Cosmos Output
        return input.Select(p => new { id = p.Id });
    }

    return null;
}

此範例需要下列 using 語句：

using System.Collections.Generic;
using System.Linq;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

當指定的資料庫和容器中有插入或更新時，會叫用此函式。

Extension 4.x+

由於 Azure Cosmos DB SDK 中的架構變更，Azure Cosmos DB 擴充功能 4.x 版需要 適用於 Java 函式的 azure-functions-java-library V3.0.0 。

    @FunctionName("CosmosDBTriggerFunction")
    public void run(
        @CosmosDBTrigger(
            name = "items",
            databaseName = "ToDoList",
            containerName = "Items",
            leaseContainerName="leases",
            connection = "AzureCosmosDBConnection",
            createLeaseContainerIfNotExists = true
        )
        Object inputItem,
        final ExecutionContext context
    ) {
        context.getLogger().info("Items modified: " + inputItems.size());
    }

Functions 2.x+

    @FunctionName("cosmosDBMonitor")
    public void cosmosDbProcessor(
        @CosmosDBTrigger(name = "items",
            databaseName = "ToDoList",
            collectionName = "Items",
            leaseCollectionName = "leases",
            createLeaseCollectionIfNotExists = true,
            connectionStringSetting = "AzureCosmosDBConnection") String[] items,
            final ExecutionContext context ) {
                context.getLogger().info(items.length + "item(s) is/are changed.");
            }

在 Java 函式運行時間連結庫中，對 @CosmosDBTrigger 值來自 Azure Cosmos DB 的參數使用註釋。 此批注可以搭配原生 Java 類型、POJO 或使用 可為 Null 的值使用 Optional<T>。

模型 v4

下列範例顯示 Azure Cosmos DB 觸發程式 TypeScript 函式。 新增或修改 Azure Cosmos DB 記錄時，函式會寫入記錄訊息。

import { app, InvocationContext } from '@azure/functions';

export async function cosmosDBTrigger1(documents: unknown[], context: InvocationContext): Promise<void> {
    context.log(`Cosmos DB function processed ${documents.length} documents`);
}

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: cosmosDBTrigger1,
});

模型 v3

Model v3 不會記載 TypeScript 範例。

模型 v4

下列範例顯示 Azure Cosmos DB 觸發 程式 JavaScript 函式。 新增或修改 Azure Cosmos DB 記錄時，函式會寫入記錄訊息。

const { app } = require('@azure/functions');

app.cosmosDB('cosmosDBTrigger1', {
    connection: '<connection-app-setting>',
    databaseName: 'Tasks',
    containerName: 'Items',
    createLeaseContainerIfNotExists: true,
    handler: (documents, context) => {
        context.log(`Cosmos DB function processed ${documents.length} documents`);
    },
});

模型 v3

下列範例示範function.json檔案中的 Azure Cosmos DB 觸發程式系結，以及使用系結的 JavaScript 函式。 新增或修改 Azure Cosmos DB 記錄時，函式會寫入記錄訊息。

以下是 function.json 檔案中的繫結資料：

Functions 2.x+

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

Functions 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

請注意，某些系結屬性名稱在 Azure Cosmos DB 擴充功能 4.x 版中有所變更。

以下是 JavaScript 程式代碼：

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

下列範例示範如何在 Azure Cosmos DB 中執行函式作為數據變更。

Functions 2.x+

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

Functions 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

請注意，某些系結屬性名稱在 Azure Cosmos DB 擴充功能 4.x 版中有所變更。

在 run.ps1 檔案中，您可以存取透過 $Documents 參數觸發函式的檔。

param($Documents, $TriggerMetadata) 

Write-Host "First document Id modified : $($Documents[0].id)" 

下列範例顯示 Azure Cosmos DB 觸發程式系結。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

v2

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="CosmosDBTrigger")
@app.cosmos_db_trigger(name="documents", 
                       connection="CONNECTION_SETTING",
                       database_name="DB_NAME", 
                       container_name="CONTAINER_NAME", 
                       lease_container_name="leases",
                       create_lease_container_if_not_exists="true")
def test_function(documents: func.DocumentList) -> str:
    if documents:
        logging.info('Document id: %s', documents[0]['id'])

v1

修改 Azure Cosmos DB 記錄時，函式會寫入記錄訊息。 以下是 function.json 檔案中的繫結資料：

Functions 2.x+

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

Functions 4.x+

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseContainerName": "leases",
    "connection": "<connection-app-setting>",
    "databaseName": "Tasks",
    "containerName": "Items",
    "createLeaseContainerIfNotExists": true
}

請注意，某些系結屬性名稱在 Azure Cosmos DB 擴充功能 4.x 版中有所變更。

以下是 Python 程式代碼：

    import logging
    import azure.functions as func


    def main(documents: func.DocumentList) -> str:
        if documents:
            logging.info('First document Id modified: %s', documents[0]['id'])

屬性

內含式和隔離程序 C# 程式庫都會使用 CosmosDBTriggerAttribute 來定義函式。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

Extension 4.x+

Attribute 屬性	描述
[連接]	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
DatabaseName	該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
ContainerName	要監視的容器名稱。
LeaseConnection	(選用) 應用程式設定或設定集合的名稱，該名稱會指定如何連接到保存租用容器的 Azure Cosmos DB 帳戶。 如果未設定，會使用 Connection 值。 在入口網站中建立繫結時，會自動設定此參數。 租用容器的連接字串必須具有寫入權限。
LeaseDatabaseName	(選擇性) 保存租用儲存容器的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
LeaseContainerName	(選擇性) 用來儲存租用的容器名稱。 如果未設定，會使用 leases 值。
CreateLeaseContainerIfNotExists	(選擇性) 設為 true 時，如果租用容器尚未存在，即會自動加以建立。 預設值是 false。 使用 Microsoft Entra 身分識別時，如果您將值設定為 true，則建立容器是不允許的作業，函式也將無法啟動。
LeasesContainerThroughput	(選擇性) 定義要在建立租用容器時指派的要求單位數。 只有在將 CreateLeaseContainerIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
LeaseContainerPrefix	(選擇性) 設定時，系統會將值新增為此函式租用容器中建立的租用前置詞。 使用前置詞可讓兩個個別 Azure Functions 透過不同的前置詞，來共用相同的租用容器。
FeedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
LeaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
LeaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
LeaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
MaxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視容器中的作業是透過預存程序執行，那麼從變更摘要讀取項目時會保留異動範圍。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
StartFromBeginning	(選擇性) 此選項會告知觸發程序從容器的變更歷程記錄開頭讀取變更，而非當前的時間開頭。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
StartFromTime	(選擇性) 取得或設定要初始化變更摘要讀取作業的開始日期和時間。 建議的格式是 ISO 8601 包含 UTC 指示項，例如 2021-02-16T14:19:29Z。 此項目僅用於設定初始觸發程序狀態。 一旦觸發程序具有租用狀態之後，變更此值不會有任何作用。
PreferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。

Functions 2.x+

Attribute 屬性	描述
ConnectionStringSetting	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
DatabaseName	受監視集合的 Azure Cosmos DB 資料庫名稱。
CollectionName	正在監視的集合名稱。
LeaseConnectionStringSetting	（選擇性）應用程式設定或設定集合的名稱，指定如何連線到保存租用集合的 Azure Cosmos DB 帳戶。 如果未設定，會使用 ConnectionStringSetting 值。 在入口網站中建立繫結時，會自動設定此參數。 租用集合 連接字串 必須具有寫入許可權。
LeaseDatabaseName	（選擇性）保存用來儲存租用之集合的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
LeaseCollectionName	（選擇性）用來儲存租用的集合名稱。 如果未設定，會使用 leases 值。
CreateLeaseCollectionIfNotExists	（選擇性）當設定為 true時，租用集合會在不存在時自動建立。 預設值是 false。
LeasesCollectionThroughput	（選擇性）定義建立租用集合時要指派的要求單位數目。 只有在將 CreateLeaseCollectionIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
LeaseCollectionPrefix	（選擇性）設定時，值會新增為此函式之 Lease 集合中建立的租用前置詞。 使用前置詞可讓兩個不同的 Azure Functions 使用不同的前置詞來共用相同的租用集合。
FeedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
LeaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
LeaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
LeaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
CheckpointInterval	（選擇性）設定時，它會以毫秒為單位定義租用檢查點之間的間隔。 預設一律在每個函數調用之後。
CheckpointDocumentCount	（選擇性）自訂租用檢查點之間的文件數量。 預設值是在每個函式呼叫之後。
MaxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視集合中的作業是透過預存程式執行， 則會在從變更摘要讀取專案時保留交易範圍 。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
StartFromBeginning	（選擇性）此選項會告知觸發程式從集合變更歷程記錄的開頭讀取變更，而不是從目前時間開始。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
PreferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。
UseMultipleWriteLocations	（選擇性）啟用多區域帳戶以寫入租用集合。
UseDefaultJsonSerialization	（選擇性）可讓您 JsonConvert.DefaultSettings 在受監視的集合中使用。 此設定僅適用於受監視的集合和取用者，以設定受監視集合中使用的串行化。 JsonConvert.DefaultSettings必須在衍生自 CosmosDBWebJobsStartup類別中設定 。

Extension 4.x+

Attribute 屬性	描述
[連接]	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
DatabaseName	該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
ContainerName	要監視的容器名稱。
LeaseConnection	(選用) 應用程式設定或設定集合的名稱，該名稱會指定如何連接到保存租用容器的 Azure Cosmos DB 帳戶。 如果未設定，會使用 Connection 值。 在入口網站中建立繫結時，會自動設定此參數。 租用容器的連接字串必須具有寫入權限。
LeaseDatabaseName	(選擇性) 保存租用儲存容器的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
LeaseContainerName	(選擇性) 用來儲存租用的容器名稱。 如果未設定，會使用 leases 值。
CreateLeaseContainerIfNotExists	(選擇性) 設為 true 時，如果租用容器尚未存在，即會自動加以建立。 預設值是 false。 使用 Microsoft Entra 身分識別時，如果您將值設定為 true，則建立容器是不允許的作業，函式也將無法啟動。
LeasesContainerThroughput	(選擇性) 定義要在建立租用容器時指派的要求單位數。 只有在將 CreateLeaseContainerIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
LeaseContainerPrefix	(選擇性) 設定時，系統會將值新增為此函式租用容器中建立的租用前置詞。 使用前置詞可讓兩個個別 Azure Functions 透過不同的前置詞，來共用相同的租用容器。
FeedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
LeaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
LeaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
LeaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
MaxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視容器中的作業是透過預存程序執行，那麼從變更摘要讀取項目時會保留異動範圍。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
StartFromBeginning	(選擇性) 此選項會告知觸發程序從容器的變更歷程記錄開頭讀取變更，而非當前的時間開頭。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
StartFromTime	(選擇性) 取得或設定要初始化變更摘要讀取作業的開始日期和時間。 建議的格式是 ISO 8601 包含 UTC 指示項，例如 2021-02-16T14:19:29Z。 此項目僅用於設定初始觸發程序狀態。 一旦觸發程序具有租用狀態之後，變更此值不會有任何作用。
PreferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。

Functions 2.x+

Attribute 屬性	描述
ConnectionStringSetting	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
DatabaseName	受監視集合的 Azure Cosmos DB 資料庫名稱。
CollectionName	正在監視的集合名稱。
LeaseConnectionStringSetting	（選擇性）應用程式設定或設定集合的名稱，指定如何連線到保存租用集合的 Azure Cosmos DB 帳戶。 如果未設定，會使用 ConnectionStringSetting 值。 在入口網站中建立繫結時，會自動設定此參數。 租用集合的 連接字串 必須具有寫入許可權。
LeaseDatabaseName	（選擇性）保存用來儲存租用之集合的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
LeaseCollectionName	（選擇性）用來儲存租用的集合名稱。 如果未設定，會使用 leases 值。
CreateLeaseCollectionIfNotExists	（選擇性）當設定為 true時，租用集合會在不存在時自動建立。 預設值是 false。
LeasesCollectionThroughput	（選擇性）定義建立租用集合時要指派的要求單位數目。 只有在將 CreateLeaseCollectionIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
LeaseCollectionPrefix	（選擇性）設定時，值會新增為此函式之 Lease 集合中建立的租用前置詞。 使用前置詞可讓兩個不同的 Azure Functions 使用不同的前置詞來共用相同的租用集合。
FeedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
LeaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
LeaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
LeaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
CheckpointInterval	（選擇性）設定時，它會以毫秒為單位定義租用檢查點之間的間隔。 預設一律在每個函數調用之後。
CheckpointDocumentCount	（選擇性）自訂租用檢查點之間的文件數量。 預設值是在每個函式呼叫之後。
MaxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視集合中的作業是透過預存程式執行， 則會在從變更摘要讀取專案時保留交易範圍 。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
StartFromBeginning	（選擇性）此選項會告知觸發程式從集合變更歷程記錄的開頭讀取變更，而不是從目前時間開始。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
PreferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。
UseMultipleWriteLocations	（選擇性）啟用多區域帳戶以寫入租用集合。
UseDefaultJsonSerialization	（選擇性）可讓您 JsonConvert.DefaultSettings 在受監視的集合中使用。 此設定僅適用於受監視的集合和取用者，以設定受監視集合中使用的串行化。 JsonConvert.DefaultSettings必須在衍生自 CosmosDBWebJobsStartup類別中設定 。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，在上 cosmos_db_trigger具有下列屬性：

屬性	說明
arg_name	函式程式碼中使用的變數名稱，代表有變更的文件清單。
database_name	受監視集合的 Azure Cosmos DB 資料庫名稱。
collection_name	要監視的 Azure Cosmos DB 集合名稱。
connection	正在監視的 Azure Cosmos DB 連接字串。

如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。

註釋

Extension 4.x+

由於 Azure Cosmos DB SDK 中的架構變更，Azure Cosmos DB 擴充功能 4.x 版需要 適用於 Java 函式的 azure-functions-java-library V3.0.0 。

在 @CosmosDBTrigger 從 Azure Cosmos DB 讀取數據的參數上使用註釋。 註解支援下列屬性：

Attribute 屬性	描述
connection	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
name	函數的名稱。
databaseName	該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
containerName	要監視的容器名稱。
leaseConnectionStringSetting	(選用) 應用程式設定或設定集合的名稱，該名稱會指定如何連接到保存租用容器的 Azure Cosmos DB 帳戶。 如果未設定，會使用 Connection 值。 在入口網站中建立繫結時，會自動設定此參數。 租用容器的連接字串必須具有寫入權限。
leaseDatabaseName	(選擇性) 保存租用儲存容器的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
leaseContainerName	(選擇性) 用來儲存租用的容器名稱。 如果未設定，會使用 leases 值。
createLeaseContainerIfNotExists	(選擇性) 設為 true 時，如果租用容器尚未存在，即會自動加以建立。 預設值是 false。 如果您將值設定為 true，則使用 Microsoft Entra 身分識別時，建立容器不是 允許的作業 ，而且您的函式不會啟動。
leasesContainerThroughput	(選擇性) 定義要在建立租用容器時指派的要求單位數。 只有在將 CreateLeaseContainerIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
leaseContainerPrefix	(選擇性) 設定時，系統會將值新增為此函式租用容器中建立的租用前置詞。 使用前置詞可讓兩個個別 Azure Functions 透過不同的前置詞，來共用相同的租用容器。
feedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
leaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
leaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 如果租用未在此間隔內更新，則會過期，且分割區的擁有權會移至另一個實例。 預設值為 60000 (60 秒)。
leaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
maxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視容器中的作業是透過預存程序執行，那麼從變更摘要讀取項目時會保留異動範圍。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
startFromBeginning	(選擇性) 此選項會告知觸發程序從容器的變更歷程記錄開頭讀取變更，而非當前的時間開頭。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
preferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。

Functions 2.x+

從 Java 函式運行時間連結庫，對從 Azure Cosmos DB 讀取資料的參數使用@CosmosDBTrigger批注。 註解支援下列屬性：

• name
• connectionStringSetting
• databaseName
• collectionName
• leaseConnectionStringSetting
• leaseDatabaseName
• leaseCollectionName
• createLeaseCollectionIfNotExists
• leasesCollectionThroughput
• leaseCollectionPrefix
• feedPollDelay
• leaseAcquireInterval
• leaseExpirationInterval
• leaseRenewInterval
• checkpointInterval
• checkpointDocumentCount
• maxItemsPerInvocation
• startFromBeginning
• preferredLocations

組態

僅適用於 Python v1 程式設計模型。

模型 v4

下表說明您可以在傳遞至 app.cosmosDB() 方法的物件options上設定的屬性。 type、 direction和 name 屬性不適用於 v4 模型。

模型 v3

下表說明您在 function.json 檔案中設定的系結組態屬性，其中屬性與延伸模組版本不同：

下表說明您在 function.json 檔案中設定的系結組態屬性，其中屬性與延伸模組版本不同：

Extension 4.x+

function.json 屬性	描述
type	必須設定為 cosmosDBTrigger。
direction	必須設定為 in。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此參數。
name	函式程式碼中使用的變數名稱，代表有變更的文件清單。
connection	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
databaseName	該 Azure Cosmos DB 資料庫名稱含有要監視的容器。
containerName	要監視的容器名稱。
leaseConnection	(選擇性) 應用程式設定或設定容器的名稱，該名稱會指定如何連接到保存租用容器的 Azure Cosmos DB 帳戶。 如果未設定，會使用 connection 值。 在入口網站中建立繫結時，會自動設定此參數。 租用容器的連接字串必須具有寫入權限。
leaseDatabaseName	(選擇性) 保存租用儲存容器的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
leaseContainerName	(選擇性) 用來儲存租用的容器名稱。 如果未設定，會使用 leases 值。
createLeaseContainerIfNotExists	(選擇性) 設為 true 時，如果租用容器尚未存在，即會自動加以建立。 預設值是 false。 使用 Microsoft Entra 身分識別時，如果您將值設定為 true，則建立容器是不允許的作業，函式也將無法啟動。
leasesContainerThroughput	(選擇性) 定義要在建立租用容器時指派的要求單位數。 只有在將 createLeaseContainerIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
leaseContainerPrefix	(選擇性) 設定時，系統會將值新增為此函式租用容器中建立的租用前置詞。 使用前置詞可讓兩個個別 Azure Functions 透過不同的前置詞，來共用相同的租用容器。
feedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
leaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
leaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
leaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
maxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視容器中的作業是透過預存程序執行，那麼從變更摘要讀取項目時會保留異動範圍。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
startFromBeginning	(選擇性) 此選項會告知觸發程序從容器的變更歷程記錄開頭讀取變更，而非當前的時間開頭。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
startFromTime	(選擇性) 取得或設定要初始化變更摘要讀取作業的開始日期和時間。 建議的格式是 ISO 8601 包含 UTC 指示項，例如 2021-02-16T14:19:29Z。 此項目僅用於設定初始觸發程序狀態。 一旦觸發程序具有租用狀態之後，變更此值不會有任何作用。
preferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。

Functions 2.x+

function.json 屬性	描述
type	必須設定為 cosmosDBTrigger。
direction	必須設定為 in。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此參數。
name	函式程式碼中使用的變數名稱，代表有變更的文件清單。
connectionStringSetting	應用程式設定或設定集合的名稱，該名稱會指定如何連接到要監視的 Azure Cosmos DB 帳戶。 如需詳細資訊，請參閱連線。
databaseName	受監視集合的 Azure Cosmos DB 資料庫名稱。
collectionName	正在監視的集合名稱。
leaseConnectionStringSetting	（選擇性）應用程式設定或設定集合的名稱，指定如何連線到保存租用集合的 Azure Cosmos DB 帳戶。 如果未設定，會使用 connectionStringSetting 值。 在入口網站中建立繫結時，會自動設定此參數。 租用集合的 連接字串 必須具有寫入許可權。
leaseDatabaseName	（選擇性）保存用來儲存租用之集合的資料庫名稱。 如果未設定，會使用 databaseName 設定的值。
leaseCollectionName	（選擇性）用來儲存租用的集合名稱。 如果未設定，會使用 leases 值。
createLeaseCollectionIfNotExists	（選擇性）當設定為 true時，租用集合會在不存在時自動建立。 預設值是 false。
leasesCollectionThroughput	（選擇性）定義建立租用集合時要指派的要求單位數目。 只有在將 createLeaseCollectionIfNotExists 設為 true 時才會使用此設定。 使用入口網站建立繫結時，會自動設定此參數。
leaseCollectionPrefix	（選擇性）設定時，值會新增為此函式之 Lease 集合中建立的租用前置詞。 使用前置詞可讓兩個不同的 Azure Functions 使用不同的前置詞來共用相同的租用集合。
feedPollDelay	(選擇性) 在目前所有的變更都清空後，每次輪詢分割區以了解摘要上是否有新變更時所要延遲的時間 (以毫秒為單位)。 預設值為 5,000 毫秒或 5 秒。
leaseAcquireInterval	(選擇性) 如果設定，將會以毫秒為單位定義啟動工作以計算分割區是否平均分散到已知主機執行個體的間隔。 預設值為 13000 (13 秒)。
leaseExpirationInterval	(選擇性) 如果設定，將會以毫秒為單位定義租用代表分割區的間隔。 未在此間隔內更新的租用將會過期，且分割區的擁有權會移轉給另一個執行個體。 預設值為 60000 (60 秒)。
leaseRenewInterval	(選擇性) 如果設定，將會以毫秒為單位定義目前由執行個體保有之分割區的所有租用所適用的更新間隔。 預設值為 17000 (17 秒)。
checkpointInterval	（選擇性）設定時，它會以毫秒為單位定義租用檢查點之間的間隔。 預設一律在每個函數調用之後。
checkpointDocumentCount	（選擇性）自訂租用檢查點之間的文件數量。 預設值是在每個函式呼叫之後。
maxItemsPerInvocation	(選擇性) 如果設定，此屬性會設定每個函式呼叫可收到的項目數上限。 如果受監視集合中的作業是透過預存程式執行， 則會在從變更摘要讀取專案時保留交易範圍 。 如此一來，所接收的項目數可能會高於指定的值，這樣同一次異動所變更的項目，就會在一個不可部分完成的批次中傳回。
startFromBeginning	（選擇性）此選項會告知觸發程式從集合變更歷程記錄的開頭讀取變更，而不是從目前時間開始。 因為在後續執行中，檢查點已儲存，所以從開頭讀取僅適用於觸發程序第一次啟動的情況下。 若已經建立租用，則將此選項設為 true 不會有任何作用。
preferredLocations	(選用) 定義 Azure Cosmos DB 服務中異地複寫資料庫帳戶的慣用位置 (區域)。 應該以逗號將值分隔。 例如，"East US,South Central US,North Europe"。
useMultipleWriteLocations	（選擇性）啟用多區域帳戶以寫入租用集合。

如需完整範例， 請參閱範例一節 。

使用方式

觸發程式需要它用來儲存 分割區租用 的第二個集合。 要監視的集合和包含租用的集合都必須可供觸發程序運作。

重要

如果多個函式設定為使用相同的集合使用 Azure Cosmos DB 觸發程式，則每個函式都應該使用專用租用集合，或為每個函式指定不同的 LeaseCollectionPrefix 函式。 否則，只會觸發其中一個函式。 如需前置詞的相關信息，請參閱 屬性一節。

重要

如果多個函式設定為使用相同的集合使用 Azure Cosmos DB 觸發程式，則每個函式都應該使用專用租用集合，或為每個函式指定不同的 leaseCollectionPrefix 函式。 否則，只會觸發其中一個函式。 如需前置詞的相關信息，請參閱 註釋一節。

重要

如果多個函式設定為使用相同的集合使用 Azure Cosmos DB 觸發程式，則每個函式都應該使用專用租用集合，或為每個函式指定不同的 leaseCollectionPrefix 函式。 否則，只會觸發其中一個函式。 如需前置詞的相關信息，請參閱組 態一節。

觸發程式不會指出檔是否已更新或插入，只會提供檔本身。 如果您需要以不同的方式處理更新和插入，您可以藉由實作插入或更新的時間戳欄位來執行此動作。

Azure Cosmos DB 觸發程式所支援的參數類型取決於 Functions 執行時間版本、擴充套件版本，以及所使用的 C# 形式。

Extension 4.x+

如需支援的型別清單，請參閱 系結類型 。

Functions 2.x+

如需支援的型別清單，請參閱 系結類型 。

Extension 4.x+

當您想要讓函式處理單一檔時，Cosmos DB 觸發程式可以繫結至下列類型：

類型	描述
JSON 可序列化型別	函式會嘗試將檔的 JSON 數據從 Cosmos DB 變更摘要還原串行化為純舊 CLR 物件 （POCO） 類型。

當您想要讓函式處理檔批次時，Cosmos DB 觸發程式可以繫結至下列類型：

類型	描述
IEnumerable<T>其中 T 是 JSON 可串行化類型	批次中包含的實體列舉。 每個專案都代表 Cosmos DB 變更摘要中的一份檔。

Functions 2.x+

如需支援的型別清單，請參閱 系結類型 。

連線

connectionStringSetting/connection和 leaseConnectionStringSetting/leaseConnection 屬性是環境組態的參考，其會指定應用程式應該如何連線到 Azure Cosmos DB。 他們可以指定：

• 包含 連接字串 的應用程式設定名稱
• 多個應用程式設定的共用前置詞名稱，並定義 以身分識別為基礎的連線。 此選項僅適用於 connection 4.x 版或更高版本的 和 leaseConnection 版本。

如果設定的值既與單一設定完全相符，又是其他設定的前置詞比對，則會使用完全相符專案。

連接字串

資料庫帳戶的 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的連接屬性所指定的值。

身分識別型連線

如果您使用 4.x 版或更高版本的延伸模組，而不是使用具有秘密的 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要執行此動作，您會在觸發程序和繫結設定中對應至「連線」屬性的通用前置詞下定義設定。

在此模式中，延伸模組需要下列屬性：

屬性	環境變數範本	描述	範例值
帳戶端點	<CONNECTION_NAME_PREFIX>__accountEndpoint	Azure Cosmos DB 帳戶端點 URI。	<https:// database_account_name.documents.azure.com:443/>

其他屬性可以設定為自定義連線。 請參閱 身分識別型連線的一般屬性。

主控於 Azure Functions 服務時，以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。 請注意，不支援使用資源標識符設定使用者指派的身分識別。 在其他內容中執行時，例如本機開發，會改用您的開發人員身分識別，但您可以自定義此身分識別。 請參閱 使用身分識別型連線進行本機開發。

授與權限給身分識別

正在使用的任何身分識別，都必須具有執行預期動作的權限。 對於大部分的 Azure 服務，這表示您必須 使用內建或自定義角色，在 Azure RBAC 中指派角色，以提供這些許可權。

重要

部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠從數據源讀取，請使用只有讀取許可權的角色。 指派也允許寫入該服務的角色是不適當的，因為這會是讀取作業的過度許可權。 同樣地，您會想要確保角色指派的範圍僅限於需要讀取的資源。

Cosmos DB 不會針對數據作業使用 Azure RBAC。 相反地，它會使用 以類似概念為基礎的 Cosmos DB 內建 RBAC 系統 。 您必須建立角色指派，以在運行時間提供資料庫帳戶的存取權。 Azure RBAC 管理角色，例如 擁有者 不足。 下表顯示在正常作業中使用 Azure Cosmos DB 擴充功能時建議的內建角色。 您的應用程式可能需要根據您撰寫的程式代碼來取得其他許可權。

繫結類型	範例內建角色1
觸發程式2	Cosmos DB 內建數據參與者
輸入繫結	Cosmos DB 內建數據讀取器
輸出繫結	Cosmos DB 內建數據參與者

¹ 這些角色不能用於 Azure RBAC 角色指派中。 如需如何指派這些角色的詳細資訊，請參閱 Cosmos DB 內建的 RBAC 系統檔。

² 使用身分識別時，Cosmos DB 會將容器建立視為管理作業。 它無法做為觸發程式的數據平面作業。 在設定函式之前，您必須確定您已建立觸發程式所需的容器（包括租用容器）。

下一步

• 讀取 Azure Cosmos DB 文件 (輸入繫結)
• 將變更儲存至 Azure Cosmos DB 文件 (輸出繫結)