適用於 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.Blobs
- Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
- Microsoft.Azure.Functions.Worker.Extensions.Tables
先前,延伸模組一起隨附在 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# 執行模式,這可以是下列其中一項:
選擇版本以查看模式和版本的系結類型詳細資料。
隔離的背景工作進程會根據下表支援參數類型。 支援從 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 毫秒)。 間隔最多遞增至 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 。 |