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

發行項
08/15/2024

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;
}

下列範例顯示 C# 函式，會為每個收到的 HTTP 要求建立佇列訊息。

[StorageAccount("MyStorageConnectionAppSetting")]
public static class QueueFunctions
{
    [FunctionName("QueueOutput")]
    [return: Queue("myqueue-items")]
    public static string QueueOutput([HttpTrigger] dynamic input,  ILogger log)
    {
        log.LogInformation($"C# function processed: {input.Text}");
        return input.Text;
    }
}

如需如何設定輸出系結至佇列記憶體的端對端範例，請參閱下列其中一篇文章：

下列範例顯示 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類型。

如需如何設定輸出系結至佇列記憶體的端對端範例，請參閱下列其中一篇文章：

模型 v4
模型 v3

下列範例顯示 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']);

模型 v4
模型 v3

下列範例顯示 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']);

如需如何設定輸出系結至佇列記憶體的端對端範例，請參閱下列其中一篇文章：

下列範例顯示function.json檔案中的 HTTP 觸發程式系結，以及使用系結的 JavaScript 函式。 函式會為每個收到的 HTTP 要求建立佇列專案。

以下是 function.json 檔案：

{
  "bindings": [
    {
      "type": "httpTrigger",
      "direction": "in",
      "authLevel": "function",
      "name": "input"
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "myQueueItem",
      "queueName": "outqueue",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

組態區段說明這些屬性。

以下是 JavaScript 程式碼：

module.exports = async function (context, input) {
    context.bindings.myQueueItem = input.body;
};

您可以定義輸出系結的 myQueueItem 訊息數位，一次傳送多個訊息。下列 JavaScript 程式代碼會針對每個收到的 HTTP 要求傳送兩個具有硬式編碼值的佇列訊息。

module.exports = async function(context) {
    context.bindings.myQueueItem = ["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'

如需如何設定輸出系結至佇列記憶體的端對端範例，請參閱下列其中一篇文章：

記憶體佇列系結定義於 類型設定queue為的function.json中。

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "function",
      "type": "httpTrigger",
      "direction": "in",
      "name": "req",
      "methods": [
        "get",
        "post"
      ]
    },
    {
      "type": "http",
      "direction": "out",
      "name": "$return"
    },
    {
      "type": "queue",
      "direction": "out",
      "name": "msg",
      "queueName": "outqueue",
      "connection": "AzureStorageQueuesConnectionString"
    }
  ]
}

若要在佇列上設定個別訊息，請將單一值傳遞至 set 方法。

import azure.functions as func

def main(req: func.HttpRequest, msg: func.Out[str]) -> func.HttpResponse:

    input_msg = req.params.get('message')

    msg.set(input_msg)

    return 'OK'

若要在佇列上建立多個訊息，請將參數宣告為適當的清單類型，並將值陣列（符合清單類型）傳遞至 set 方法。

import azure.functions as func
import typing

def main(req: func.HttpRequest, msg: func.Out[typing.List[str]]) -> func.HttpResponse:

    msg.set(['one', 'two'])

    return 'OK'

屬性

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

隔離式背景工作角色模型
內含式模型

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

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

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

在 C# 類別庫中，使用 QueueAttribute。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

屬性會套用至 out 參數或函式的傳回值。屬性的建構函式會採用佇列的名稱，如下列範例所示：

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

您可以設定 Connection 屬性來指定要使用的記憶體帳戶，如下列範例所示：

[FunctionName("QueueOutput")]
[return: Queue("myqueue-items", Connection = "StorageConnectionAppSetting")]
public static string Run([HttpTrigger] dynamic input,  ILogger log)
{
    ...
}

您可以使用 StorageAccount 屬性來指定類別、方法或參數層級的記憶體帳戶。如需詳細資訊，請參閱觸發程式 - 屬性。

裝飾項目

僅適用於 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 程式設計模型。

模型 v4
模型 v3

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

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

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

屬性	描述
type	必須設定為 `queue`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為 `out`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中佇列的變數名稱。設為 `$return` 以參考函式傳回值。
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# 函式會在與執行階段隔離的處理序中執行。

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

使用方法參數來撰寫單一佇列訊息，例如 out T paramName。您可以使用方法傳回類型， out 而不是參數，而且 T 可以是下列任何類型：

物件可串行化為 JSON
string
byte[]
QueueMessage

如需使用這些類型的範例，請參閱 GitHub 的延伸模組存放庫。

您可以使用下列其中一種類型，將多個訊息寫入佇列：

ICollector<T> 或 IAsyncCollector<T>
QueueClient

如需使用 QueueMessage 和 QueueClient 的範例，請參閱延伸模組的 GitHub 存放庫。

雖然屬性採用 Connection 屬性，您也可以使用 StorageAccountAttribute 來指定記憶體帳戶連線。當您需要使用與連結庫中其他函式不同的記憶體帳戶時，可以執行此動作。建構函式會採用包含記憶體連接字串的應用程式設定名稱。屬性可以在參數、方法或類別層級套用。下列範例顯示類別層級和方法層級：

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

要使用的記憶體帳戶會依下列順序決定：

觸發程式或系結屬性的 Connection 屬性。
套 StorageAccount 用至與觸發程式或系結屬性相同的參數的屬性。
套 StorageAccount 用至函式的屬性。
套 StorageAccount 用至類別的屬性。
函式應用程式的預設記憶體帳戶，定義於應用程式設定中 AzureWebJobsStorage 。

使用方法參數來撰寫單一佇列訊息，例如 out T paramName。您可以使用方法傳回類型， out 而不是參數，而且 T 可以是下列任何類型：

物件可串行化為 JSON
string
byte[]
CloudQueueMessage

如果您嘗試系結至 CloudQueueMessage 並收到錯誤訊息，請確定您有正確的記憶體 SDK 版本的參考。

您可以使用下列其中一種類型，將多個訊息寫入佇列：

ICollector<T> 或 IAsyncCollector<T>
CloudQueue

[StorageAccount("ClassLevelStorageAppSetting")]
public static class AzureFunctions
{
    [FunctionName("StorageTrigger")]
    [StorageAccount("FunctionLevelStorageAppSetting")]
    public static void Run( //...
{
    ...
}

要使用的記憶體帳戶會依下列順序決定：

觸發程式或系結屬性的 Connection 屬性。
套 StorageAccount 用至與觸發程式或系結屬性相同的參數的屬性。
套 StorageAccount 用至函式的屬性。
套 StorageAccount 用至類別的屬性。
函式應用程式的預設記憶體帳戶，定義於應用程式設定中 AzureWebJobsStorage 。

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

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

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

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

針對其他輸出案例，請直接從 Azure.Storage.Queues 建立並使用 QueueClient 與其他類型。如需使用相依性插入從 Azure SDK 建立用戶端類型的範例，請參閱註冊 Azure 用戶端。

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

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

模型 v4
模型 v3

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

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

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

傳回值：將 name 中的屬性設定為 $returnfunction.json。使用此組態時，函式的傳回值會保存為佇列記憶體訊息。
命令式：將值傳遞至宣告為 Out 類型的參數的 set 方法。傳遞至 set 的值會保存為佇列記憶體訊息。

連線

屬性 connection 是環境組態的參考，指定應用程式應該如何連線到 Azure 佇列。此屬性可以指定：

包含連接字串的應用程式設定名稱
多個應用程式設定的共用前置詞名稱，一起定義身分識別型連線。

如果設定的值與單一設定完全相符，又與其他設定的開頭相符，則會使用完全相符項目。

Connection string

若要取得連接字串，請遵循管理儲存體帳戶存取金鑰所示的步驟。

此連接字串應該儲存在應用程式設定中，其名稱符合系結組態的屬性所connection指定的值。

如果應用程式設定名稱以「AzureWebJobs」開頭，您就只能在這裡指定名稱的其餘部分。例如，如果您設定connection為「MyStorage」，Functions 運行時間會尋找名為「AzureWebJobsMyStorage」的應用程式設定。如果您保留connection空白，Functions 運行時間會在名為 AzureWebJobsStorage的應用程式設定中使用預設的記憶體連接字串。

身分識別型連線

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

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

屬性	環境變數範本	描述	範例值
佇列服務 URI	`<CONNECTION_NAME_PREFIX>__queueServiceUri`¹	您使用 HTTPS 配置連線之佇列服務的數據平面 URI。	https://<storage_account_name>.queue.core.windows.net

¹ <CONNECTION_NAME_PREFIX>__serviceUri 可作為別名。如果提供這兩個窗體，則會 queueServiceUri 使用表單。 serviceUri在 Blob、佇列和/或數據表之間使用整體聯機組態時，無法使用表單。

其他屬性可以設定為自定義連線。請參閱身分識別型連線的通用屬性。

主控於 Azure Functions 服務時，以身分識別為基礎的連接會使用受控識別。雖然可以使用 credential 和 clientID 屬性指定使用者指派的身分識別，但預設會使用系統指派的身分識別。請注意，不支援以資源識別碼來設定使用者指派的身分識別。在本機開發等其他內容中執行時，雖然這可以自訂，但仍會改用您的開發人員身分識別。請參閱使用身分識別型連線進行本機開發。

授與權限給身分識別

正在使用的任何身分識別，都必須具有執行預期動作的權限。有關大多數 Azure 服務，意即您需要指派 Azure RBAC 的角色，利用提供這些權限的內建或自訂角色。

重要

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

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

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

例外狀況和傳回碼

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

下一步

以佇列記憶體資料變更的形式執行函式（觸發程式）

共用方式為

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

範例

屬性

裝飾項目

註釋

組態

使用方式

連線

Connection string

身分識別型連線

授與權限給身分識別

例外狀況和傳回碼

下一步

意見反應

其他資源