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

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

@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 是POJO的任何原生Java類型。

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 設定為 "listen"。 否則，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 物件的訊息。

傳訊特定參數類型包含其他訊息元數據。 輸出系結所支援的特定類型取決於 Functions 執行時間版本、延伸模組套件版本，以及所使用的 C# 形式。

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

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

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

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

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

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

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

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

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

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

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

連線

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

如果設定的值既與單一設定完全相符，又是其他設定的前置詞比對，則會使用完全相符專案。

連接字串

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

此 連接字串 應該儲存在應用程式設定中，其名稱符合系結組態的 屬性所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 中指派角色，以提供這些許可權。

重要

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

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

繫結類型 範例內建角色
觸發程式1 Azure 服務匯流排 數據接收器，Azure 服務匯流排 數據擁有者
輸出繫結 Azure 服務匯流排資料傳送者

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

例外狀況和傳回碼

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

下一步