適用於 Azure Functions 的 Azure 佇列記憶體觸發程式
佇列記憶體觸發程式會執行函式，因為訊息會新增至 Azure 佇列記憶體。
取用和 進階版 方案的 Azure 佇列記憶體調整決策是透過以目標為基礎的調整來完成。 如需詳細資訊，請參閱 以目標為基礎的調整。
重要
本文使用索引標籤來支援多個版本的Node.js程序設計模型。 v4 模型已正式推出，旨在為 JavaScript 和 TypeScript 開發人員提供更靈活的直覺式體驗。 如需 v4 模型運作方式的詳細資訊，請參閱 Azure Functions Node.js開發人員指南。 若要深入瞭解 v3 與 v4 之間的差異，請參閱 移轉指南。
Azure Functions 支援兩種適用於 Python 的程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。
Python v2 程式設計模型可讓您直接在 Python 函式程式代碼中使用裝飾項目來定義系結。 如需詳細資訊，請參閱 Python 開發人員指南。
本文支援這兩種程序設計模型。
範例
當佇列上收到新專案時，請使用佇列觸發程式啟動函式。 佇列訊息會當成函式輸入提供。
您可以使用下列其中一種 C# 模式來建立 C# 函式：
- 隔離的背景工作模型：在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 需要隔離的背景工作進程，才能支援在 LTS 和非 LTS 版本 .NET 和 .NET Framework 上執行的 C# 函式。 隔離背景工作進程函式的延伸模組會使用
Microsoft.Azure.Functions.Worker.Extensions.*命名空間。 - 同進程模型：在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中，函式可以使用 C# 腳本來執行，主要支援 C# 入口網站編輯。 進程內函式的延伸模組會使用
Microsoft.Azure.WebJobs.Extensions.*命名空間。
重要
支援將於 2026 年 11 月 10 日結束進程模型。 強烈建議您將 應用程式移轉至隔離的背景工作模型 ，以取得完整支援。
下列範例顯示 C# 函式 ，會輪詢 input-queue 佇列，並在每次處理佇列專案時，將數則訊息寫入輸出佇列。
[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
// Use a string array to return more than one message.
string[] messages = {
$"Album name = {myQueueItem.Name}",
$"Album songs = {myQueueItem.Songs.ToString()}"};
_logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);
// Queue Output messages
return messages;
}
下列 Java 範例顯示記憶體佇列觸發程式函式，其會將觸發的訊息記錄到佇列 myqueuename中。
@FunctionName("queueprocessor")
public void run(
@QueueTrigger(name = "msg",
queueName = "myqueuename",
connection = "myconnvarname") String message,
final ExecutionContext context
) {
context.getLogger().info(message);
}
下列範例顯示佇列觸發程式 TypeScript 函式。 此函式會輪詢 myqueue-items 佇列，並在每次處理佇列項目時寫入記錄。
import { app, InvocationContext } from '@azure/functions';
export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: storageQueueTrigger1,
});
使用方式區段說明 queueItem。 訊息元數據區段說明顯示的所有其他變數。
下列範例顯示佇列觸發程式 JavaScript 函式。 此函式會輪詢 myqueue-items 佇列，並在每次處理佇列項目時寫入記錄。
const { app } = require('@azure/functions');
app.storageQueue('storageQueueTrigger1', {
queueName: 'myqueue-items',
connection: 'MyStorageConnectionAppSetting',
handler: (queueItem, context) => {
context.log('Storage queue function processed work item:', queueItem);
context.log('expirationTime =', context.triggerMetadata.expirationTime);
context.log('insertionTime =', context.triggerMetadata.insertionTime);
context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
context.log('id =', context.triggerMetadata.id);
context.log('popReceipt =', context.triggerMetadata.popReceipt);
context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
},
});
使用方式區段說明 queueItem。 訊息元數據區段說明顯示的所有其他變數。
下列範例示範如何讀取透過觸發程式傳遞至函式的佇列訊息。
儲存體 佇列觸發程式定義於 function.json 檔案中，其中 type 設定為 queueTrigger。
{
"bindings": [
{
"name": "QueueItem",
"type": "queueTrigger",
"direction": "in",
"queueName": "messages",
"connection": "MyStorageConnectionAppSetting"
}
]
}
Run.ps1 檔案中的程式代碼會將 參數宣告為 $QueueItem，這可讓您讀取函式中的佇列訊息。
# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)
# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"
下列範例示範如何讀取透過觸發程式傳遞至函式的佇列訊息。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。
import logging
import azure.functions as func
app = func.FunctionApp()
@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
connection="storageAccountConnectionString") # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
connection="storageAccountConnectionString") # Queue output binding
def test_function(msg: func.QueueMessage,
outputQueueItem: func.Out[str]) -> None:
logging.info('Python queue trigger function processed a queue item: %s',
msg.get_body().decode('utf-8'))
outputQueueItem.set('hello')
屬性
進程內和隔離的背景工作進程 C# 連結庫都會使用 QueueTriggerAttribute 來定義函式。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。
在 C# 類別庫中，屬性的建構函式會採用要監視的佇列名稱，如下列範例所示：
[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
此範例也會示範在屬性本身中設定 連接字串 設定。
註釋
批 QueueTrigger 注可讓您存取觸發函式的佇列。 下列範例會透過 message 參數讓佇列訊息可供函式使用。
package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;
public class QueueTriggerDemo {
@FunctionName("QueueTriggerDemo")
public void run(
@QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
final ExecutionContext context
) {
context.getLogger().info("Queue message: " + message);
}
}
| 屬性 | 說明 |
|---|---|
name |
在函式簽章中宣告參數名稱。 觸發函式時，此參數的值會包含佇列訊息的內容。 |
queueName |
宣告記憶體帳戶中的佇列名稱。 |
connection |
指向記憶體帳戶 連接字串。 |
裝飾項目
僅適用於 Python v2 程式設計模型。
針對使用裝飾項目定義的 Python v2 函式，裝飾專案上的queue_trigger下列屬性會定義佇列 儲存體 觸發程式：
| 屬性 | 說明 |
|---|---|
arg_name |
在函式簽章中宣告參數名稱。 觸發函式時，此參數的值會包含佇列訊息的內容。 |
queue_name |
宣告記憶體帳戶中的佇列名稱。 |
connection |
指向記憶體帳戶 連接字串。 |
如需使用 function.json 定義的 Python 函式，請參閱組態一節。
組態
僅適用於 Python v1 程式設計模型。
下表說明您在 function.json 檔案和 QueueTrigger 屬性中設定的系結組態屬性。
| function.json 屬性 | 描述 |
|---|---|
| type | 必須設定為 queueTrigger。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。 |
| direction | 僅限在 function.json 檔案中。 必須設定為 in。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。 |
| name | 在函式程式碼中包含佇列項目承載的變數名稱。 |
| queueName | 要輪詢的佇列名稱。 |
| connection | 應用程式設定或設定集合的名稱，其指定如何連線到 Azure 佇列。 請參閱連線。 |
如需完整範例， 請參閱範例一節 。
當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。
使用方式
注意
函式需要 base64 編碼的字串。 必須在呼叫服務中實作編碼類型的任何調整（若要準備數據為 base64 編碼字串）。
佇列觸發程式的使用方式取決於擴充套件版本，以及函式應用程式中所使用的 C# 形式，這可以是下列其中一種模式：
已編譯 C# 函式的隔離背景工作進程類別庫會在與運行時間隔離的進程中執行。
選擇版本以查看模式和版本的使用量詳細數據。
佇列觸發程式可以系結至下列類型：
| 類型 | 描述 |
|---|---|
string |
以字串表示的訊息內容。 當訊息是簡單的文字時，請使用 。 |
byte[] |
訊息的位元組。 |
| JSON 可序列化型別 | 當佇列訊息包含 JSON 數據時，Functions 會嘗試將 JSON 數據還原串行化為純舊 CLR 物件 （POCO） 類型。 |
| QueueMessage1 | 訊息。 |
| BinaryData1 | 訊息的位元組。 |
1 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.儲存體。佇列 5.2.0 或更新版本，以及 SDK 類型系結的常見相依性。
QueueTrigger 註釋可讓您存取觸發函式的佇列訊息。
透過符合系結參數在 function.json 檔案中指定名稱的name字串參數存取佇列訊息。
透過輸入為 QueueMessage 的參數存取佇列訊息。
中繼資料
佇列觸發程式提供數個 元數據屬性。 這些屬性可以做為其他系結中系結表達式的一部分，或做為程式代碼中的參數，供提供此訊息元數據存取權的語言背景工作角色使用。
訊息元數據屬性是 CloudQueueMessage 類別的成員。
您可以從存取 context.triggerMetadata訊息元資料屬性。
您可以從傳遞 $TriggerMetadata 的參數存取訊息元資料屬性。
| 屬性 | 類型 | 描述 |
|---|---|---|
QueueTrigger |
string |
佇列承載（如果有效的字串）。 如果佇列訊息承載是字串，QueueTrigger則具有與 function.json 中 屬性所命名name的變數相同的值。 |
DequeueCount |
long |
此訊息已清除佇列的次數。 |
ExpirationTime |
DateTimeOffset |
訊息到期的時間。 |
Id |
string |
佇列訊息標識碼。 |
InsertionTime |
DateTimeOffset |
訊息新增至佇列的時間。 |
NextVisibleTime |
DateTimeOffset |
訊息接下來會顯示的時間。 |
PopReceipt |
string |
訊息的快顯收據。 |
您可以從傳遞的係結參數存取下列訊息元數據屬性（msg 在先前 的範例中）。
| 屬性 | 說明 |
|---|---|
body |
將承載隊列為字串。 |
dequeue_count |
此訊息已清除佇列的次數。 |
expiration_time |
訊息到期的時間。 |
id |
佇列訊息標識碼。 |
insertion_time |
訊息新增至佇列的時間。 |
time_next_visible |
訊息接下來會顯示的時間。 |
pop_receipt |
訊息的快顯收據。 |
連線
屬性 connection 是環境組態的參考，指定應用程式應該如何連線到 Azure 佇列。 它可以指定：
- 包含 連接字串 的應用程式設定名稱
- 多個應用程式設定的共用前置詞名稱，並定義 以身分識別為基礎的連線。
如果設定的值既與單一設定完全相符，又是其他設定的前置詞比對，則會使用完全相符專案。
連接字串
若要取得 連接字串，請遵循管理記憶體帳戶存取密鑰中顯示的步驟。
此 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的 屬性所connection指定的值。
如果應用程式設定名稱以 「AzureWebJobs」 開頭，您就只能在這裡指定名稱的其餘部分。 例如，如果您設定connection為 「My 儲存體」，Functions 運行時間會尋找名為 「AzureWebJobsMy 儲存體」 的應用程式設定。如果您保留connection空白，Functions 運行時間會在名為 AzureWebJobsStorage的應用程式設定中使用預設 儲存體 連接字串。
身分識別型連線
如果您使用 5.x 版或更高版本的延伸模組（non-.NET 語言堆疊組合 3.x 或更新版本），而不是搭配秘密使用 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要使用身分識別，您可以在對應至 connection 觸發程式和系結組態中 屬性的通用前置詞下定義設定。
如果您要將 設定connection為 「AzureWebJobs 儲存體」，請參閱使用身分識別來裝載記憶體 連線。 針對所有其他連線，擴充功能需要下列屬性：
| 屬性 | 環境變數範本 | 描述 | 範例值 |
|---|---|---|---|
| 佇列服務 URI | <CONNECTION_NAME_PREFIX>__queueServiceUri1 |
您使用 HTTPS 配置連線之佇列服務的數據平面 URI。 | <https:// storage_account_name.queue.core.windows.net> |
1<CONNECTION_NAME_PREFIX>__serviceUri 可作為別名。 如果提供這兩個窗體，則會 queueServiceUri 使用表單。 serviceUri在 Blob、佇列和/或數據表之間使用整體聯機組態時，無法使用表單。
其他屬性可以設定為自定義連線。 請參閱 身分識別型連線的一般屬性。
主控於 Azure Functions 服務時，以身分識別為基礎的連接會使用受控識別。 雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。 請注意，不支援使用資源標識符設定使用者指派的身分識別。 在其他內容中執行時，例如本機開發，會改用您的開發人員身分識別，但您可以自定義此身分識別。 請參閱 使用身分識別型連線進行本機開發。
授與權限給身分識別
正在使用的任何身分識別，都必須具有執行預期動作的權限。 對於大部分的 Azure 服務，這表示您必須 使用內建或自定義角色，在 Azure RBAC 中指派角色，以提供這些許可權。
重要
部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠從數據源讀取，請使用只有讀取許可權的角色。 指派也允許寫入該服務的角色是不適當的，因為這會是讀取作業的過度許可權。 同樣地，您會想要確保角色指派的範圍僅限於需要讀取的資源。
您必須建立角色指派，以在運行時間提供佇列的存取權。 擁有者之類的管理角色不足。 下表顯示在正常作業中使用佇列 儲存體 擴充功能時建議的內建角色。 您的應用程式可能需要根據您撰寫的程式代碼來取得其他許可權。
| 繫結類型 | 範例內建角色 |
|---|---|
| 觸發程序 | 儲存體 佇列數據讀取器，儲存體 佇列數據訊息處理器 |
| 輸出繫結 | 儲存體 佇列數據參與者，儲存體 佇列數據訊息傳送者 |
有害訊息
當佇列觸發程式函式失敗時，Azure Functions 會針對指定的佇列訊息重試函式最多五次，包括第一次嘗試。 如果這五次嘗試都失敗，函式運行時間會將訊息新增至名為 originalqueuename-poison> 的<佇列。 您可以撰寫函式來處理有害佇列中的訊息，方法是記錄訊息，或傳送需要手動注意的通知。
若要手動處理有害訊息，請檢查 佇列訊息的 dequeueCount 。
預覽鎖定
使用記憶體服務所提供的可見度機制，佇列觸發程式會自動發生窺視鎖定模式。 當訊息被觸發的函式清除佇列時，它們會標示為不可見。 佇列觸發函式的執行可以在佇列中的訊息上產生下列其中一個結果：
- 函式執行會順利完成，而且訊息會從佇列中刪除。
- 函式執行失敗，Functions 主機會根據
visibilityTimeouthost.json檔案中的設定來更新訊息的可見度。 默認可見性逾時為零，這表示訊息會立即重新出現在佇列中以進行重新處理。visibilityTimeout使用 設定來延遲無法處理的訊息重新處理。 此逾時設定適用於函式應用程式中所有佇列觸發的函式。 - Functions 主機會在函式執行期間當機。 發生這個不常見的事件時，主機無法將 套用
visibilityTimeout至正在處理的訊息。 相反地，訊息會保留記憶體服務所設定的預設 10 分鐘逾時。 10 分鐘之後，訊息會在佇列中重新出現以進行重新處理。 無法變更此服務定義的預設逾時。
輪詢演算法
佇列觸發程式會實作隨機指數輪詢演算法，以減少閑置佇列輪詢對記憶體交易成本的影響。
此演算法會使用下列邏輯：
- 找到訊息時，運行時間會等候 100 毫秒，然後檢查另一則訊息。
- 找不到訊息時，它會等候大約 200 毫秒再試一次。
- 在後續嘗試取得佇列訊息失敗之後，等候時間會繼續增加，直到達到最長等候時間，預設為一分鐘。
- 等候時間上限可透過
maxPollingIntervalhost.json 檔案中的 屬性來設定。
在本機開發期間，輪詢間隔上限預設為兩秒。
注意
在取用方案中裝載函式應用程式時，您不需要支付運行時間輪詢所花費的時間的費用。
並行
等候多個佇列訊息時，佇列觸發程式會擷取一批訊息，並同時叫用函式實例來處理它們。 根據預設，批次大小為16。 當正在處理的數字減少到 8 時，運行時間會取得另一個批次，並開始處理這些訊息。 因此，一部虛擬機（VM） 上每個函式所處理的並行訊息數目上限為 24。 此限制會分別套用至每個 VM 上每個佇列觸發的函式。 如果您的函式應用程式向外延展至多個 VM，則每個 VM 會等候觸發程式並嘗試執行函式。 例如，如果函式應用程式相應放大為 3 部 VM，則一個佇列觸發函式的預設並行實例數目上限為 72。
取得新批次的批次大小和臨界值可在 host.json 檔案中設定。 如果您想要將函式應用程式中佇列觸發函式的平行執行降到最低，您可以將批次大小設定為 1。 只要函式應用程式在單一虛擬機 （VM） 上執行，此設定才會排除並行。
佇列觸發程式會自動防止函式同時處理佇列訊息。
host.json屬性
host.json檔案包含控制佇列觸發程序的設定。 如需可用設定的詳細資訊，請參閱host.json設定一節。