Azure 服務匯流排Azure Functions的輸出系結

使用 Azure 服務匯流排輸出繫結來傳送佇列或主題訊息。

如需安裝和設定詳細資料的相關資訊,請參閱概觀

範例

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

  • 同進程類別庫:在與 Functions 執行時間相同的進程中執行的已編譯 C# 函式。
  • 隔離進程類別庫:在與執行時間隔離的進程中執行的已編譯 C# 函式。 需要隔離的程式,才能支援在 .NET 5.0 上執行的 C# 函式。
  • C# 腳本:主要是在 Azure 入口網站 中建立 C# 函式時使用。

下列範例示範的 C# 函式可記錄服務匯流排佇列訊息:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string ServiceBusOutput([HttpTrigger] dynamic input, ILogger log)
{
    log.LogInformation($"C# function processed: {input.Text}");
    return input.Text;
}

下列範例顯示 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 類型的 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();

    }

下列範例示範 function.json 檔案中的服務匯流排觸發程序繫結,以及使用此繫結的 JavaScript 函式。 此函式會使用計時器觸發程序,每隔 15 秒傳送一則佇列訊息。

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

{
    "bindings": [
        {
            "schedule": "0/15 * * * * *",
            "name": "myTimer",
            "runsOnStartup": true,
            "type": "timerTrigger",
            "direction": "in"
        },
        {
            "name": "outputSbQueue",
            "type": "serviceBus",
            "queueName": "testqueue",
            "connection": "MyServiceBusConnection",
            "direction": "out"
        }
    ],
    "disabled": false
}

以下是可建立單一訊息的 JavaScript 指令碼程式碼:

module.exports = async function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = message;
};

以下是可建立多則訊息的 JavaScript 指令碼程式碼:

module.exports = async function (context, myTimer) {
    var message = 'Service Bus queue message created at ' + timeStamp;
    context.log(message);   
    context.bindings.outputSbQueue = [];
    context.bindings.outputSbQueue.push("1 " + message);
    context.bindings.outputSbQueue.push("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 中寫出服務匯流排佇列。

服務匯流排系結定義是在function.json中定義,其中 type設定為 serviceBus

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

_init_.py中,您可以將值傳遞至 方法,將訊息寫出至 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'

屬性

進程內隔離進程C# 程式庫都會使用 屬性來定義輸出系結。 C# 腳本會改用 function.json 組態檔。

C# 類別程式庫中,使用 ServiceBusAttribute

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

屬性 描述
QueueName 佇列的名稱。 只有在傳送佇列訊息時設定 (不適用於主題)。
TopicName 主題的名稱。 只有在傳送主題訊息時設定 (不適用於佇列)。
[連接] 指定如何連線至服務匯流排的應用程式設定或設定集合名稱。 請參閱 連線
存取 連接字串的存取權限。 可用值為 managelisten。 預設值是 manage,這表示 connection 已具備管理權限。 如果您使用沒有管理權限的連接字串,請將 accessRights 設定為 "listen"。 否則,Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。 在 Azure Functions 2.x 版和更新版本中,無法使用此屬性,因為最新版本的 服務匯流排 SDK 不支援管理作業。

以下範例顯示套用至函式傳回值的屬性:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

您可以設定 Connection 屬性來指定應用程式設定的名稱,其中包含要使用的服務匯流排連接字串,如下列範例所示:

[FunctionName("ServiceBusOutput")]
[return: ServiceBus("myqueue", Connection = "ServiceBusConnection")]
public static string Run([HttpTrigger] dynamic input, ILogger log)
{
    ...
}

如需完整範例,請參閱 範例

您可以使用 ServiceBusAccount 屬性來指定要在類別、方法或參數層級使用的服務匯流排帳戶。 如需詳細資訊,請參閱觸發程式參考中的 屬性

註解

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

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

組態

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

function.json 屬性 描述
type 必須設為 "serviceBus"。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。
direction 必須設定為 "out"。 當您在 Azure 入口網站中建立觸發程序時,會自動設定此屬性。
name 代表函式程式碼中佇列或主題訊息的變數名稱。 設為 "$return" 以參考函式傳回值。
queueName 佇列的名稱。 只有在傳送佇列訊息時設定 (不適用於主題)。
topicName 主題的名稱。 只有在傳送主題訊息時設定 (不適用於佇列)。
connection 指定如何連線至服務匯流排的應用程式設定或設定集合名稱。 請參閱 連線
僅限 accessRights (v1) 連接字串的存取權限。 可用值為 managelisten。 預設值是 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# 形式。

使用中繼資料傳送訊息時,請使用 ServiceBusMessage 類型。 參數定義為 return 類型屬性。 ICollector<T>使用 或 IAsyncCollector<T> 來寫入多個訊息。 當您呼叫 Add 方法時,就會建立一則訊息。

當函式結束時的參數值為 Null 時,Functions 不會建立訊息。

您也可以使用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 設定。

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

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

使用 context.bindings.<name from function.json> 存取佇列或主題。 您可以將字串、位元組陣列或 JavaScript 物件指派 (還原序列化為 JSON) 。 context.binding.<name>

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

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

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

連接

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

如果設定的值是單一設定的完全相符專案,而前置詞符合其他設定,則會使用完全相符專案。

連接字串

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

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

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

以身分識別為基礎的連線

如果您使用 5.x 版或更高版本的擴充功能,而不是使用連接字串搭配秘密,您可以讓應用程式使用Azure Active Directory身分識別。 若要這樣做,您會在通用前置詞下定義設定,以對應至 connection 觸發程式和系結組態中的 屬性。

在此模式中,延伸模組需要下列屬性:

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

其他屬性可以設定為自訂連線。 請參閱 身分識別型連線的一般屬性

裝載于Azure Functions服務時,以身分識別為基礎的連線會使用受控識別。 預設會使用系統指派的身分識別,不過可以使用 和 clientID 屬性來指定 credential 使用者指派的身分識別。 在其他內容中執行時,例如本機開發,會改用您的開發人員身分識別,雖然可以自訂。 請參閱 使用身分識別型連線進行本機開發

授與身分識別的許可權

使用的任何身分識別都必須具有執行預期動作的許可權。 您必須使用提供這些許可權的內建角色或自訂角色,在 Azure RBAC 中指派角色

重要

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

您必須建立角色指派,以在執行時間存取您的主題和佇列。 擁有者之類的管理角色不足。 下表顯示一般作業中使用 服務匯流排 擴充功能時建議的內建角色。 您的應用程式可能會根據您撰寫的程式碼要求額外的許可權。

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

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

例外狀況和傳回碼

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

下一步