Azure Functions 的 Azure 服務匯流排觸發程序

發行項
04/07/2024

使用服務匯流排觸發程式來回應來自服務匯流排佇列或主題的訊息。從擴充功能 3.1.0 版開始，您可以在已啟用會話的佇列或主題上觸發。

如需安裝和組態詳細數據的詳細資訊，請參閱概觀。

服務匯流排取用和進階方案的調整決策是根據以目標為基礎的調整進行。如需詳細資訊，請參閱以目標為基礎的調整。

重要

本文使用索引標籤來支援多個版本的 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 日結束。強烈建議您將應用程式移轉至隔離式背景工作角色模型，以取得完整支援。

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

此程式代碼會定義並初始化 ILogger：

private readonly ILogger<ServiceBusReceivedMessageFunctions> _logger;

public ServiceBusReceivedMessageFunctions(ILogger<ServiceBusReceivedMessageFunctions> logger)
{
    _logger = logger;
}

此範例顯示 C# 函式，該函式會接收單一服務匯流排佇列訊息，並將它寫入記錄：

[Function(nameof(ServiceBusReceivedMessageFunction))]
[ServiceBusOutput("outputQueue", Connection = "ServiceBusConnection")]
public string ServiceBusReceivedMessageFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection")] ServiceBusReceivedMessage message)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    var outputMessage = $"Output message created at {DateTime.Now}";
    return outputMessage;
}

此範例顯示 C# 函式，會在單一批次中接收多個服務匯流排佇列訊息，並將每個訊息寫入記錄：

[Function(nameof(ServiceBusReceivedMessageBatchFunction))]
public void ServiceBusReceivedMessageBatchFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", IsBatched = true)] ServiceBusReceivedMessage[] messages)
{
    foreach (ServiceBusReceivedMessage message in messages)
    {
        _logger.LogInformation("Message ID: {id}", message.MessageId);
        _logger.LogInformation("Message Body: {body}", message.Body);
        _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);
    }
}

此範例顯示 C# 函式，該函式會接收多個服務匯流排佇列訊息、將它寫入記錄，然後將訊息確定為已完成：

[Function(nameof(ServiceBusMessageActionsFunction))]
public async Task ServiceBusMessageActionsFunction(
    [ServiceBusTrigger("queue", Connection = "ServiceBusConnection", AutoCompleteMessages = false)]
    ServiceBusReceivedMessage message,
    ServiceBusMessageActions messageActions)
{
    _logger.LogInformation("Message ID: {id}", message.MessageId);
    _logger.LogInformation("Message Body: {body}", message.Body);
    _logger.LogInformation("Message Content-Type: {contentType}", message.ContentType);

    // Complete the message
    await messageActions.CompleteMessageAsync(message);
}

下列範例顯示 C# 函式，可讀取訊息元數據並記錄服務匯流排佇列訊息：

[FunctionName("ServiceBusQueueTriggerCSharp")]                    
public static void Run(
    [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
    string myQueueItem,
    Int32 deliveryCount,
    DateTime enqueuedTimeUtc,
    string messageId,
    ILogger log)
{
    log.LogInformation($"C# ServiceBus queue trigger function processed message: {myQueueItem}");
    log.LogInformation($"EnqueuedTimeUtc={enqueuedTimeUtc}");
    log.LogInformation($"DeliveryCount={deliveryCount}");
    log.LogInformation($"MessageId={messageId}");
}

下列 Java 函式會使用 @ServiceBusQueueTrigger Java 函式運行時間連結庫中的註釋來描述服務匯流排佇列觸發程式的組態。函式會擷取放在佇列上的訊息，並將它新增至記錄。

@FunctionName("sbprocessor")
 public void serviceBusProcess(
    @ServiceBusQueueTrigger(name = "msg",
                             queueName = "myqueuename",
                             connection = "myconnvarname") String message,
   final ExecutionContext context
 ) {
     context.getLogger().info(message);
 }

當訊息新增至服務匯流排主題時，也可以觸發Java函式。下列範例會 @ServiceBusTopicTrigger 使用註釋來描述觸發程式組態。

@FunctionName("sbtopicprocessor")
    public void run(
        @ServiceBusTopicTrigger(
            name = "message",
            topicName = "mytopicname",
            subscriptionName = "mysubscription",
            connection = "ServiceBusConnection"
        ) String message,
        final ExecutionContext context
    ) {
        context.getLogger().info(message);
    }

模型 v4
模型 v3

下列範例顯示服務匯流排觸發程式 TypeScript 函式。函式會讀取訊息元數據，並記錄服務匯流排佇列訊息。

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

export async function serviceBusQueueTrigger1(message: unknown, context: InvocationContext): Promise<void> {
    context.log('Service bus queue function processed message:', message);
    context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
    context.log('MessageId =', context.triggerMetadata.messageId);
}

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: serviceBusQueueTrigger1,
});

模型 v4
模型 v3

下列範例顯示服務匯流排觸發 JavaScript 函式。函式會讀取訊息元數據，並記錄服務匯流排佇列訊息。

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

app.serviceBusQueue('serviceBusQueueTrigger1', {
    connection: 'MyServiceBusConnection',
    queueName: 'testqueue',
    handler: (message, context) => {
        context.log('Service bus queue function processed message:', message);
        context.log('EnqueuedTimeUtc =', context.triggerMetadata.enqueuedTimeUtc);
        context.log('DeliveryCount =', context.triggerMetadata.deliveryCount);
        context.log('MessageId =', context.triggerMetadata.messageId);
    },
});

下列範例顯示function.json檔案中的 服務匯流排觸發程式系結，以及使用系結的 JavaScript 函式。 函式會讀取訊息元數據，並記錄服務匯流排佇列訊息。

以下是 function.json 檔案中的繫結資料：

{
"bindings": [
    {
    "queueName": "testqueue",
    "connection": "MyServiceBusConnection",
    "name": "myQueueItem",
    "type": "serviceBusTrigger",
    "direction": "in"
    }
],
"disabled": false
}

以下是 JavaScript 腳本程式代碼：

module.exports = async function(context, myQueueItem) {
    context.log('Node.js ServiceBus queue trigger function processed message', myQueueItem);
    context.log('EnqueuedTimeUtc =', context.bindingData.enqueuedTimeUtc);
    context.log('DeliveryCount =', context.bindingData.deliveryCount);
    context.log('MessageId =', context.bindingData.messageId);
};

下列範例示範function.json檔案中的 服務匯流排 觸發程式系結，以及使用系結的 PowerShell 函式。

以下是 function.json 檔案中的繫結資料：

{
  "bindings": [
    {
      "name": "mySbMsg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "topicName": "mytopic",
      "subscriptionName": "mysubscription",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

以下是傳送服務匯流排訊息時執行的函式。

param([string] $mySbMsg, $TriggerMetadata)

Write-Host "PowerShell ServiceBus queue trigger function processed message: $mySbMsg"

下列範例示範如何透過觸發程式讀取服務匯流排佇列訊息。此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusQueueTrigger1")
@app.service_bus_queue_trigger(arg_name="msg", 
                               queue_name="<QUEUE_NAME>", 
                               connection="<CONNECTION_SETTING>")
def test_function(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message: %s',
                 msg.get_body().decode('utf-8'))

服務匯流排系結定義於 function.json ，其中 type 設定為 serviceBusTrigger ，而佇列是由設定queueName。

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "msg",
      "type": "serviceBusTrigger",
      "direction": "in",
      "queueName": "inputqueue",
      "connection": "AzureServiceBusConnectionString"
    }
  ]
}

_init中的程式代碼_.py將參數宣告為 func.ServiceBusMessage，這可讓您讀取函式中的佇列訊息。

import azure.functions as func

import logging
import json

def main(msg: func.ServiceBusMessage):
    logging.info('Python ServiceBus queue trigger processed message.')

    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'expiration_time': msg.expiration_time,
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': msg.scheduled_enqueue_time,
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
        'metadata' : msg.metadata
    }, default=str)

    logging.info(result)

下列範例示範如何透過觸發程式讀取服務匯流排佇列主題。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="ServiceBusTopicTrigger1")
@app.service_bus_topic_trigger(arg_name="message", 
                               topic_name="TOPIC_NAME", 
                               connection="CONNECTION_SETTING", 
                               subscription_name="SUBSCRIPTION_NAME")
def test_function(message: func.ServiceBusMessage):
    message_body = message.get_body().decode("utf-8")
    logging.info("Python ServiceBus topic trigger processed message.")
    logging.info("Message Body: " + message_body)

服務匯流排系結定義於 function.json，其中 type 設定為 serviceBusTrigger ，而主題是由設定topicName。

{
  "scriptFile": "__init__.py",
  "bindings": [
   {
     "type": "serviceBusTrigger",
     "direction": "in",
     "name": "msg",
     "topicName": "inputtopic",
     "connection": "AzureServiceBusConnectionString"
   }
  ]
}

_init中的程式代碼_.py將參數宣告為 func.ServiceBusMessage，這可讓您讀取函式中的主題。

import json

import azure.functions as azf


def main(msg: azf.ServiceBusMessage) -> str:
    result = json.dumps({
        'message_id': msg.message_id,
        'body': msg.get_body().decode('utf-8'),
        'content_type': msg.content_type,
        'delivery_count': msg.delivery_count,
        'expiration_time': (msg.expiration_time.isoformat() if
                            msg.expiration_time else None),
        'label': msg.label,
        'partition_key': msg.partition_key,
        'reply_to': msg.reply_to,
        'reply_to_session_id': msg.reply_to_session_id,
        'scheduled_enqueue_time': (msg.scheduled_enqueue_time.isoformat() if
                                   msg.scheduled_enqueue_time else None),
        'session_id': msg.session_id,
        'time_to_live': msg.time_to_live,
        'to': msg.to,
        'user_properties': msg.user_properties,
    })

    logging.info(result)

屬性

進程內和隔離的背景工作進程 C# 連結庫都會使用 ServiceBusTriggerAttribute 屬性來定義函式觸發程式。 C# 文稿會改用function.json組態檔，如 C# 腳本指南中所述。

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

下表說明您可以使用這個觸發程式屬性來設定的屬性：

屬性	說明
QueueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
TopicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
SubscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
[連接]	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。
IsBatched	訊息會以批次方式傳遞。需要數位或集合類型。
IsSessionsEnabled	如果連接到工作階段感知佇列或訂用帳戶，則為 `true`。否則為 `false`，其為預設值。
AutoCompleteMessages	`true` 如果觸發程式應該在成功叫用之後自動完成訊息，則為。 `false` 如果不應該，則為，例如當您在程式代碼中處理訊息結算時。如果未明確設定，行為會以中的`host.json`組`autoCompleteMessages`態為基礎。

下表說明您可以使用這個觸發程式屬性來設定的屬性：

屬性	說明
QueueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
TopicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
SubscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
[連接]	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。
存取權限	連接字串的存取權限。可用值為 `manage` 和 `listen`。預設值是 `manage`，這表示 `connection` 已具備管理權限。如果您使用沒有管理權限的連接字串，請將 `accessRights` 設定為 "listen"。否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。在 Azure Functions 版本 2.x 及以上版本中，無法使用此屬性，因為最新版的服務匯流排 SDK 不支援管理作業。
IsBatched	訊息會以批次方式傳遞。需要數位或集合類型。
IsSessionsEnabled	如果連接到工作階段感知佇列或訂用帳戶，則為 `true`。否則為 `false`，其為預設值。
AutoComplete	`true` 觸發程式是否應該在處理之後自動呼叫完成，或函式程式代碼是否會手動呼叫完成。如果設定為 `true` 且觸發程序在函式執行成功完成，那麼觸發程序會自動完成訊息，否則會放棄訊息。設定為 `false`時，您必須負責呼叫 ServiceBusReceiver 方法來完成、放棄或將訊息、會話或批次失效。擲回例外狀況 (未呼叫任何 `ServiceBusReceiver` 方法) 時，鎖定會維持不變。一旦鎖定到期，訊息就會以遞增的 `DeliveryCount` 重新排入佇列，並自動更新鎖定。

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

裝飾項目

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

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

屬性	說明
`arg_name`	代表函式程式碼中佇列或主題訊息的變數名稱。
`queue_name`	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
`connection`	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。

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

註釋

批ServiceBusQueueTrigger注可讓您建立函式，以在建立服務匯流排佇列訊息時執行。可用的群組態選項包括下列屬性：

屬性	描述
name	代表函式程式碼中佇列或主題訊息的變數名稱。
queueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
topicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
subscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
connection	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。

批 ServiceBusTopicTrigger 注可讓您指定主題和訂用帳戶，以鎖定哪些數據觸發函式。

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

如需詳細資訊，請參閱觸發程式範例。

組態

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

模型 v4
模型 v3

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

屬性	說明
queueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
topicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
subscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
connection	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。
accessRights	連接字串的存取權限。可用值為 `manage` 和 `listen`。預設值是 `manage`，這表示 `connection` 已具備管理權限。如果您使用沒有管理權限的連接字串，請將 `accessRights` 設定為 "listen"。否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。在 Azure Functions 版本 2.x 及以上版本中，無法使用此屬性，因為最新版的服務匯流排 SDK 不支援管理作業。
isSessionsEnabled	如果連接到工作階段感知佇列或訂用帳戶，則為 `true`。否則為 `false`，其為預設值。
autoComplete	必須是 `true` 非 C# 函式，這表示觸發程式應該在處理之後自動呼叫完成，或函式程式代碼手動呼叫完成。當設定為 `true`時，觸發程式會在函式執行順利完成時自動完成訊息，否則會放棄訊息。函式中的例外狀況會導致背景中的運行時間呼叫 `abandonAsync` 。如果沒有發生例外狀況，則會 `completeAsync` 在背景中呼叫。此屬性僅適用於 Azure Functions 2.x 和更新版本。

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

屬性	描述
type	必須設定為 `serviceBusTrigger`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為「in」。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中佇列或主題訊息的變數名稱。
queueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
topicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
subscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
connection	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。
accessRights	連接字串的存取權限。可用值為 `manage` 和 `listen`。預設值是 `manage`，這表示 `connection` 已具備管理權限。如果您使用沒有管理權限的連接字串，請將 `accessRights` 設定為 "listen"。否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。在 Azure Functions 版本 2.x 及以上版本中，無法使用此屬性，因為最新版的服務匯流排 SDK 不支援管理作業。
isSessionsEnabled	如果連接到工作階段感知佇列或訂用帳戶，則為 `true`。否則為 `false`，其為預設值。
autoComplete	必須是 `true` 非 C# 函式，這表示觸發程式應該在處理之後自動呼叫完成，或函式程式代碼手動呼叫完成。當設定為 `true`時，觸發程式會在函式執行順利完成時自動完成訊息，否則會放棄訊息。函式中的例外狀況會導致背景中的運行時間呼叫 `abandonAsync` 。如果沒有發生例外狀況，則會 `completeAsync` 在背景中呼叫。此屬性僅適用於 Azure Functions 2.x 和更新版本。

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

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

function.json 屬性	描述
type	必須設定為 `serviceBusTrigger`。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction	必須設定為「in」。當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name	代表函式程式碼中佇列或主題訊息的變數名稱。
queueName	要監視的佇列名稱。只有在監視佇列時設定 (不適用於主題)。
topicName	要監視的主題名稱。只有在監視主題時設定 (不適用於佇列)。
subscriptionName	要監視的訂用帳戶名稱。只有在監視主題時設定 (不適用於佇列)。
connection	指定如何連線到服務匯流排的應用程式設定或設定集合名稱。請參閱連線。
accessRights	連接字串的存取權限。可用值為 `manage` 和 `listen`。預設值是 `manage`，這表示 `connection` 已具備管理權限。如果您使用沒有管理權限的連接字串，請將 `accessRights` 設定為 "listen"。否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。在 Azure Functions 版本 2.x 及以上版本中，無法使用此屬性，因為最新版的服務匯流排 SDK 不支援管理作業。
isSessionsEnabled	如果連接到工作階段感知佇列或訂用帳戶，則為 `true`。否則為 `false`，其為預設值。
autoComplete	必須是 `true` 非 C# 函式，這表示觸發程式應該在處理之後自動呼叫完成，或函式程式代碼手動呼叫完成。當設定為 `true`時，觸發程式會在函式執行順利完成時自動完成訊息，否則會放棄訊息。函式中的例外狀況會導致背景中的運行時間呼叫 `abandonAsync` 。如果沒有發生例外狀況，則會 `completeAsync` 在背景中呼叫。此屬性僅適用於 Azure Functions 2.x 和更新版本。

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

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

使用方式

所有 C# 形式和延伸模組版本都支援下列參數類型：

類型	描述
System.String	當訊息為簡單文字時，請使用。
byte[]	用於二進位數據訊息。
Object	當訊息包含 JSON 時，Functions 會嘗試將 JSON 數據還原串行化為已知的純舊 CLR 物件類型。

傳訊特定參數類型包含其他訊息元數據。服務匯流排觸發程式支援的特定類型取決於 Functions 執行時間版本、擴充套件版本，以及所使用的 C# 形式。

使用 ServiceBusReceivedMessage 類型，從佇列和訂用帳戶服務匯流排接收訊息元數據。若要深入瞭解，請參閱訊息、承載和串行化。

在 C# 類別庫中，屬性的建構函式會採用佇列或主題和訂用帳戶的名稱。

您也可以使用 ServiceBusAccountAttribute 來指定要使用的服務匯流排帳戶。建構函式會採用包含服務匯流排連接字串的應用程式設定名稱。屬性可以在參數、方法或類別層級套用。下列範例顯示類別層級和方法層級：

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

要使用的服務匯流排帳戶會依下列順序決定：

屬性 ServiceBusTrigger 的 Connection 屬性。
套 ServiceBusAccount 用至與屬性相同的參數 ServiceBusTrigger 的屬性。
套 ServiceBusAccount 用至函式的屬性。
套 ServiceBusAccount 用至類別的屬性。
應用程式 AzureWebJobsServiceBus 設定。

使用訊息類型來接收具有元數據的訊息。若要深入瞭解，請參閱訊息、承載和串行化。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但它們將不再收到 Microsoft 的官方支援和更新。如需詳細資訊，請參閱支援淘汰公告。

在 C# 類別庫中，屬性的建構函式會採用佇列或主題和訂用帳戶的名稱。

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

要使用的服務匯流排帳戶會依下列順序決定：

屬性 ServiceBusTrigger 的 Connection 屬性。
套 ServiceBusAccount 用至與屬性相同的參數 ServiceBusTrigger 的屬性。
套 ServiceBusAccount 用至函式的屬性。
套 ServiceBusAccount 用至類別的屬性。
應用程式 AzureWebJobsServiceBus 設定。

下列參數類型適用於佇列或主題訊息：

BrokeredMessage - 提供您使用 BrokeredMessage.GetBody<T>（）方法來還原串行化訊息。
MessageReceiver - 用來接收和認可訊息容器中的訊息，當設定為 false時autoComplete，這是必要的。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但它們將不再收到 Microsoft 的官方支援和更新。如需詳細資訊，請參閱支援淘汰公告。

在 C# 類別庫中，屬性的建構函式會採用佇列或主題和訂用帳戶的名稱。在 Azure Functions 1.x 版中，您也可以指定連線的訪問許可權。如果您未指定存取權限，預設值為 Manage。

[ServiceBusAccount("ClassLevelServiceBusAppSetting")]
public static class AzureFunctions
{
    [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
    [FunctionName("ServiceBusQueueTriggerCSharp")]
    public static void Run(
        [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
        string myQueueItem, ILogger log)
{
    ...
}

要使用的服務匯流排帳戶會依下列順序決定：

屬性 ServiceBusTrigger 的 Connection 屬性。
套 ServiceBusAccount 用至與屬性相同的參數 ServiceBusTrigger 的屬性。
套 ServiceBusAccount 用至函式的屬性。
套 ServiceBusAccount 用至類別的屬性。
應用程式 AzureWebJobsServiceBus 設定。

當您想要讓函式處理單一訊息時，服務匯流排觸發程式可以繫結至下列類型：

類型	描述
`string`	以字串表示的訊息。當訊息為簡單文字時，請使用。
`byte[]`	訊息的位元組。
JSON 可序列化型別	當事件包含 JSON 數據時，Functions 會嘗試將 JSON 數據還原串行化為一般舊的 CLR 物件（POCO）類型。
ServiceBusReceivedMessage¹	訊息物件。系結至 `ServiceBusReceivedMessage`時，您也可以選擇性地包含 ServiceBusMessageActions^1,2 類型的參數來執行訊息結算動作。

當您想要讓函式處理一批訊息時，服務匯流排觸發程式可以繫結至下列類型：

類型	描述
`T[]` 其中 `T` 是其中一種單一訊息類型	來自批次的事件陣列。每個專案都代表一個事件。系結至 `ServiceBusReceivedMessage[]`時，您也可以選擇性地包含 ServiceBusMessageActions^1,2 類型的參數來執行訊息結算動作。

¹ 若要使用這些類型，您必須參考 Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 或更新版本，以及 SDK 類型系結的常見相依性。

² 使用 ServiceBusMessageActions時，將觸發程式屬性的屬性設定AutoCompleteMessages為 false。這可防止運行時間在成功函式調用之後嘗試完成訊息。

Connection未定義屬性時，Functions 會尋找名為 AzureWebJobsServiceBus的應用程式設定，這是服務匯流排連接字串的預設名稱。您也可以設定 Connection 屬性來指定應用程式設定的名稱，其中包含要使用的服務匯流排連接字串。

傳入服務匯流排訊息可透過 ServiceBusQueueMessage 或 ServiceBusTopicMessage 參數取得。

模型 v4
模型 v3

存取佇列或主題訊息作為函式的第一個自變數。服務匯流排訊息會以字串或 JSON 物件的形式傳遞至函式。

服務匯流排實例可透過function.json檔案名稱屬性中設定的參數來取得。

佇列訊息可透過類型為 func.ServiceBusMessage的參數提供給函式。服務匯流排訊息會以字串或 JSON 物件的形式傳遞至函式。

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

連線

屬性connection是環境組態的參考，指定應用程式應該如何連線到服務匯流排。此屬性可以指定：

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

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

Connection string

若要取得連接字串，請遵循取得管理認證中所述的步驟。連接字串必須是服務匯流排命名空間，不限於特定佇列或主題。

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

如果應用程式設定名稱以「AzureWebJobs」開頭，則您只能指定名稱的其餘部分。例如，如果您設定 connection 為「MyServiceBus」，Functions 運行時間會尋找名為 “AzureWebJobsMyServiceBus” 的應用程式設定。如果您保留connection空白，Functions 運行時間會在名為 “AzureWebJobsServiceBus” 的應用程式設定中使用預設服務匯流排連接字串。

身分識別型連線

如果您使用 5.x 版或更高版本的延伸模組，而不是使用具有秘密的連接字串，您可以讓應用程式使用 Microsoft Entra 身分識別。若要執行此動作，您會在對應至觸發程序和繫結設定中 connection 屬性的通用前置詞下定義設定。

在此模式中，延伸模組需要下列屬性：

屬性	環境變數範本	描述	範例值
完整命名空間	`<CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace`	完整服務匯流排命名空間。	<>service_bus_namespace.servicebus.windows.net

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

注意

使用 Azure 應用程式組態或 Key Vault 來提供「受控識別」連線的設定時，設定名稱應使用有效的索引鍵分隔符號，例如：: 或 / 取代 __，以確保正確解析名稱。

例如： <CONNECTION_NAME_PREFIX>:fullyQualifiedNamespace 。

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

授與權限給身分識別

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

重要

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

您必須建立可在執行時間存取您主題和佇列的角色指派。擁有者類似的管理角色不足。下列資料表顯示在一般作業中使用服務匯流排延伸模組時建議的內建角色。您的應用程式可能會根據您寫入的程式碼要求額外的權限。

繫結類型	內建角色範例
Trigger¹	Azure 服務匯流排資料接收者、Azure 服務匯流排資料擁有者
輸出繫結	Azure 服務匯流排資料傳送者

¹ 若要從服務匯流排主題觸發，角色指派需要具有服務匯流排訂用帳戶資源的有效範圍。如果只包含主題，則會發生錯誤。 Azure 入口網站等部分用戶端不會將服務匯流排訂用帳戶資源公開為角色指派的範圍。在這種情況下，可以改用 Azure CLI。如需深入了解，請參閱 Azure 服務匯流排的 Azure 內建角色。

有害訊息

無法在 Azure Functions 中控制或設定有害訊息處理。服務匯流排處理有害訊息本身。

PeekLock 行為

Functions 運行時間會以 PeekLock 模式接收訊息。

根據預設，如果函式順利完成，則運行時間會在訊息上呼叫 Complete ，如果函式失敗，則會呼叫 Abandon 。您可以使用中的host.json屬性停用自動完成autoCompleteMessages。

根據預設，如果函式順利完成，則運行時間會在訊息上呼叫 Complete ，如果函式失敗，則會呼叫 Abandon 。您可以使用中的 host.json 屬性，或透過觸發程式屬性上的屬性停用自動完成autoCompleteMessages。如果您的函式程式碼處理訊息結算，您應該停用自動完成。

如果函式執行的時間超過 PeekLock 逾時，只要函式正在執行，就會自動更新鎖定。 maxAutoRenewDuration可在 host.json 中設定，其對應至 ServiceBusProcessor.MaxAutoLockRenewalDuration。此設定的預設值為 5 分鐘。

訊息元數據

傳訊特定類型可讓您輕鬆地擷取元數據做為對象的屬性。這些屬性取決於 Functions 運行時間版本、擴充套件版本，以及所使用的 C# 形式。

這些屬性是 ServiceBusReceivedMessage 類別的成員。

屬性	類型	描述
`ApplicationProperties`	`ApplicationProperties`	傳送者所設定的屬性。
`ContentType`	`string`	傳送者和接收者用於應用程式特定邏輯的內容類型標識碼。
`CorrelationId`	`string`	相互關連識別碼。
`DeliveryCount`	`Int32`	交付次數。
`EnqueuedTime`	`DateTime`	UTC 加入佇列的時間。
`ScheduledEnqueueTimeUtc`	`DateTime`	以UTC排程加入佇列的時間。
`ExpiresAt`	`DateTime`	UTC 的到期時間。
`MessageId`	`string`	用戶定義值，如果啟用，服務匯流排可用來識別重複的訊息。
`ReplyTo`	`string`	佇列位址的回復。
`Subject`	`string`	應用程式特定的標籤，可用來取代 `Label` 元資料屬性。
`To`	`string`	傳送至位址。

這些屬性是 Message 類別的成員。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但它們將不再收到 Microsoft 的官方支援和更新。如需詳細資訊，請參閱支援淘汰公告。

屬性	類型	描述
`ContentType`	`string`	傳送者和接收者用於應用程式特定邏輯的內容類型標識碼。
`CorrelationId`	`string`	相互關連識別碼。
`DeliveryCount`	`Int32`	交付次數。
`ScheduledEnqueueTimeUtc`	`DateTime`	以UTC排程加入佇列的時間。
`ExpiresAtUtc`	`DateTime`	UTC 的到期時間。
`Label`	`string`	應用程式特定的標籤。
`MessageId`	`string`	用戶定義值，如果啟用，服務匯流排可用來識別重複的訊息。
`ReplyTo`	`string`	佇列位址的回復。
`To`	`string`	傳送至位址。
`UserProperties`	`IDictionary<string, object>`	傳送者所設定的屬性。

這些屬性是 BrokeredMessage 和 MessageReceiver 類別的成員。

在 2026 年 9 月 30 日，我們將淘汰不符合 Azure SDK 準則的 Azure 服務匯流排 SDK 程式庫 WindowsAzure.ServiceBus、Microsoft.Azure.ServiceBus 和 com.microsoft.azure.servicebus。我們也將結束 SBMP 通訊協定的支援，因此您將無法在 2026 年 9 月 30 日之後再使用此通訊協定。請在該日期之前移轉至最新的 Azure SDK 程式庫，該程式庫提供重要的安全性更新和改進的功能。

雖然較舊的程式庫仍可在 2026 年 9 月 30 日之後使用，但它們將不再收到 Microsoft 的官方支援和更新。如需詳細資訊，請參閱支援淘汰公告。

屬性	類型	描述
`ContentType`	`string`	傳送者和接收者用於應用程式特定邏輯的內容類型標識碼。
`CorrelationId`	`string`	相互關連識別碼。
`DeadLetterSource`	`string`	寄不出的信件來源。
`DeliveryCount`	`Int32`	交付次數。
`EnqueuedTimeUtc`	`DateTime`	UTC 加入佇列的時間。
`ExpiresAtUtc`	`DateTime`	UTC 的到期時間。
`Label`	`string`	應用程式特定的標籤。
`MessageId`	`string`	用戶定義值，如果啟用，服務匯流排可用來識別重複的訊息。
`MessageReceiver`	`MessageReceiver`	服務匯流排訊息接收者。可用來放棄、完成或使訊息失效。
`MessageSession`	`MessageSession`	特別適用於已啟用會話的佇列和主題的訊息接收者。
`ReplyTo`	`string`	佇列位址的回復。
`SequenceNumber`	`long`	服務匯流排指派給訊息的唯一號碼。
`To`	`string`	傳送至位址。
`UserProperties`	`IDictionary<string, object>`	傳送者所設定的屬性。

這些屬性是 ServiceBusReceivedMessage 類別的成員。

屬性	類型	描述
`ApplicationProperties`	`ApplicationProperties`	傳送者所設定的屬性。
`ContentType`	`string`	傳送者和接收者用於應用程式特定邏輯的內容類型標識碼。
`CorrelationId`	`string`	相互關連識別碼。
`DeliveryCount`	`Int32`	交付次數。
`EnqueuedTime`	`DateTime`	UTC 加入佇列的時間。
`ScheduledEnqueueTimeUtc`	`DateTime`	以UTC排程加入佇列的時間。
`ExpiresAt`	`DateTime`	UTC 的到期時間。
`MessageId`	`string`	用戶定義值，如果啟用，服務匯流排可用來識別重複的訊息。
`ReplyTo`	`string`	佇列位址的回復。
`Subject`	`string`	應用程式特定的標籤，可用來取代 `Label` 元資料屬性。
`To`	`string`	傳送至位址。

下一步

從 Azure Functions 傳送 Azure 服務匯流排訊息 (輸出繫結)

共用方式為

Azure Functions 的 Azure 服務匯流排觸發程序

範例

屬性

裝飾項目

註釋

組態

使用方式

連線

Connection string

身分識別型連線

授與權限給身分識別

有害訊息

PeekLock 行為

訊息元數據

下一步

意見反應

其他資源