共用方式為

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

此程式代碼會定義並初始化 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;
}

 

此範例會使用 HTTP 觸發程式搭配 OutputType 對象來傳送 HTTP 回應並寫入輸出訊息。

[Function("HttpSendMsg")]
public async Task<OutputType> Run([HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req, FunctionContext context)
{
   _logger.LogInformation($"C# HTTP trigger function processed a request for {context.InvocationId}.");

   HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
   await response.WriteStringAsync("HTTP response: Message sent");

   return new OutputType()
   {
       OutputEvent = "MyMessage",
       HttpResponse = response
   };
}

此程式代碼會定義多個輸出類型OutputType，其中包含上的 OutputEvent服務匯流排 輸出系結定義：

 public class OutputType
{
   [ServiceBusOutput("TopicOrQueueName", Connection = "ServiceBusConnection")]
   public string OutputEvent { get; set; }

   public HttpResponseData HttpResponse { get; set; }
}

下列範例顯示 Java 函式，會在 HTTP 要求觸發時，將訊息傳送至 服務匯流排 佇列myqueue。

@FunctionName("httpToServiceBusQueue")
@ServiceBusQueueOutput(name = "message", queueName = "myqueue", connection = "AzureServiceBusConnection")
public String pushToQueue(
  @HttpTrigger(name = "request", methods = {HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS)
  final String message,
  @HttpOutput(name = "response") final OutputBinding<T> result ) {
      result.setValue(message + " has been sent.");
      return message;
 }

在 Java 函式運行時間連結庫中，對@QueueOutput將值寫入 服務匯流排 佇列的函式參數上使用註釋。 參數類型應該是 OutputBinding<T>，其中 T 是計劃舊 Java 物件的任何原生 Java 類型 （POJO）。

Java 函式也可以寫入 服務匯流排 主題。 下列範例會 @ServiceBusTopicOutput 使用 註釋來描述輸出系結的組態。

@FunctionName("sbtopicsend")
    public HttpResponseMessage run(
            @HttpTrigger(name = "req", methods = {HttpMethod.GET, HttpMethod.POST}, authLevel = AuthorizationLevel.ANONYMOUS) HttpRequestMessage<Optional<String>> request,
            @ServiceBusTopicOutput(name = "message", topicName = "mytopicname", subscriptionName = "mysubscription", connection = "ServiceBusConnection") OutputBinding<String> message,
            final ExecutionContext context) {

        String name = request.getBody().orElse("Azure Functions");

        message.setValue(name);
        return request.createResponseBuilder(HttpStatus.OK).body("Hello, " + name).build();

    }

下列範例顯示定時器觸發的 TypeScript 函式 ，每 5 分鐘傳送佇列訊息一次。

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

export async function timerTrigger1(myTimer: Timer, context: InvocationContext): Promise<string> {
    const timeStamp = new Date().toISOString();
    return `Message created at: ${timeStamp}`;
}

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: output.serviceBusQueue({
        queueName: 'testqueue',
        connection: 'MyServiceBusConnection',
    }),
    handler: timerTrigger1,
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

下列範例顯示定時器觸發的 JavaScript 函式 ，每 5 分鐘傳送佇列訊息一次。

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

const serviceBusOutput = output.serviceBusQueue({
    queueName: 'testqueue',
    connection: 'MyServiceBusConnection',
});

app.timer('timerTrigger1', {
    schedule: '0 */5 * * * *',
    return: serviceBusOutput,
    handler: (myTimer, context) => {
        const timeStamp = new Date().toISOString();
        return `Message created at: ${timeStamp}`;
    },
});

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

const timeStamp = new Date().toISOString();
const message = `Message created at: ${timeStamp}`;
return [`1: ${message}`, `2: ${message}`];

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

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

{
  "bindings": [
    {
      "type": "serviceBus",
      "direction": "out",
      "connection": "AzureServiceBusConnectionString",
      "name": "outputSbMsg",
      "queueName": "outqueue",
      "topicName": "outtopic"
    }
  ]
}

以下是建立訊息做為函式輸出的PowerShell。

param($QueueItem, $TriggerMetadata) 

Push-OutputBinding -Name outputSbMsg -Value @{ 
    name = $QueueItem.name 
    employeeId = $QueueItem.employeeId 
    address = $QueueItem.address 
}

下列範例示範如何在 Python 中寫出至 服務匯流排 佇列。 此範例取決於您使用的是 v1 或 v2 Python 程式設計模型。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_topic_output(arg_name="message",
                              connection="<CONNECTION_SETTING>",
                              topic_name="<TOPIC_NAME>")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

屬性

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

在 C# 類別庫中，使用 ServiceBusOutputAttribute 來定義輸出所寫入的佇列或主題。

下表說明您可以使用 屬性設定的屬性：

屬性 說明
EntityType 將實體類型設定為 Queue 將訊息傳送至佇列，或 Topic 將訊息傳送至主題時。
QueueOrTopicName 要傳送訊息的主題或佇列名稱。 使用 EntityType 來設定目的地類型。
[連接] 指定如何連線到服務匯流排的應用程式設定或設定集合名稱。 請參閱連線。

裝飾項目

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

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

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

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

註釋

ServiceBusQueueOutput和 ServiceBusTopicOutput 批註可用來將訊息寫入為函式輸出。 以這些註釋裝飾的參數必須宣告為 OutputBinding<T> ，其中 T 是對應至訊息類型的類型。

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

組態

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

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

屬性 說明
queueName 待辦事項的名稱。
connection 指定如何連線到服務匯流排的應用程式設定或設定集合名稱。 請參閱連線。

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

屬性 說明
topicName 主題的名稱。
connection 指定如何連線到服務匯流排的應用程式設定或設定集合名稱。 請參閱連線。

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

下表說明您在 function.json 檔案和 ServiceBus 屬性中設定的系結組態屬性。

function.json 屬性 描述
type 必須設定為 serviceBus。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
direction 必須設定為 out。 當您在 Azure 入口網站中建立觸發程序時，會自動設定此屬性。
name 代表函式程式碼中佇列或主題訊息的變數名稱。 設為 "$return" 以參考函式傳回值。
queueName 待辦事項的名稱。 只有在傳送佇列訊息時設定 (不適用於主題)。
topicName 主題的名稱。 只有在傳送主題訊息時設定 (不適用於佇列)。
connection 指定如何連線到服務匯流排的應用程式設定或設定集合名稱。 請參閱連線。
accessRights (僅限 v1) 連接字串的存取權限。 可用值為 manage 和 listen。 預設值是 manage，這表示 connection 已具備管理權限。 如果您使用沒有 [管理] 許可權的 連接字串，請將 設定accessRights為 [接聽]。 否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。 在 Azure Functions 2.x 版和更新版本中，無法使用此屬性，因為最新版本的 服務匯流排 SDK 不支援管理作業。

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

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

使用方式

所有 C# 形式與擴充功能版本都支援下列輸出參數類型：

類型 描述
System.String 當要寫入的訊息是簡單的文字時，請使用 。 當函式結束時，參數值為 Null 時，Functions 不會建立訊息。
byte[] 用於寫入二進位數據訊息。 當函式結束時，參數值為 Null 時，Functions 不會建立訊息。
Object 當訊息包含 JSON 時，Functions 會將物件串行化為 JSON 訊息承載。 當函式結束時，參數值為 Null 時，Functions 會建立具有 Null 物件的訊息。

傳訊特定參數類型包含額外的訊息元數據，且與 JSON 串行化不相容。 因此，無法與隔離模型中的輸出系結搭配使用 ServiceBusMesage 。 輸出系結所支援的特定類型取決於 Functions 執行時間版本、延伸模組套件版本，以及所使用的 C# 形式。

當您想要函式寫入單一訊息時，服務匯流排 輸出系結可以繫結至下列類型：

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

當您想要函式寫入多個訊息時，服務匯流排 輸出系結可以繫結至下列類型：

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

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

在 Azure Functions 1.x 中，運行時間會在佇列不存在且您已設定 accessRights 為 manage時建立佇列。 在 Azure Functions 2.x 版和更新版本中，佇列或主題必須已經存在;如果您指定不存在的佇列或主題，則函式會失敗。

使用 Azure 服務匯流排 SDK，而不是內建的輸出系結。

直接或使用 context.extraOutputs.set()傳回 值，以存取輸出訊息。

服務匯流排 的輸出可透過 Push-OutputBinding Cmdlet 取得，您可以在其中傳遞符合系結名稱參數在 function.json 檔案中指定名稱的自變數。

使用 Azure 服務匯流排 SDK，而不是內建的輸出系結。

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

連線

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

重要

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

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

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

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

例外狀況和傳回碼

繫結 參考
服務匯流排 服務匯流排 錯誤碼
服務匯流排 服務匯流排 限制

下一步