Azure Functions の Azure Service Bus トリガー

Service Bus トリガーを使用して、Service Bus キューまたはトピックからのメッセージに応答します。 拡張機能バージョン 3.1.0 以降では、セッションが有効なキューまたはトピックでトリガーを実行できます。

セットアップと構成の詳細については、概要に関するページをご覧ください。

次の例は、メッセージ メタデータを読み取り、Service Bus キュー メッセージをログに記録する 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}");
}

属性と注釈

C# クラス ライブラリでは、以下の属性を使用して Service Bus トリガーを構成します。

  • ServiceBusTriggerAttribute

    属性のコンストラクターは、キューの名前、またはトピックとサブスクリプションを受け取ります。 Azure Functions バージョン 1.x では、接続のアクセス権を指定することもできます。 アクセス権を指定しない場合、既定値は Manage になります。 詳細については、「トリガー - 構成」セクションをご覧ください。

    文字列パラメーターで使用される属性を示す例は次のとおりです。

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue")] string myQueueItem, ILogger log)
    {
        ...
    }
    

    Connection プロパティは定義されていないため、関数は AzureWebJobsServiceBus という名前のアプリ設定を探します。これは Service Bus 接続文字列の既定の名前です。 また、次の例で示すように、Connection プロパティを設定して、使用する Service Bus 接続文字列を含むアプリケーション設定の名前を指定することもできます。

    [FunctionName("ServiceBusQueueTriggerCSharp")]                    
    public static void Run(
        [ServiceBusTrigger("myqueue", Connection = "ServiceBusConnection")] 
        string myQueueItem, ILogger log)
    {
        ...
    }
    

    完全な例については、「トリガー - 例」を参照してください。

  • ServiceBusAccountAttribute

    使用する Service Bus アカウントを指定する別の方法を示します。 コンストラクターは、Service Bus 接続文字列を含むアプリ設定の名前を受け取ります。 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。 次の例では、クラス レベルとメソッド レベルを示します。

    [ServiceBusAccount("ClassLevelServiceBusAppSetting")]
    public static class AzureFunctions
    {
        [ServiceBusAccount("MethodLevelServiceBusAppSetting")]
        [FunctionName("ServiceBusQueueTriggerCSharp")]
        public static void Run(
            [ServiceBusTrigger("myqueue", AccessRights.Manage)] 
            string myQueueItem, ILogger log)
    {
        ...
    }
    

使用する Service Bus アカウントは、次の順序で決定されます。

  • ServiceBusTrigger 属性の Connection プロパティ。
  • ServiceBusTrigger 属性と同じパラメーターに適用された ServiceBusAccount 属性。
  • 関数に適用される ServiceBusAccount 属性。
  • クラスに適用される ServiceBusAccount 属性。
  • "AzureWebJobsServiceBus" アプリの設定。

構成

次の表は、function.json ファイルと ServiceBusTrigger 属性で設定したバインド構成のプロパティを説明しています。

function.json のプロパティ 属性のプロパティ 説明
type 該当なし "serviceBusTrigger" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction 該当なし "in" に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 該当なし 関数コード内のキューまたはトピック メッセージを表す変数の名前。
queueName QueueName 監視するキューの名前。 トピックではなくキューを監視する場合にのみ設定します。
topicName TopicName 監視するトピックの名前。 キューではなくトピックを監視する場合にのみ設定します。
subscriptionName SubscriptionName 監視するサブスクリプションの名前。 キューではなくトピックを監視する場合にのみ設定します。
connection 接続 このバインドに使用する Service Bus 接続文字列を含むアプリ設定の名前です。 アプリ設定の名前が "AzureWebJobs" で始まる場合は、名前の残りの部分のみを指定できます。 たとえば、connection を "MyServiceBus" に設定した場合、Functions ランタイムは "AzureWebJobsMyServiceBus" という名前のアプリ設定を探します。 connection を空のままにした場合、Functions ランタイムは、アプリ設定内の "AzureWebJobsServiceBus" という名前の既定の Service Bus 接続文字列を使用します。

接続文字列は、管理資格情報の取得に関する記事の手順に従って取得します。 接続文字列は、特定のキューまたはトピックに限らず、Service Bus 名前空間のものである必要があります。

バージョン 5.x またはそれ以降の拡張機能を使用している場合は、接続文字列の代わりに、接続を定義する構成セクションへの参照を指定できます。 「接続」を参照してください。
accessRights Access (アクセス) 接続文字列のアクセス権。 使用できる値は managelisten です。 既定値は manage で、connection管理 アクセス許可を持つことを示します。 管理 アクセス許可を持たない接続文字列を使用する場合は、accessRights を "listen" に設定します。 設定しないと、Functions ランタイムが管理権限を必要とする操作の試行に失敗する可能性があります。 最新バージョンの Service Bus SDK が管理の操作をサポートしていないため、Azure Functions バージョン 2.x 以降ではこのプロパティを利用できません。
isSessionsEnabled IsSessionsEnabled セッション対応のキューまたはサブスクリプションに接続する場合は true。 それ以外の場合は false (既定値)。
autoComplete オートコンプリート trueトリガーが処理後に自動的に complete を呼び出す必要があるか、または関数コードで complete を手動で呼び出すかどうか。

false に設定することは、C# でのみサポートされています。

true に設定した場合、関数の実行が正常に完了するとトリガーによって自動的にメッセージが完了され、それ以外の場合はメッセージが破棄されます。

false に設定する場合は、MessageReceiver を呼び出し、メッセージを完了、破棄、または配信不能にする必要があります。 例外がスローされた場合 (かつ MessageReceiver メソッドが呼び出されなかった場合)、ロックは維持されます。 ロックが期限切れになると、メッセージはキューに再登録されて DeliveryCount はインクリメントされ、ロックは自動的に更新されます。

C# 以外の関数では、関数で例外が発生すると、ランタイムによってバックグラウンドで abandonAsync が呼び出されます。 例外が発生しなかった場合は、バックグラウンドで completeAsync が呼び出されます。 このプロパティは Azure Functions 2.x 以降でのみ利用できます。

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。

使用法

キューまたはトピック メッセージに次のパラメーター型を使用できます。

  • string - メッセージがテキストである場合。
  • byte[] - バイナリ データの場合に便利です。
  • カスタム型 - メッセージに JSON が含まれている場合、Azure Functions は JSON データの逆シリアル化を試みます。
  • BrokeredMessage - BrokeredMessage.GetBody<T>() メソッドで逆シリアル化されたメッセージを返します。
  • MessageReceiver - メッセージ コンテナーからのメッセージを受信および確認するために使用します (autoCompletefalse に設定されている場合に必要です)

これらのパラメーター型は Azure Functions バージョン 1.x 用です。2.x 以降では、BrokeredMessage の代わりに Message を使用してください。

その他の型

5.0.0 以降のバージョンの Service Bus 拡張機能を使用するアプリでは、Microsoft.Azure.ServiceBus 名前空間の代わりに Azure.Messaging.ServiceBusServiceBusReceivedMessage 型を使用します。 このバージョンでは、次の型を優先して、レガシ Message 型のサポートがなくなります。

有害メッセージ

Azure Functions では、有害メッセージの処理を制御することも構成することもできません。 Service Bus 自体で、有害なメッセージが処理されます。

PeekLock 動作

Functions ランタイムは、メッセージを PeekLock モードで受信します。 それは、関数が正常に終了した場合はメッセージに対して Complete を呼び出し、関数が失敗した場合は Abandon を呼び出します。 関数が実行されている限り、関数の実行時間が PeekLock タイムアウトよりも長くなると、ロックが自動的に更新されます。

maxAutoRenewDurationhost.json に構成可能です。これは OnMessageOptions.MaxAutoRenewDuration にマップされます。 この設定に許可される最大値は、Service Bus のドキュメントに従って 5 分ですが、Functions の制限時間は既定の 5 分から 10 分に増やすことができます。 Service Bus 関数の場合は、Service Bus の更新制限を超えるので増やしません。

メッセージのメタデータ

Service Bus トリガーには、いくつかのメタデータ プロパティがあります。 これらのプロパティは、他のバインドのバインド式の一部として、またはコードのパラメーターとして使用できます。 これらのプロパティは Message クラスのメンバーです。

プロパティ Type 説明
ContentType string アプリケーション固有のロジックのために送信者と受信者が利用するコンテンツ タイプ識別子。
CorrelationId string 関連付け ID。
DeadLetterSource string 配信不能のソース。
DeliveryCount Int32 配信回数。
EnqueuedTimeUtc DateTime エンキューされた時刻 (UTC)。
ExpiresAtUtc DateTime 有効期限 (UTC)。
Label string アプリケーション固有のラベル。
MessageId string 有効になっている場合に、重複するメッセージを識別するために Service Bus が使用できるユーザー定義の値
MessageReceiver MessageReceiver Service Bus メッセージ受信者。 使用すると、メッセージの破棄、完了、または配信不能とすることができます。
MessageSession MessageSession セッションが有効なキューとトピック専用のメッセージ受信者。
ReplyTo string キュー アドレスへの返信。
SequenceNumber long Service Bus によってメッセージに割り当てられる一意の番号。
To string 送信先アドレス。
UserProperties IDictionary<string, object> 送信者によって設定されたプロパティ。 (バージョン 5.x 以降の拡張機能については、これはサポートされていません。ApplicationProperties を使用してください。)

この記事の前半でこれらのプロパティを使用しているコード例を参照してください。

追加のメッセージ メタデータ

以下のメタデータ プロパティは、5.0.0 以降の拡張機能を使用するアプリでサポートされています。 これらのプロパティは ServiceBusReceivedMessage クラスのメンバーです。

プロパティ Type 説明
ApplicationProperties ApplicationProperties 送信者によって設定されたプロパティ。 UserProperties メタデータ プロパティの代わりにこれを使用します。
Subject string Label メタデータ プロパティの代わりに使用できるアプリケーション固有のラベル。
MessageActions ServiceBusMessageActions ServiceBusReceivedMessage に対して実行できるアクションのセット。 これは MessageReceiver メタデータ プロパティの代わりに使用できます。
SessionActions ServiceBusSessionMessageActions セッションと ServiceBusReceivedMessage に対して実行できるアクションのセット。 これは MessageSession メタデータ プロパティの代わりに使用できます。

次のステップ