共用方式為

適用於 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}"};

    _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 程式設計模型。

下表說明您可以在傳遞至 app.storageQueue() 方法的物件options上設定的屬性。

屬性 說明
queueName 要輪詢的佇列名稱。
connection 應用程式設定或設定集合的名稱，其指定如何連線到 Azure 佇列。 請參閱連線。

下表說明您在 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.Storage.Queues 5.2.0 或更新版本 ，以及 SDK 類型系結的常見相依性。

QueueTrigger 註釋可讓您存取觸發函式的佇列訊息。

存取佇列專案作為函式的第一個自變數。 如果承載為 JSON，該值會還原串行化為 物件。

透過符合系結參數在 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為 「MyStorage」，Functions 運行時間會尋找名為 「AzureWebJobsMyStorage」 的應用程式設定。如果您保留connection空白，Functions 運行時間會在名為 AzureWebJobsStorage的應用程式設定中使用預設的記憶體 連接字串。

身分識別型連線

如果您使用 5.x 版或更高版本的延伸模組（non-.NET 語言堆疊組合 3.x 或更新版本），而不是搭配秘密使用 連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。 若要使用身分識別，您可以在對應至 connection 觸發程式和系結組態中 屬性的通用前置詞下定義設定。

如果您要將 設定 connection 為 「AzureWebJobsStorage」，請參閱 使用身分識別連線到主機記憶體。 針對所有其他連線，擴充功能需要下列屬性：

屬性 環境變數範本 描述 範例值
佇列服務 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 毫秒再試一次。
  • 在後續嘗試取得佇列訊息失敗之後，等候時間會繼續增加，直到達到最長等候時間，預設為一分鐘。
  • 等候時間上限可透過 maxPollingInterval host.json 檔案中的 屬性來設定。

在本機開發期間，輪詢間隔上限預設為兩秒。

注意

在取用方案中裝載函式應用程式時，您不需要支付運行時間輪詢所花費的時間的費用。

並行

等候多個佇列訊息時，佇列觸發程式會擷取一批訊息，並同時叫用函式實例來處理它們。 根據預設，批次大小為16。 當正在處理的數字減少到 8 時，運行時間會取得另一個批次，並開始處理這些訊息。 因此，一部虛擬機（VM） 上每個函式所處理的並行訊息數目上限為 24。 此限制會分別套用至每個 VM 上每個佇列觸發的函式。 如果您的函式應用程式向外延展至多個 VM，則每個 VM 會等候觸發程式並嘗試執行函式。 例如，如果函式應用程式相應放大為 3 部 VM，則一個佇列觸發函式的預設並行實例數目上限為 72。

取得新批次的批次大小和臨界值可在 host.json 檔案中設定。 如果您想要將函式應用程式中佇列觸發函式的平行執行降到最低，您可以將批次大小設定為 1。 只要函式應用程式在單一虛擬機 （VM） 上執行，此設定才會排除並行。

佇列觸發程式會自動防止函式同時處理佇列訊息。

host.json屬性

host.json檔案包含控制佇列觸發程序的設定。 如需可用設定的詳細資訊，請參閱host.json設定一節。

下一步