適用於 Azure Functions 2.x 和更高概觀的 Azure Cosmos DB 觸發程式和系結
這組文章說明如何在 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 系結僅支援與適用於 NoSQL 的 Azure Cosmos DB 搭配使用。 從 延伸模組 5.x 開始，使用數據表記憶體系結來提供 Azure Cosmos DB for Table 的支援。 針對所有其他 Azure Cosmos DB API，您應該使用 API 的靜態用戶端從函式存取資料庫，包括 適用於 MongoDB 的 Azure Cosmos DB、 適用於 Cassandra 的 Azure Cosmos DB，以及 適用於 Apache Gremlin 的 Azure Cosmos DB。
安裝擴充功能
您安裝的延伸模組 NuGet 套件取決於您在函式應用程式中使用的 C# 模式：
函式會在隔離的 C# 背景工作進程中執行。 若要深入瞭解，請參閱 在隔離背景工作程序中執行 C# Azure Functions 的指南。
安裝擴充功能的程式會因擴充功能版本而異：
此版本的 Azure Cosmos DB 系結延伸模塊引進了使用身分識別而非秘密進行連線的能力。 如需使用受控識別設定函式應用程式的教學課程，請參閱 使用身分識別型連線建立函式應用程式教學課程。
藉由安裝 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 。
此版本的套件組合包含 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)"
}
}
若要深入瞭解，請參閱 更新延伸模組。
繫結型別
.NET 支援的系結類型取決於延伸模組版本和 C# 執行模式，這可以是下列其中一項：
已編譯 C# 函式的隔離背景工作進程類別庫會在與運行時間隔離的進程中執行。
選擇版本以查看模式和版本的系結類型詳細數據。
隔離的背景工作進程會根據下表支持參數類型。 支援從 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 可串行化類型 |
查詢所傳回之實體的列舉。 每個專案都代表一份檔。 |
| CosmosClient1 | 線上到 Cosmos DB 帳戶的用戶端。 |
| 資料庫1 | 線上至 Cosmos DB 資料庫的用戶端。 |
| 容器1 | 線上至 Cosmos DB 容器的用戶端。 |
1 若要使用這些類型，您必須參考 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參考。
{
"version": "2.0",
"extensions": {
"cosmosDB": {
"connectionMode": "Gateway",
"userAgentSuffix": "MyDesiredUserAgentStamp"
}
}
}
| 屬性 | 預設 | 描述 |
|---|---|---|
| connectionMode | Gateway |
連線到 Azure Cosmos DB 服務時函式所使用的連線模式。 選項為 Direct 和 Gateway |
| userAgentSuffix | n/a | 將指定的字串值加入至觸發程式或系結至服務的所有要求。 這可讓您更輕鬆地根據特定函式應用程式追蹤 Azure 監視器中的活動，並依 User Agent進行篩選。 |