共用方式為

Azure Functions 的 Azure 佇列記憶體輸出系結

  • 發行項

Azure Functions 可以藉由設定輸出系結來建立新的 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 日結束。 強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。

[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 函式，此函式會在 HTTP 要求觸發時建立 的佇列訊息。

@FunctionName("httpToQueue")
@QueueOutput(name = "item", queueName = "myqueue-items", connection = "MyStorageConnectionAppSetting")
 public String pushToQueue(
     @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
     final String message,
     @HttpOutput(name = "response") final OutputBinding<String> result) {
       result.setValue(message + " has been added.");
       return message;
 }

在 Java 函式運行時間連結庫中，對 @QueueOutput 值寫入佇列記憶體的參數使用註釋。 參數類型應該是 OutputBinding<T>，其中 T 是POJO的任何原生Java類型。

下列範例顯示 HTTP 觸發的 TypeScript 函式 ，會為每個收到的 HTTP 要求建立佇列專案。

import { app, HttpRequest, HttpResponseInit, InvocationContext, output } from '@azure/functions';

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

export async function httpTrigger1(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
    const body = await request.text();
    context.extraOutputs.set(queueOutput, body);
    return { body: 'Created queue item.' };
}

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: httpTrigger1,
});

若要輸出多個訊息，請傳回數位，而不是單一物件。 例如：

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

下列範例顯示 HTTP 觸發的 JavaScript 函式 ，會為每個收到的 HTTP 要求建立佇列專案。

const { app, output } = require('@azure/functions');

const queueOutput = output.storageQueue({
    queueName: 'outqueue',
    connection: 'MyStorageConnectionAppSetting',
});

app.http('httpTrigger1', {
    methods: ['GET', 'POST'],
    authLevel: 'anonymous',
    extraOutputs: [queueOutput],
    handler: async (request, context) => {
        const body = await request.text();
        context.extraOutputs.set(queueOutput, body);
        return { body: 'Created queue item.' };
    },
});

若要輸出多個訊息，請傳回數位，而不是單一物件。 例如：

context.extraOutputs.set(queueOutput, ['message 1', 'message 2']);

下列程式代碼範例示範如何從 HTTP 觸發的函式輸出佇列訊息。 的組態區段會typequeue定義輸出系結。

{
  "bindings": [
    {
      "authLevel": "anonymous",
      "type": "httpTrigger",
      "direction": "in",
      "name": "Request",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "Response"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "Msg",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

使用此系結組態，PowerShell 函式可以使用 來建立佇列訊息 Push-OutputBinding。 在此範例中，會從查詢字串或本文參數建立訊息。

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = $Request.Query.Message
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

若要一次傳送多個訊息，請定義訊息陣列，並使用 Push-OutputBinding 將訊息傳送至佇列輸出系結。

using namespace System.Net

# Input bindings are passed in via param block.
param($Request, $TriggerMetadata)

# Write to the Azure Functions log stream.
Write-Host "PowerShell HTTP trigger function processed a request."

# Interact with query parameters or the body of the request.
$message = @("message1", "message2")
Push-OutputBinding -Name Msg -Value $message
Push-OutputBinding -Name Response -Value ([HttpResponseContext]@{
    StatusCode = 200
    Body = "OK"
})

下列範例示範如何將單一和多個值輸出至記憶體佇列。 function.json所需的設定任一方式都相同。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueOutput1")
@app.route(route="message")
@app.queue_output(arg_name="msg", 
                  queue_name="<QUEUE_NAME>", 
                  connection="<CONNECTION_SETTING>")
def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('name')
    logging.info(input_msg)

    msg.set(input_msg)

    logging.info(f'name: {name}')
    return 'OK'

屬性

在 C# 連結庫中定義輸出系結的屬性取決於 C# 類別庫執行的模式。

在隔離的背景工作進程中執行時，您可以使用 QueueOutputAttribute，它會採用佇列的名稱，如下列範例所示：

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

在隔離的背景工作進程中執行時，僅支援傳回的變數。 無法使用輸出參數。

裝飾項目

僅適用於 Python v2 程式設計模型。

針對使用裝飾項目定義的 Python v2 函式，在上 queue_output具有下列屬性：

屬性 說明
arg_name 代表函式程式碼中佇列的變數名稱。
queue_name 佇列的名稱。
connection 應用程式設定或設定集合的名稱，其指定如何連線到 Azure 佇列。 請參閱連線。

如需使用 function.json 定義的 Python 函式，請參閱組 態 一節。

註釋

QueueOutput 註釋可讓您撰寫訊息作為函式的輸出。 下列範例示範建立佇列訊息的 HTTP 觸發函式。

package com.function;
import java.util.*;
import com.microsoft.azure.functions.annotation.*;
import com.microsoft.azure.functions.*;

public class HttpTriggerQueueOutput {
    @FunctionName("HttpTriggerQueueOutput")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.FUNCTION) HttpRequestMessage<Optional<String>> request,
            @QueueOutput(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") OutputBinding<String> message,
            final ExecutionContext context) {

        message.setValue(request.getQueryParameters().get("name"));
        return request.createResponseBuilder(HttpStatus.OK).body("Done").build();
    }
}
屬性 說明
name 在函式簽章中宣告參數名稱。 觸發函式時，此參數的值會包含佇列訊息的內容。
queueName 宣告記憶體帳戶中的佇列名稱。
connection 指向記憶體帳戶 連接字串。

與 QueueOutput 註釋相關聯的參數會輸入為 OutputBinding<T> 實例。

組態

僅適用於 Python v1 程式設計模型。

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

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

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

下表說明您在 function.json 檔案中設定的繫結設定屬性。

function.json 屬性 描述
type 必須設定為 queue。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction 必須設定為 out。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name 代表函式程式碼中佇列的變數名稱。 設為 $return 以參考函式傳回值。
queueName 佇列的名稱。
connection 應用程式設定或設定集合的名稱，其指定如何連線到 Azure 佇列。 請參閱連線。

當您在本機開發時，請在集合中的 local.settings.json 檔案Values中新增應用程式設定。

如需完整範例，請參閱範例一節。

使用方式

佇列輸出系結的使用方式取決於函式應用程式中所使用的擴充套件版本和 C# 形式，這可以是下列其中一項：

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

選擇版本以查看模式和版本的使用量詳細數據。

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

類型 描述
string 以字串表示的訊息內容。 當訊息為簡單文字時，請使用 。
byte[] 訊息的位元組。
JSON 可序列化型別 物件，表示 JSON 訊息的內容。 函式會嘗試將一般舊的CLR物件 （POCO） 類型串行化為 JSON 數據。

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

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

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

使用 QueueOutput 註釋從函式寫入佇列有兩個選項：

  • 傳回值：藉由將註釋套用至函式本身，函式的傳回值會寫入佇列。

  • 命令式：若要明確設定訊息值，請將批注套用至類型的 OutputBinding<T>特定參數，其中 T 是 POJO 或任何原生 Java 類型。 使用此組態，將值傳遞至 setValue 方法會將值寫入佇列。

直接傳 context.extraOutputs.set()回值或使用 ，以存取輸出佇列專案。 您可以針對佇列項目承載使用字串或 JSON 可串行化物件。

您可以透過Push-OutputBinding將符合係結參數所指定名稱的name自變數傳遞至佇列訊息，以在function.json檔案中傳遞自變數。

有兩個選項可從函式寫入至設定的佇列：

  • 傳回值：將 name 中的屬性設定為 $returnfunction.json。 使用此組態時，函式的傳回值會保存為佇列記憶體訊息。

  • 命令式：將值傳遞至宣告為 Out 類型的參數的 set 方法。 傳遞至 set 的值會保存為佇列記憶體訊息。

連線

屬性 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 的角色，利用提供這些權限的內建或自訂角色。

重要

部分權限可能會由所有內容都不需要的目標服務公開。 可以的話，請遵循最低權限原則，只授與身分識別所需的權限。 例如，如果應用程式只需要能夠讀取資料來源，請使用只有讀取權限的角色。 不宜指派也允許寫入該服務的角色，因為讀取作業不需要這麼多權限。 同樣地，最好確保角色指派的範圍僅限於需要讀取的資源。

您必須建立可在執行時間存取佇列的角色指派。 擁有者等的管理角色不足。 下表顯示通常作業中使用佇列儲存體延伸模組時建議的內建角色。 您的應用程式可能會根據您寫入的程式碼要求額外的權限。

繫結類型 內建角色範例
觸發程序 儲存體佇列資料讀取器、儲存體佇列資料訊息處理器
輸出繫結 儲存體佇列資料參與者、儲存體佇列資料訊息傳送者

例外狀況和傳回碼

繫結 參考
佇列 佇列錯誤碼
Blob、數據表、佇列 記憶體錯誤碼
Blob、數據表、佇列 疑難排解

下一步