適用於 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 進行篩選。 |