Azure Functions 的 Azure Cosmos DB 觸發程序和系結概觀

這組文章說明如何在 Azure Functions 中使用 Azure Cosmos DB 繫結。 Azure Functions 支援 Azure Cosmos DB 的觸發程式、輸入和輸出系結。

動作	類型
建立或修改 Azure Cosmos DB 檔時，執行函式	觸發程序
閱讀 Azure Cosmos DB 檔	輸入繫結
將變更儲存至 Azure Cosmos DB 檔	輸出繫結

重要

此版本的 Azure Cosmos DB 繫結延伸模組支援 Azure Functions 4.x 版。如果您的應用程式仍使用 Functions 執行階段 1.x 版，請改為參閱 Azure Functions 1.x 的 Azure Cosmos DB 繫結。在 Functions v1.x 執行階段中，此繫結最初名為 DocumentDB。

支援的 API

下表指出如何從函式程式碼連線到各種 Azure Cosmos DB API：

API	Recommendation
適用於 NoSQL 的 Azure Cosmos DB	使用 Azure Cosmos DB 繫結延伸模組
適用於 MongoDB 的 Azure Cosmos DB	使用原生用戶端 SDK。
適用於資料表的 Azure Cosmos DB	使用 5.x 版或更新版本的 Azure 資料表繫結延伸模組。
適用於 Apache Cassandra 的 Azure Cosmos DB	使用原生用戶端 SDK。
適用於 Apache Gremlin 的 Azure Cosmos DB （圖形 API）	使用原生用戶端 SDK
適用於 PostgreSQL 的 Azure Cosmos DB	使用原生用戶端 SDK。

安裝擴充功能

您安裝的延伸模組 NuGet 套件取決於您在函式應用程式中使用的 C# 模式：

隔離式背景工作角色模型
內含式模型

函式會在隔離的 C# 背景工作進程中執行。若要深入瞭解，請參閱在隔離背景工作程序中執行 C# Azure Functions 的指南。

安裝擴充功能的程式會因擴充功能版本而異：

本節說明如何使用類別庫。針對 C# 文稿，您必須改為安裝延伸模組套件組合 4.x 版。

此版本的 Azure Cosmos DB 系結延伸模塊引進了使用身分識別而非秘密進行連線的能力。如需使用受控識別設定函數應用程式的教學課程，請參閱使用身分識別型連線建立函數應用程式的教學課程。

此版本也會變更您可以系結的類型，並將 v2 SDK 中的類型取代為 v3 SDK Microsoft.Azure.DocumentDBMicrosoft.Azure.Cosmos 的較新類型。深入了解這些新類型的不同方式，以及如何從 SDK 移轉指南、觸發程式、輸入系結和輸出系結範例移轉至它們。

此延伸模組版本以 NuGet 套件 4.x 版的形式提供。

藉由安裝 NuGet 套件 4.x 版，將延伸模組新增至專案。

如果您要使用 F# 撰寫應用程式，您也必須將此延伸模組設定為應用程式的啟動設定的一部分。在或的呼叫ConfigureFunctionsWorkerDefaults()ConfigureFunctionsWebApplication()中，新增接受參數的IFunctionsWorkerApplication委派。然後在該委派的主體內呼叫 ConfigureCosmosDBExtension() 物件：

let hostBuilder = new HostBuilder()
hostBuilder.ConfigureFunctionsWorkerDefaults(fun (context: HostBuilderContext) (appBuilder: IFunctionsWorkerApplicationBuilder) ->
    appBuilder.ConfigureCosmosDBExtension() |> ignore
) |> ignore

安裝搭售方案

若要能夠在應用程式中使用這個繫結延伸模組，請確定專案根目錄中的 host.json 檔案包含下列 extensionBundle 參考：

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.0.0, 5.0.0)"
    }
}

在此範例中， version 的 [4.0.0, 5.0.0) 值指示 Functions 主機使用至少 4.0.0 但小於 5.0.0的套件版本，其中包括 4.x 的所有潛在版本。此表示法可有效地在 v4.x 擴充功能套件組合的最新可用次要版本上維護您的應用程式。

可能的話，您應該使用最新的延伸套件組合主要版本，並允許執行階段自動維護最新的次要版本。您可以在延伸套件組合發行頁面上檢視最新套件組合的內容。如需詳細資訊，請參閱 Azure Functions 延伸模組套件組合。

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

繫結型別

針對 .NET 所支援的繫結類型同時取決於延伸模組版本和 C# 執行模式，這可以是下列其中一項：

隔離式背景工作角色模型
內含式模型

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

選擇版本以查看模式和版本的系結類型詳細數據。

根據下表，Azure Cosmos DB 擴充功能支持參數類型。

系結案例	參數型別
Cosmos DB 觸發程式（單一檔案）	JSON 可串行化類型¹
Cosmos DB 觸發程式（檔案批次）	`IEnumerable<T>`其中 `T` 是 JSON 可串行化類型¹
Cosmos DB 輸入（單一檔案）	JSON 可串行化類型¹
Cosmos DB 輸入（查詢傳回多個檔案）	CosmosClient `IEnumerable<T>` 其中 `T` 是 JSON 可串行化類型¹
Cosmos DB 輸出（單一檔）	JSON 可串行化類型¹
Cosmos DB 輸出（多份檔案）	`ICollector<T>` 或 `IAsyncCollector<T>` ，其中 `T` 是 JSON 可串行化類型¹

¹ 包含 JSON 資料的檔可以還原串行化為已知的純舊 CLR 物件（POCO）類型。

隔離的背景工作進程會根據下表支持參數類型。支援從 Microsoft.Azure.Cosmos系結至類型，目前為預覽狀態。

Cosmos DB 觸發程式

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

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

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

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

Cosmos DB 輸入系結

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

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

當您要函式從查詢處理多個檔案時，Cosmos DB 輸入系結可以繫結至下列類型：

類型	描述
`IEnumerable<T>`其中 `T` 是 JSON 可串行化類型	查詢所傳回之實體的列舉。每個專案都代表一份檔。
CosmosClient¹	線上到 Cosmos DB 帳戶的用戶端。
資料庫¹	線上至 Cosmos DB 資料庫的用戶端。
容器¹	線上至 Cosmos DB 容器的用戶端。

¹ 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.CosmosDB 4.4.0 或更新版本，以及 SDK 類型系結的常見相依性。

Cosmos DB 輸出系結

當您要函式寫入單一檔時，Cosmos DB 輸出系結可以繫結至下列類型：

類型	描述
JSON 可序列化型別	物件，表示檔的 JSON 內容。函式會嘗試將一般舊的CLR物件（POCO）類型串行化為 JSON 數據。

當您要函式寫入多個檔案時，Cosmos DB 輸出系結可以繫結至下列類型：

類型	描述
`T[]` 其中 `T` 是 JSON 可串行化類型	包含多個檔的陣列。每個專案都代表一份檔。

針對其他輸出案例，請直接從 Microsoft.Azure.Cosmos 建立並使用 CosmosClient 與其他類型。如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱註冊 Azure 用戶端。

SDK 系結類型

Azure Cosmos 的 SDK 類型支持處於預覽狀態。遵循適用於CosmosDB的 Python SDK 系結範例，以開始使用 Python 中的適用於 Cosmos 的 SDK 類型。

重要

使用 SDK 類型系結需要 Python v2 程式設計模型。

繫結	參數型別	範例
CosmosDB 輸入	ContainerProxy、 CosmosClient、 DatabaseProxy	`ContainerProxy`、 `CosmosClient`、 `DatabaseProxy`

例外狀況和傳回碼

繫結	參考
Azure Cosmos DB	Azure Cosmos DB 的 HTTP 狀態碼

host.json 設定

本節說明 2.x 版和更新版本中此系結可用的組態設定。 host.json檔案中的設定會套用至函式應用程式實例中的所有函式。如需函式應用程式組態設定的詳細資訊，請參閱 azure Functionshost.json 參考。

擴充功能 4.x+
函數 2.x+

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "userAgentSuffix": "MyDesiredUserAgentStamp"
        }
    }
}

屬性	預設	描述
connectionMode	`Gateway`	連線到 Azure Cosmos DB 服務時函式所使用的連線模式。選項： `Direct` 透過 TCP 直接連線到後端複本，並提供較低的延遲，並 `Gateway` 透過 HTTPS 透過前端閘道路由傳送要求。如需詳細資訊，請參閱 Azure Cosmos DB SDK 連線模式。
userAgentSuffix	n/a	將指定的字串值加入至觸發程式或系結至服務的所有要求。這可讓您更輕鬆地根據特定函式應用程式追蹤 Azure 監視器中的活動，並依 `User Agent`進行篩選。

{
    "version": "2.0",
    "extensions": {
        "cosmosDB": {
            "connectionMode": "Gateway",
            "protocol": "Https",
            "leaseOptions": {
                "leasePrefix": "prefix1"
            }
        }
    }
}

屬性	預設	描述
connectionMode	`Gateway`	連線到 Azure Cosmos DB 服務時函式所使用的連線模式。選項： `Direct` 透過 TCP 直接連線到後端複本，並提供較低的延遲，並 `Gateway` 透過 HTTPS 透過前端閘道路由傳送要求。如需詳細資訊，請參閱 Azure Cosmos DB SDK 連線模式。
協定	`Https`	連線到 Azure Cosmos DB 服務時函式所使用的連線通訊協定。如需這兩種模式的說明，請參閱這裡。
leasePrefix	n/a	要在應用程式的所有函式上使用的租用前置詞。

下一步

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-22