適用於 Azure Functions 的 Azure 佇列儲存體觸發程序和繫結概觀

Azure Functions 可以在建立新的 Azure 佇列儲存體訊息時執行,而且可以在函式內撰寫佇列訊息。

動作 類型
當佇列儲存體資料變更時執行函式 觸發程序
撰寫佇列儲存體訊息 輸出繫結

安裝擴充功能

您安裝的 NuGet 套件擴充取決於您在函數應用程式中使用的 C# 模式:

函式會在隔離的 C# 背景工作處理序中執行。 若要深入了解,請參閱在隔離式背景工作處理序中執行 C# Azure Functions 的指南

擴充的功能會根據擴充版本而有所不同:

從這個版本開始可以使用身分識別而非祕密來連線。 有關使用受控識別設定函數應用程式的教學課程,請參閱使用身分識別型連線建立函數應用程式的教學課程

此版本可讓您繫結至 Azure.Storage.Queues 中的類型。

安裝 NuGet 套件 5.x 版本將此延伸模組新增至專案。

使用 .NET CLI:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues --version 5.0.0

注意

Azure Blob、Azure 佇列和 Azure 資料表現在使用個別的延伸模組,並個別參考。 例如,若要針對 .NET 內含式應用程式中的所有三個服務使用觸發程序和繫結,您應該將下列套件新增至專案:

先前,延伸模組一起隨附在 Microsoft.Azure.Functions.Worker.Extensions.Storage 4.x 版中。 上述套件也有 5.x 版,只參考 Blob 和佇列的分割套件。 從舊版升級套件參考時,您可能需要另外參考新的 Microsoft.Azure.Functions.Worker.Extensions.Tables NuGet 套件。 此外,參考這些較新的分割套件時,請確定您未參考舊版的合併儲存體套件,因為這會導致相同繫結的兩個定義發生衝突。

安裝搭售方案

Blob 儲存體繫結是延伸模組搭售方案的一部分,由 host.json 專案檔所指定。 您可能需要修改此搭售方案來變更繫結的版本,否則就是搭售方案尚未安裝。 若要深入了解,請參閱擴充搭售方案

從這個版本開始可以使用身分識別而非祕密來連線。 有關使用受控識別設定函數應用程式的教學課程,請參閱使用身分識別型連線建立函數應用程式的教學課程

您可以在 host.json 檔案中新增或取代下列程式碼,以從預覽延伸模組組合 v3 中新增此版本的延伸模組:

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

若要深入了解,請參閱更新您的延伸模組

繫結型別

.NET 支援的系結類型取決於延伸模組版本和 C# 執行模式,這可以是下列其中一項:

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

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

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

佇列觸發程式

佇列觸發程式可以系結至下列類型:

類型 描述
string 訊息內容做為字串。 當訊息為簡單文字時,請使用 。
byte[] 訊息的位元組。
JSON 可序列化類型 當佇列訊息包含 JSON 資料時,Functions 會嘗試將 JSON 資料還原序列化為純舊 CLR 物件, (POCO) 類型。
QueueMessage1 訊息。
BinaryData1 訊息的位元組。

1 若要使用這些類型,您必須參考 Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues 5.2.0 或更新版本 ,以及 SDK 類型系結的通用相依性

佇列輸出系結

當您想要函式寫入單一訊息時,佇列輸出系結可以系結至下列類型:

類型 描述
string 訊息內容做為字串。 請在訊息是簡單文字時使用。
byte[] 訊息的位元組。
JSON 可序列化類型 物件,表示 JSON 訊息的內容。 函式會嘗試將一般舊 CLR 物件序列化為 JSON 資料, (POCO) 類型。

當您想要函式寫入多個訊息時,佇列輸出系結可以系結至下列類型:

類型 描述
T[] 其中 T 是其中一種單一訊息類型 包含多個訊息內容的陣列。 每個專案都代表一則訊息。

針對其他輸出案例,直接從 Azure.Storage.Queues 建立和使用類型。

host.json 設定

本區段說明在 2.x 版本和更新版本中,可用於此繫結的組態設定。 host.json 檔案中的設定會套用至所有函數應用程式執行個體中的函式。 下面的範例 host.json 檔案僅包含此繫結的 2.x+ 版本設定。 如需 2.x 版本和更新版本中函數應用程式組態設定的詳細資訊,請參閱 Azure Functions 的 host.json 參考

注意

有關 Functions 1.x 中 host.json 的參考,請參閱適用於 Azure Functions 1.x 的 host.json 參考

{
    "version": "2.0",
    "extensions": {
        "queues": {
            "maxPollingInterval": "00:00:02",
            "visibilityTimeout" : "00:00:30",
            "batchSize": 16,
            "maxDequeueCount": 5,
            "newBatchThreshold": 8,
            "messageEncoding": "base64"
        }
    }
}
屬性 預設 描述
maxPollingInterval 00:01:00 佇列輪詢之間的間隔上限。 最小間隔為 00:00:00.100 (100 毫秒)。 間隔最多遞增至 maxPollingIntervalmaxPollingInterval 的預設值為 00:01:00 (1 分鐘)。 maxPollingInterval 不得小於 00:00:00.100 (100 毫秒)。 在 Functions 2.x 和更新版本中,資料類型是 TimeSpan。 在 Functions 1.x 中以毫秒為單位。
visibilityTimeout 00:00:00 處理訊息失敗時,重試之間的時間間隔。
batchSize 16 Functions 執行階段會同時擷取,並以平行方式處理的佇列訊息數目。 當要處理的數目減少到 newBatchThreshold 時,執行階段就會取得另一個批次,並開始處理那些訊息。 因此,每個函式並行處理之訊息的上限為 batchSize 加上 newBatchThreshold。 這項限制個別套用至每個佇列觸發的函式。

如果您需要避免平行執行在單一佇列上收到的訊息,可以將 batchSize 設定為 1。 不過,只要您的函數應用程式只在單一虛擬機器 (VM) 上執行,此設定就會排除並行。 如果函式應用程式相應放大為多個 VM,則每個 VM 可以執行每個佇列觸發之函式的一個執行個體。

最大值 batchSize 為 32。
maxDequeueCount 5 將訊息移至有害佇列之前,嘗試處理訊息的次數。
newBatchThreshold N*batchSize/2 每當要同時處理的訊息數目下降至這個數字時,執行階段就會擷取另一個批次。

N 代表在 App Service 或進階方案上執行時可用的 vCPU 數目。 在取用方案中值為 1
messageEncoding base64 此設定僅適用於延伸模組組合 5.0.0 版和更新版本。 代表訊息的編碼格式。 有效值為 base64none

後續步驟