共用方式為


適用於 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 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

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

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

範例

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

隔離式背景工作處理序類別庫編譯的 C# 函式會在與執行階段隔離的處理序中執行。

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

此範例會參考簡單的 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);
        }
    }
}

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

由於 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());
    }

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

下列範例顯示 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,
});

下列範例顯示 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`);
    },
});

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

{
    "type": "cosmosDBTrigger",
    "name": "documents",
    "direction": "in",
    "leaseCollectionName": "leases",
    "connectionStringSetting": "<connection-app-setting>",
    "databaseName": "Tasks",
    "collectionName": "Items",
    "createLeaseCollectionIfNotExists": 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 程式設計模型

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'])

屬性

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

屬性內容 描述
[連接] 應用程式設定或設定集合的名稱,該名稱會指定如何連接到要監視的 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"。

裝飾項目

僅適用於 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 函式,請參閱組 一節。

註釋

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

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

屬性內容 描述
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"。

組態

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

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

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

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"。

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

使用方式

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

重要

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

重要

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

重要

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

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

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

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

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

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

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

連線

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

如果設定的值與單一設定完全相符,又與其他設定的開頭相符,則會使用完全相符項目。

Connection string

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

身分識別型連線

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

在此模式中,延伸模組需要下列屬性:

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

還可以設定其他屬性來自訂連線。 請參閱身分識別型連線的通用屬性

主控於 Azure Functions 服務時,以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credentialclientID 屬性指定使用者指派的身分識別,但預設會使用系統指派的身分識別。 請注意,支援以資源識別碼來設定使用者指派的身分識別。 在本機開發等其他內容中執行時,雖然這可以自訂,但仍會改用您的開發人員身分識別。 請參閱使用身分識別型連線進行本機開發

授與權限給身分識別

正在使用的任何身分識別,都必須具有執行預期動作的權限。 有關大多數 Azure 服務,意即您需要指派 Azure RBAC 的角色,利用提供這些權限的內建或自訂角色。

重要

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

Cosmos DB 不會針對資料作業使用 Azure RBAC。 反而會改用以類似概念為基礎的 Cosmos DB 內建 RBAC 系統。 您必須建立可在執行時間存取資料庫帳戶的角色指派。 擁有者等的 Azure RBAC 管理角色並不足夠。 下表會顯示通常作業中使用 Azure Cosmos DB 延伸模組時建議的內建角色。 您的應用程式可能會根據您寫入的程式碼要求額外的權限。

繫結類型 內建角色範例1
Trigger2 Cosmos DB 內建資料參與者
輸入繫結 Cosmos DB 內建資料讀取器
輸出繫結 Cosmos DB 內建資料參與者

1 這些角色無法用於 Azure RBAC 角色指派。 如需如何指派這些角色的詳細資訊,請參閱 Cosmos DB 內建 RBAC 系統文件。

2 使用身分識別時,Cosmos DB 會將容器建立視為管理作業。 其不可作為觸發程序的資料平面作業。 您必須確定在設定函式之前,先建立觸發程序所需的容器 (包括租用容器)。

下一步