共用方式為

Azure Functions 的 Azure 佇列記憶體觸發程式和系結概觀

  • 發行項

Azure Functions 可以在建立新的 Azure 佇列記憶體訊息時執行，而且可以在函式內寫入佇列訊息。

動作 類型
以佇列記憶體數據變更的形式執行函式 觸發程序
寫入佇列記憶體訊息 輸出繫結

安裝擴充功能

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

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

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

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

此版本可讓您系結至來自 Azure.Storage.Queues 的類型。

此版本支援透過 .NET Aspire 整合來設定觸發程式和系結。

藉由安裝 NuGet 套件 5.x 版，將延伸模組新增至您的專案。

使用 .NET CLI：

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

注意

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項目檔中。 您可能需要修改此套件組合來變更系結的版本，或尚未安裝套件組合。 若要深入瞭解，請參閱 延伸模組套件組合。

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

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

{
    "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物件 （POCO） 類型串行化為 JSON 數據。

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

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

針對其他輸出案例，請直接從 Azure.Storage.Queues 建立並使用 QueueClient 與其他類型。 如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱 註冊 Azure 用戶端 。

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 毫秒）。 間隔會遞增至 maxPollingInterval。 的預設值 maxPollingInterval 為 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 版和更新版本。 它代表訊息的編碼格式。 有效值為 base64 和 none。

下一步