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 への接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。
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 ファイルに保存されます。

接続

connection プロパティは、アプリを Service Bus に接続する方法を指定する環境構成への参照です。 次のものが指定されている場合があります。

  • 接続文字列を含むアプリケーション設定の名前
  • まとめて ID ベースの接続を定義する、複数のアプリケーション設定の共有プレフィックスの名前。

構成された値が、1 つの設定に完全一致し、その他の設定のプレフィックスとも一致する場合、完全一致が使用されます。

接続文字列

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

この接続文字列は、バインディング構成の connection プロパティで指定した値と一致する名前のアプリケーション設定に格納する必要があります。

アプリ設定の名前が "AzureWebJobs" で始まる場合は、名前の残りの部分のみを指定できます。 たとえば、connection を "MyServiceBus" に設定した場合、Functions ランタイムは "AzureWebJobsMyServiceBus" という名前のアプリ設定を探します。 connection を空のままにした場合、Functions ランタイムは、アプリ設定内の "AzureWebJobsServiceBus" という名前の既定の Service Bus 接続文字列を使用します。

ID ベースの接続

バージョン 5.x 以上の拡張機能を使用する場合は、シークレットを含む接続文字列を使う代わりに、アプリで Azure Active Directory ID を使用することができます。 これを行うには、トリガーおよびバインディング構成の connection プロパティにマップされる共通のプレフィックスに設定を定義します。

このモードでは、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
完全修飾名前空間 <CONNECTION_NAME_PREFIX>__fullyQualifiedNamespace Service Bus の完全修飾名前空間。 <service_bus_namespace>.servicebus.windows.net

接続をカスタマイズするために、追加のプロパティを設定できます。 「ID ベース接続に共通のプロパティ」を参照してください。

Azure Functions サービスでホストされている場合、ID ベースの接続では、マネージド ID が使用されます。 ユーザー割り当て ID を credential および clientID プロパティで指定できますが、システム割り当て ID が既定で使用されます。 ローカル開発などの他のコンテキストで実行する場合は、代わりに開発者 ID が使用されますが、カスタマイズすることもできます。 ID ベースの接続によるローカル開発に関するページをご覧ください。

ID にアクセス許可を付与する

使用されている ID が何であれ、目的のアクションを実行するためのアクセス許可が必要です。 これらのアクセス許可を提供する組み込みロールまたはカスタム ロールを使用して、Azure RBAC でロールを割り当てる必要があります。

重要

すべてのコンテキストに必要ではない一部のアクセス許可がターゲット サービスによって公開される場合があります。 可能であれば、最小限の特権の原則 に従い、必要な特権だけを ID に付与します。 たとえば、アプリがデータ ソースからの読み取りのみを行う必要がある場合は、読み取りアクセス許可のみを持つロールを使用します。 サービスへの書き込みも可能なロールを割り当てることは、読み取り操作に対するアクセス許可が過剰になるため、不適切です。 同様に、ロールの割り当てが、読み取る必要のあるリソースだけに限定されていることを確認する必要があります。

実行時にトピックとキューへのアクセスを提供するロールの割り当てを作成する必要があります。 ロール割り当てのスコープは、特定のキューまたはトピックに制限されない、Service Bus 名前空間に対するものである必要があります。 所有者のような管理ロールでは十分ではありません。 次の表は、通常の操作で Service Bus の拡張機能を使用するときに推奨される組み込みロールを示しています。 アプリケーションでは、記述したコードに基づいて追加のアクセス許可が必要になる場合があります。

[バインドの種類] 組み込みロールの例
トリガー Azure Service Bus データ受信者Azure Service Bus データ所有者
出力バインド Azure Service Bus データ送信者

使用法

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

  • 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 メタデータ プロパティの代わりに使用できます。

次のステップ