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.儲存體 建立和使用類型。直接佇列。

使用 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為 「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 中指派角色，以提供這些許可權。

重要

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

您必須建立角色指派，以在運行時間提供佇列的存取權。 擁有者之類的管理角色不足。 下表顯示正常作業中使用佇列 儲存體 擴充功能時建議的內建角色。 您的應用程式可能需要根據您撰寫的程式代碼來取得其他許可權。

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

例外狀況和傳回碼

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

下一步