適用於 Azure Functions 2.x 和更高概觀的 Azure Cosmos DB 觸發程式和系結

文章
06/13/2024

這組文章說明如何在 Azure Functions 2.x 和更新版本中使用 Azure Cosmos DB 系結。 Azure Functions 支援 Azure Cosmos DB 的觸發程式、輸入和輸出系結。

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

注意

此參考適用於 Azure Functions 2.x 版和更新版本。如需如何在 Functions 1.x 中使用這些系結的詳細資訊，請參閱 Azure Functions 1.x 的 Azure Cosmos DB 系結。

此系結最初命名為 DocumentDB。在 Azure Functions 2.x 版和更新版本中，觸發程式、系結和套件全都命名為 Azure Cosmos DB。

支援的 API

目前僅支援將 Azure Cosmos DB 繫結用於 Azure Cosmos DB for NoSQL。從延伸模組 5.x 開始，將會使用表格儲存體繫結提供對 Azure Cosmos DB for Table 的支援。對於其他所有的 Azure Cosmos DB API，您應使用 API 的靜態用戶端，以從函式存取資料庫，包括 Azure Cosmos DB for MongoDB、Azure Cosmos DB for Cassandra 和 Azure Cosmos DB for Apache Gremlin。

安裝擴充功能

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

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

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

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

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

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

此版本也會變更您可以系結的類型，並將 v2 SDK 中的類型取代為 v3 SDK Microsoft.Azure.DocumentDB Microsoft.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

安裝搭售方案

Azure Cosmos DB 系結延伸模組是延伸模組套件組合的一部分，該套件會在您的host.json項目檔中指定。您可能需要修改此套件組合來變更系結的版本，或尚未安裝套件組合。若要深入瞭解，請參閱延伸模組套件組合。

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

搭售方案 v4.x
套件組合 v2.x 和 v3.x

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

您可以從預覽延伸模組套件組合 v4 新增此版本的延伸模組，方法是在檔案中 host.json 新增或取代下列程式代碼：

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

若要深入瞭解，請參閱更新延伸模組。

您可以在函式應用程式中安裝此版本的延伸模組，方法是註冊延伸模組套件組合 2.x 或 3.x 版。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.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 建立和使用類型。

例外狀況和傳回碼

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

host.json 設定

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

Extension 4.x+
Functions 2.x+

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

屬性	預設	描述
connectionMode	`Gateway`	連線到 Azure Cosmos DB 服務時函式所使用的連線模式。選項為 `Direct` 和 `Gateway`
userAgentSuffix	n/a	將指定的字串值加入至觸發程式或系結至服務的所有要求。這可讓您更輕鬆地根據特定函式應用程式追蹤 Azure 監視器中的活動，並依 `User Agent`進行篩選。

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

屬性	預設	描述
connectionMode	`Gateway`	連線到 Azure Cosmos DB 服務時函式所使用的連線模式。選項為 `Direct` 和 `Gateway`
protocol	`Https`	連線到 Azure Cosmos DB 服務時函式所使用的連線通訊協定。如需這兩種模式的說明，請參閱這裡。
leasePrefix	n/a	要在應用程式的所有函式上使用的租用前置詞。

分享方式：