Azure 服務匯流排 output binding for Azure Functions

使用 Azure 服務匯流排 輸出綁定來發送佇列或主題訊息。

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

重要

本文使用索引標籤來支援多個版本的 Node.js 程式設計模型。 v4 模型已正式推出,旨在為 JavaScript 和 TypeScript 開發人員提供更靈活且更直覺的體驗。 關於 v4 模型的更多運作細節,請參閱 Azure Functions Node.js 開發者指南。 若要深入了解 v3 與 v4 之間的差異,請參閱移轉指南。

Azure Functions 支援兩種 Python 程式設計模型。 您定義系結的方式取決於您所選擇的程式設計模型。

Python v2 程式設計模型允許你直接在 Python 函式程式碼中使用裝飾器來定義綁定。 更多資訊請參閱 Python 開發者指南。

本文支援這兩種程序設計模型。

範例

目前這款綁定沒有 Go 支援。

您可以使用下列其中一種 C# 模式來建立 C# 函式:

  • 隔離的背景工作模型:在與運行時間隔離的背景工作進程中執行的已編譯 C# 函式。 獨立工作程序必須支援在 LTS 及非 LTS 版本 .NET 與 .NET 框架上運行的 C# 函式。 孤立工作程序函式的擴充功能使用 Microsoft.Azure.Functions.Worker.Extensions.* 命名空間。
  • 同進程模型:在與 Functions 運行時間相同的進程中執行的已編譯 C# 函式。 在此模型的變化中,函式可以使用 C# 腳本來執行,主要支援 C# 入口網站編輯。 進行中功能的擴充功能使用 Microsoft.Azure.WebJobs.Extensions.* 命名空間。

此程式代碼會定義並初始化 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 functions 執行時函式庫 中,使用 @QueueOutput 註解,針對函式參數,其值會寫入 服務匯流排 佇列。 參數型別應為 OutputBinding<T>,其中 T 是計畫舊 Java 物件(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="AzureServiceBusConnectionString",
                              topic_name="outTopic")
def main(req: func.HttpRequest, message: func.Out[str]) -> func.HttpResponse:
    input_msg = req.params.get('message')
    message.set(input_msg)
    return 'OK'

此範例展示了如何寫入 服務匯流排 佇列。

import azure.functions as func

app = func.FunctionApp()

@app.route(route="put_message")
@app.service_bus_queue_output(
    arg_name="msg",
    connection="AzureServiceBusConnectionString",
    queue_name="outqueue")
def put_message(req: func.HttpRequest, msg: func.Out[str]):
    msg.set(req.get_body().decode('utf-8'))
    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函數,請參見 Configuration 章節。

註釋

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

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

組態

僅適用於 Python v1 程式模型。

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

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

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

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

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

下表說明您在 function.json系結組態屬性。

function.json 屬性 說明
類型 必須設定為 serviceBus。 這個屬性會在你在 Azure 入口網站建立觸發器時自動設定。
方向 必須設定為 out。 這個屬性會在你在 Azure 入口網站建立觸發器時自動設定。
名字 代表函式程式碼中佇列或主題訊息的變數名稱。 設為 "$return" 以參考函式傳回值。
queueName 待辦事項的名稱。 只有在傳送佇列訊息時設定 (不適用於主題)。
topicName 主題的名稱。 只有在傳送主題訊息時設定 (不適用於佇列)。
連接 指定如何連接 服務匯流排 的應用程式設定或設定集合名稱。 請參閱連線。

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

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

使用方式

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

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

傳訊特定參數類型包含額外的訊息元數據,且與 JSON 串行化不相容。 因此,無法與隔離模型中的輸出系結搭配使用 ServiceBusMessage 。 輸出綁定所支援的具體類型取決於擴充套件版本及所使用的 C# 模態。

當你希望函式只寫出單一訊息時,服務匯流排 輸出綁定可以綁定以下類型:

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

當你想讓函式寫多個訊息時,服務匯流排 輸出綁定可以綁定以下類型:

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

對於其他輸出情境,則建立並使用 ServiceBusClient,並搭配 Azure 中的其他類型。Messaging.ServiceBus 直接。 請參見 Register Azure clients,了解如何利用依賴注入從 Azure SDK 建立客戶端類型。

該佇列或主題必須已經存在;如果你指定一個不存在的佇列或主題,函式就會失敗。

請使用 Azure 服務匯流排 SDK,而非內建的輸出綁定。

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

輸出到 服務匯流排 可透過 Push-OutputBinding cmdlet 取得,該指令中傳遞與 binding 名稱參數在 function.json 檔案中指定的參數相符的參數。

輸出函式參數必須定義為 func.Out[str] 或 func.Out[bytes]。 如需詳細資訊,請參閱 輸出範例 。 或者,你也可以使用 Azure 服務匯流排 SDK,而非內建的輸出綁定。

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

連線

這個connection屬性是應用程式設定中一個鍵的參考,該鍵回傳 Functions 執行時用來連接擴充套件所用 服務匯流排 實例的值。 連線屬性設定的值取決於連線類型:

  • 管理身份連線:此connection屬性是由<CONNECTION_NAME_PREFIX>一組設定共享的,這些設定共同定義了與 服務匯流排 建立基於身份的連線。 欲了解更多資訊,請參閱定義身份連結。
  • 金鑰保存庫 參考:connection屬性設定會回傳一個 Azure Key Vault 的參考,指向該 連接字串 集中維護的位置。 欲了解更多資訊,請參閱定義 金鑰保存庫 連接。
  • App Configuration 參考:connection屬性設定回傳一個 Azure 應用程式組態 參考,該參考會回傳一個 連接字串 或 金鑰保存庫 參考。 欲了解更多資訊,請參閱連接條目中的 Azure 應用程式組態。
  • Connection string:屬性connection設定會回傳 服務匯流排 實例的實際 連接字串。 由於 連接字串 包含共享的秘密金鑰,建議在可能的情況下使用管理身份連線。 欲了解更多資訊,請參閱定義連結。

想了解更多關於綁定連接的資訊,請參閱 Azure Functions 中的「管理連線」。

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

如果應用程式設定名稱以 AzureWebJobs開頭,你只能指定名稱的其餘部分。 例如,如果你設定 connection 為 MyServiceBus,函式執行時會尋找一個名為 AzureWebJobsMyServiceBus的應用程式設定。 如果你留connection空,Functions 執行時會使用應用程式設定AzureWebJobsServiceBus中名為 的預設服務匯流排 連接字串。

擴容權限

服務匯流排 擴充功能使用 服務匯流排 Administration API (GetQueueRuntimePropertiesAsync / GetSubscriptionRuntimePropertiesAsync) 來取得精確的訊息計數以進行擴展決策。 此 API 需要額外權限,超出發送或接收訊息所需的權限:

  • SAS 連線字串:SAS 政策必須包含 管理 存取權限。
  • 基於身份的連線:身份必須被指派為 Azure 服務匯流排 資料擁有者角色,或包含 的自訂角色Microsoft.ServiceBus/namespaces/*/read。

當連線缺乏這些權限時,啟動時不會出現錯誤。 相反地,擴充功能默默回歸使用基於窺視的訊息估計,該方法準確度較低,可能導致延遲或錯誤的擴展決策。

小提示

對於依賴自動擴展的生產工作負載,請加入管理存取權(SAS)或指派 Azure 服務匯流排 資料擁有者角色(基於身份的連線),以確保擴展行為的準確性。 應用程式設定中名為 AzureWebJobsServiceBus的 連接字串 。

例外狀況和傳回碼

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

下一步