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

  • 發行項

使用服務匯流排觸發程序來回應來自服務匯流排佇列或主題的訊息。 從延伸模組 3.1.0 版開始，您便可以在啟用工作階段的佇列或主題上進行觸發了。

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

範例

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

  • 內含式類別庫：在與 Functions 執行階段相同的程序中執行的已編譯 C# 函式。
  • 隔離式背景工作處理序類別庫：在與執行階段隔離的背景工作處理序中執行的已編譯 C# 函數。 需要隔離式背景工作處理序，才能支援在非 LTS 版 .NET 和 .NET Framework 上執行的 C# 函數。
  • C# 指令碼：主要在 Azure 入口網站中建立 C# 函式時使用。

下列範例示範的 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 函式會使用 JAVA 函式執行階段程式庫中的 @ServiceBusQueueTrigger 注釋來描述服務匯流排佇列觸發程序的設定。 函式會擷取放在佇列上的訊息並新增至記錄。

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

下列範例示範 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"

下列範例示範如何透過觸發程序來讀取服務匯流排佇列訊息。

在 function.json 中定義服務匯流排繫結，其中類型設定為 serviceBusTrigger。

{
  "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)

屬性

內含式和隔離式背景工作處理序 C# 程式庫都使用 ServiceBusTriggerAttribute 屬性來定義函數觸發程序。 C# 指令碼會改用 function.json 設定檔。

下列資料表說明您可以使用此觸發程序屬性設定哪些屬性：

屬性 描述
QueueName 要監視的佇列名稱。 只有在監視佇列時設定 (不適用於主題)。
TopicName 要監視的主題名稱。 只有在監視主題時設定 (不適用於佇列)。
SubscriptionName 要監視的訂用帳戶名稱。 只有在監視主題時設定 (不適用於佇列)。
[連接] 指定如何連線到服務匯流排的應用程式設定或設定集合名稱。 請參閱連線。
存取 連接字串的存取權限。 可用值為 manage 和 listen。 預設值是 manage，這表示 connection 已具備管理權限。 如果您使用沒有管理權限的連接字串，請將 accessRights 設定為 "listen"。 否則，Functions 執行階段在嘗試執行需要管理權限的作業時可能會失敗。 在 Azure Functions 版本 2.x 及以上版本中，無法使用此屬性，因為最新版的服務匯流排 SDK 不支援管理作業。
IsBatched 訊息會以批次方式進行傳遞。 需要一種陣列或集合類型。
IsSessionsEnabled 如果連接到工作階段感知佇列或訂用帳戶，則為 true。 否則為 false，其為預設值。
AutoComplete 不管觸發程序是否應在處理之後自動呼叫完成，或函式程式碼是否會手動呼叫完成，都為 true。

如果設定為 true 且觸發程序在函式執行成功完成，那麼觸發程序會自動完成訊息，否則會放棄訊息。

當設定為 false 時，您負責呼叫 MessageReceiver 方法，以完成、放棄訊息，或使其無效化。 如果擲回例外狀況 (未呼叫任何 MessageReceiver 方法)，那麼鎖定會維持不變。 一旦鎖定到期，訊息就會以遞增的 DeliveryCount 重新排入佇列，並自動更新鎖定。

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

註解

ServiceBusQueueTrigger 註釋可讓您建立會在建立服務匯流排訊息時執行的函式。 可用的設定選項包括下列屬性：

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

ServiceBusTopicTrigger 注釋可讓您指定主題和訂用帳戶，以便把會觸發函式的資料當做目標。

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

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

組態

下表說明您在 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 針對非 C# 函式必須為 true，這表示觸發程序應該在處理後自動呼叫完成，或者函式程式碼要手動呼叫完成。

設定為 true 時，如果觸發程序在函式執行成功完成，那麼觸發程序會自動完成訊息，否則會放棄訊息。

函式中的例外狀況會在背景中產生執行階段呼叫 abandonAsync。 如果沒有發生例外狀況，則會在背景中呼叫 completeAsync。 此屬性僅適用於 Azure Functions 2.x 和更新版本。

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

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

使用方式

所有 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 應用程式設定。

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

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

使用 context.bindings.<name from function.json> 來存取佇列或主題訊息。 服務匯流排訊息會以字串或 JSON 物件的形式傳遞至函式。

您可以針對 function.json 檔案中的名稱屬性，透過在該屬性中設定的參數取得服務匯流排執行個體。

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

如需完整範例，請參閱範例區段。

連線

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

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

連接字串

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

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

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

身分識別型連線

如果您正在使用版本 5.x 或更新版本的延伸模組，而不是使用具有祕密連接字串，您可以讓應用程式使用 Azure Active Directory 身分識別。 若要執行此動作，您會在對應至觸發程序和繫結設定中 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 內建角色。

有害訊息

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

PeekLock 行為

Functions 執行階段會在 PeekLock 模式中收到訊息。 它會在函數成功完成時，於訊息中呼叫 Complete，或是在函數失敗時呼叫 Abandon。 如果函式執行時間較 PeekLock 逾時還長，只要函式正在執行中，就會自動更新鎖定。

maxAutoRenewDuration 在 host.json 中是可設定的，其對應至 OnMessageOptions.MaxAutoRenewDuration。 此設定的預設值為 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 傳送位址。

後續步驟