共用方式為

適用於 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 繫結用於 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 的指南。

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

此版本的 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 建立並使用 CosmosClient 與其他類型。 如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱 註冊 Azure 用戶端 。

例外狀況和傳回碼

繫結 參考
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進行篩選。

下一步