Azure Functions における Azure Service Bus のバインド

  • [アーティクル]

Azure Functions はトリガーとバインドを使用して Azure Service Bus と統合されます。 Service Bus と統合すると、キューまたはトピック メッセージに応答して送信する関数を構築できます。

アクション Type
Service Bus キューまたはトピック メッセージが作成されたときに関数を実行する トリガー
Azure Service Bus メッセージを送信する 出力バインド

拡張機能のインストール

インストールする拡張機能 NuGet パッケージは、関数アプリで使用している C# モードによって異なります。

関数は分離された C# ワーカー プロセスで実行されます。 詳しくは、「分離されたワーカー プロセスにおける C# Azure Functions の実行のガイド」をご覧ください。

この NuGet パッケージをインストールして、プロジェクトに拡張機能を追加します。

拡張機能の機能性は、拡張機能のバージョンによって異なります。

このバージョンでは、シークレットではなく ID を使用して接続する機能が導入されています。 マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関 するチュートリアルを参照してください。

このバージョンでは、Azure.Messaging.ServiceBus からの型にバインドできます。

NuGet パッケージ バージョン 5.x をインストールすることによって、プロジェクトに拡張機能を追加します。

バンドルのインストール

Service Bus のバインドは、host.json プロジェクト ファイルで指定される拡張機能バンドルの一部です。 このバンドルは、バインドのバージョンを変更するために、またはバンドルがまだインストールされていない場合に変更が必要になることがあります。 詳細については、「拡張機能のバンドル」を参照してください。

このバージョンでは、シークレットではなく ID を使用して接続する機能が導入されています。 マネージド ID を使用して関数アプリを構成するチュートリアルについては、ID ベースの接続を使用した関数アプリの作成に関 するチュートリアルを参照してください。

このバージョンの拡張機能は、host.json ファイルで次のコードを追加するか、または置き換えることによって、プレビュー拡張機能バンドル v3 から追加できます。

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

詳細については、ユーザーの更新に関するページを参照してください。

バインドの種類

.NET でサポートされるバインドの種類は、拡張機能のバージョンと C# 実行モードの両方によって異なります。これは次のいずれかになります。

分離ワーカー プロセス クラス ライブラリは、ランタイムから分離されたプロセスで実行されるコンパイル済みの C# 関数です。

バージョンを選択すると、モードとバージョンのバインドの種類の詳細が表示されます。

分離ワーカー プロセスでは、以下の表に従ってパラメーターの型がサポートされています。

Service Bus トリガー

関数で 1 つのメッセージを処理する場合、Service Bus トリガーは次の型にバインドできます。

Type 説明
string 文字列としてのメッセージ。 メッセージが単純なテキストである場合に使用します。
byte[] メッセージのバイト数。
JSON シリアル化可能な型 イベントに JSON データが含まれている場合、Functions は JSON データを単純な従来の CLR オブジェクト (POCO) 型に逆シリアル化しようとします。
ServiceBusReceivedMessage1 メッセージ オブジェクト。

バインドServiceBusReceivedMessageする場合は、必要に応じて ServiceBusMessageActions1,2 型のパラメーターを含め、メッセージ解決アクションを実行することもできます。

関数でメッセージのバッチを処理するとき、Service Bus トリガーは次の型にバインドできます。

Type 説明
T[] (T は単一メッセージ型の 1 つ) バッチのイベントの配列。 各エントリは 1 つのイベントを表します。

バインドServiceBusReceivedMessage[]する場合は、必要に応じて ServiceBusMessageActions1,2 型のパラメーターを含め、メッセージ解決アクションを実行することもできます。

1 これらの型を使用するには、Microsoft.Azure.Functions.Worker.Extensions.ServiceBus 5.14.1 以降と SDK 型バインドの一般的な依存関係に関する記事を参照する必要があります。

2 使用する場合は、AutoCompleteMessagesトリガー属性falseのプロパティServiceBusMessageActionsを . これにより、関数の呼び出しが成功した後にランタイムがメッセージを完了することを試みなくなります。

Service Bus 出力バインド

関数で 1 つのメッセージを書き込む場合、Service Bus の出力バインドは次の型にバインドできます

Type 説明
string 文字列としてのメッセージ。 メッセージが単純なテキストである場合に使用します。
byte[] メッセージのバイト数。
JSON シリアル化可能な型 メッセージを表すオブジェクト。 Functions は、単純な従来の CLR オブジェクト (POCO) 型を JSON データにシリアル化しようとします。

関数で複数のメッセージを書き込む場合、Service Bus の出力バインドは次の型にバインドできます。

Type 説明
T[] (T は単一メッセージ型の 1 つ) 複数のメッセージを含む配列。 各エントリは 1 つのメッセージを表します。

その他の出力シナリオでは、Azure.Messaging.ServiceBus から型を直接作成して使用します。

host.json 設定

このセクションでは、このバインドで使用できる構成設定について説明します。これは、ランタイムと拡張機能のバージョンによって異なります。

{
    "version": "2.0",
    "extensions": {
        "serviceBus": {
            "clientRetryOptions":{
                "mode": "exponential",
                "tryTimeout": "00:01:00",
                "delay": "00:00:00.80",
                "maxDelay": "00:01:00",
                "maxRetries": 3
            },
            "prefetchCount": 0,
            "transportType": "amqpWebSockets",
            "webProxy": "https://proxyserver:8080",
            "autoCompleteMessages": true,
            "maxAutoLockRenewalDuration": "00:05:00",
            "maxConcurrentCalls": 16,
            "maxConcurrentSessions": 8,
            "maxMessageBatchSize": 1000,
            "minMessageBatchSize": 1,
            "maxBatchWaitTime": "00:00:30",
            "sessionIdleTimeout": "00:01:00",
            "enableCrossEntityTransactions": false
        }
    }
}

この clientRetryOptions の設定は、Service Bus サービスとの対話にのみ適用されます。 関数の実行の再試行には影響しません。 詳細については、「報酬」に関する記事を参照してください。

プロパティ Default 説明
mode Exponential 再試行の遅延を計算するために使用する方法です。 既定の指数モードでは、再試行の度に待機する時間が増加するバックオフ戦略に基づいて、繰り返し試みられます。 Fixed モードでは、固定の間隔で繰り返し試みられ、遅延はそれぞれ一定です。
tryTimeout 00:01:00 試行ごとに操作を待機する最大期間です。
delay 00:00:00.80 再試行の間に適用する遅延またはバックオフ係数です。
maxDelay 00:01:00 許容される再試行の間の最大遅延です。
maxRetries 3 関連する操作が失敗したと判断するまでの再試行の最大回数です。
prefetchCount 0 メッセージの受信者が同時に要求できるメッセージ数を取得または設定します。
transportType amqpTcp Service Bus との通信に使用されるプロトコルと転送。 使用可能なオプション: amqpTcp、amqpWebSockets
webProxy 該当なし Web ソケット経由の Service Bus との通信に使用されるプロキシ。 amqpTcp の転送を指定してプロキシを使用することはできません。
autoCompleteMessages true 関数の正常な実行後にメッセージを自動的に完了するかどうかを決定します。
maxAutoLockRenewalDuration 00:05:00 メッセージ ロックが自動的に更新される最大間隔。 この設定は、一度に 1 つのメッセージを受信する関数にのみ適用されます。
maxConcurrentCalls 16 スケーリングされたインスタンスごとに開始する必要があるコールバックの同時呼び出しの最大数。 既定では、Functions ランタイムは、複数のメッセージを同時に処理します。 この設定は、トリガーの isSessionsEnabled プロパティまたは属性が false に設定されている場合にのみ使用されます。 この設定は、一度に 1 つのメッセージを受信する関数にのみ適用されます。
maxConcurrentSessions 8 スケーリングされたインスタンスごとに同時に処理できるセッションの最大数。 この設定は、トリガーの isSessionsEnabled プロパティまたは属性が true に設定されている場合にのみ使用されます。 この設定は、一度に 1 つのメッセージを受信する関数にのみ適用されます。
maxMessageBatchSize 1000 各関数呼び出しに渡されるメッセージの最大数。 これは、メッセージのバッチを受信する関数にのみ適用されます。
minMessageBatchSize1 1 バッチで必要な最小メッセージ数。 最小値は、関数が複数のイベントを受信する場合にのみ適用され、maxMessageBatchSize より小さくする必要があります。
最小サイズは厳密には保証されません。 部分的なバッチは、maxBatchWaitTime が経過する前に完全なバッチを準備できない場合にディスパッチされます。
maxBatchWaitTime1 00:00:30 関数を呼び出す前に、トリガーがバッチの入力を待機する最大間隔。 待機時間は、minMessageBatchSize が 1 より大きい場合にのみ考慮され、それ以外の場合は無視されます。 待機時間が経過する前に使用可能イベントが minMessageBatchSize 未満の場合、関数は部分的なバッチで呼び出されます。 最長の許容待機時間は、エンティティ メッセージ ロック期間の 50% です。つまり、許可される最大時間は 2 分 30 秒です。 それ以外の場合は、ロック例外が発生する可能性があります。

注: この間隔は、関数が呼び出される正確なタイミングを厳密に保証するものではありません。 タイマーの精度により、わずかな誤差が生じます。
sessionIdleTimeout 該当なし 現在アクティブなセッションでメッセージを受信するまでの最大待機時間。 この時間が経過すると、セッションは閉じられ、関数で別のセッションの処理が試みられます。
enableCrossEntityTransactions false Service Bus 名前空間の複数のエンティティにまたがるトランザクションを有効にするかどうかを指定します。

1minMessageBatchSize と maxBatchWaitTime を使用するには、v5.10.0 以降のバージョンの Microsoft.Azure.WebJobs.Extensions.ServiceBus パッケージが必要です。

次のステップ