Azure Functions の Azure Queue storage トリガー

Queue storage トリガーは、メッセージが Azure Queue storage に追加されると関数を実行します。

エンコード

Azure Functions で想定されているのは base64 でエンコードされた文字列です。 (データを base64 でエンコードされた文字列として準備するために) エンコードの種類を調整する場合、それらはすべて呼び出し元のサービスに実装する必要があります。

キュー トリガーを使用して、キューで新しい項目を受け取ったときに関数を開始します。 キュー メッセージは、関数への入力として提供されます。

次の例は、キュー項目が処理されるたびに myqueue-items キューをポーリングし、ログを書き込む C# 関数を示しています。

public static class QueueFunctions
{
    [FunctionName("QueueTrigger")]
    public static void QueueTrigger(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        log.LogInformation($"C# function processed: {myQueueItem}");
    }
}

属性と注釈

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

  • QueueTriggerAttribute

    次の例のように、属性のコンストラクターは監視するキューの名前を受け取ります。

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items")] string myQueueItem, 
        ILogger log)
    {
        ...
    }
    

    次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウント接続ストリングを含むアプリ設定を指定できます。

    [FunctionName("QueueTrigger")]
    public static void Run(
        [QueueTrigger("myqueue-items", Connection = "StorageConnectionAppSetting")] string myQueueItem, 
        ILogger log)
    {
        ....
    }
    

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

  • StorageAccountAttribute

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

    [StorageAccount("ClassLevelStorageAppSetting")]
    public static class AzureFunctions
    {
        [FunctionName("QueueTrigger")]
        [StorageAccount("FunctionLevelStorageAppSetting")]
        public static void Run( //...
    {
        ...
    }
    

使用するストレージ アカウントは、次の順序で決定されます。

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

構成

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

function.json のプロパティ 属性のプロパティ 説明
type 該当なし queueTrigger に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction 該当なし function.json ファイルの場合のみ。 in に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 該当なし 関数コードでキュー項目ペイロードを含む変数の名前。
queueName QueueName ポーリングするキューの名前。
connection 接続 このバインドに使用するストレージ接続文字列を含むアプリ設定の名前です。 アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。

たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "MyStorage" という名前のアプリ設定を探します。 connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。

接続文字列の代わりにバージョン 5.x またはそれ以降の拡張機能を使用している場合は、接続を定義する構成セクションへの参照を指定できます。 「接続」を参照してください。

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

使用法

Default

string paramName のようなメソッド パラメーターを使用してメッセージ データにアクセスします。 次の型のいずれにでもバインドできます。

  • オブジェクト - Functions ランタイムは、JSON ペイロードを、コードで定義されている任意のクラスのインスタンスに逆シリアル化します。
  • string
  • byte[]
  • CloudQueueMessage

CloudQueueMessage にバインドしようとしてエラー メッセージが表示された場合は、適切な Storage SDK バージョンへの参照があることをご確認ください。

その他の型

Storage 拡張機能の 5.0.0 またはそれ以降のバージョンを使用するアプリでは、Azure SDK for .NET の型を使用することもできます。 このバージョンでは、次の型を優先して、レガシ CloudQueueMessage 型のサポートがなくなります。

これらの型の使用例については、拡張機能の GitHub リポジトリに関するページを参照してください。

メッセージのメタデータ

キュー トリガーは、いくつかのメタデータ プロパティを提供します。 これらのプロパティは、他のバインドのバインド式の一部として、またはコードのパラメーターとして使用できます。 これらのプロパティは、CloudQueueMessage クラスのメンバーです。

プロパティ Type 説明
QueueTrigger string キュー ペイロード (有効な文字列の場合)。 キュー メッセージ ペイロードが文字列の場合、QueueTrigger は、function.jsonname プロパティで指定された変数と同じ値になります。
DequeueCount int このメッセージがデキューされた回数。
ExpirationTime DateTimeOffset メッセージが期限切れになる時刻。
Id string キュー メッセージ ID。
InsertionTime DateTimeOffset メッセージがキューに追加された時刻。
NextVisibleTime DateTimeOffset メッセージが次に表示される時刻。
PopReceipt string メッセージのポップ受信。

有害メッセージ

キュー トリガー関数が失敗すると、Azure Functions は、その関数を特定のキュー メッセージに対して (最初の試行を含め) 最大 5 回再試行します。 5 回の試行すべてで失敗した場合、Functions ランタイムは、 <originalqueuename>-poison という名前のキューにメッセージを追加します。 メッセージのログを取得するか、手動での対処が必要であるという通知を送信することにより有害キューからのメッセージを処理する関数が記述できます。

有害メッセージを手動で処理するには、キュー メッセージの dequeueCount を確認します。

ピーク ロック

ピーク ロック パターンは、キュー トリガーに対して自動的に行われます。 デキューされたメッセージは、非表示とマークされ、Storage サービスが管理するタイムアウトと関連付けられます。

その関数が開始されると、次の条件下でメッセージの処理が開始されます。

  • 関数が成功すると、関数の実行が完了し、メッセージが削除されます。
  • 関数が失敗すると、メッセージの可視性がリセットされます。 リセットされると、関数が次に新しいメッセージを要求するときにメッセージが再処理されます。
  • クラッシュが原因で関数が完了しない場合は、メッセージの可視性の有効期限が切れ、メッセージはキューに再表示されます。

可視性のメカニズムは、Functions ランタイムではなく、Storage サービスによりすべて処理されます。

ポーリング アルゴリズム

キュー トリガーは、アイドル状態のキューのポーリングがストレージ トランザクション コストに与える影響を軽減するために、ランダムな指数バックオフ アルゴリズムを実装します。

アルゴリズムでは次のロジックが使用されます。

  • メッセージが見つかると、ランタイムにより 100 ミリ秒間待機してから、別のメッセージが確認されます
  • メッセージが見つからない場合は、約 200 ミリ秒間待機してからもう一度お試しください。
  • 再試行後もキュー メッセージが取得できなかった場合、待ち時間が最大になるまで再試行が続けられます。既定の最大待ち時間は 1 分間です。
  • 最大待ち時間は、host.json ファイル内の maxPollingInterval プロパティで構成できます。

ローカル開発の場合、最大ポーリング間隔は既定で 2 秒に設定されます。

注意

従量課金プランで関数アプリをホストする場合の課金については、ランタイムがポーリングに費やした時間は課金されません。

コンカレンシー

待機中のキュー メッセージが複数存在する場合、キュー トリガーはメッセージのバッチを取得し、関数インスタンスを同時に呼び出してそれらを処理します。 既定では、このバッチ サイズは 16 です。 処理されている数が 8 まで減少すると、このランタイムは別のバッチを取得し、それらのメッセージの処理を開始します。 そのため、1 つの仮想マシン (VM) 上で 1 関数あたりに処理されている同時実行メッセージの最大数は 24 です。 この制限は、各 VM 上のキューによってトリガーされる各関数に個別に適用されます。 関数アプリが複数の VM にスケールアウトした場合、各 VM はトリガーを待機し、関数を実行しようとします。 たとえば、関数アプリが 3 つの VM にスケールアウトした場合、キューによってトリガーされる 1 つの関数の同時実行インスタンスの既定の最大数は 72 です。

新しいバッチを取得するためのバッチ サイズとしきい値は、host.json ファイルで構成できます。 関数アプリ内のキューによってトリガーされる関数の並列実行を最小限に抑えたい場合は、このバッチ サイズを 1 に設定できます。 この設定によってコンカレンシーが解消されるのは、関数アプリが 1 つの仮想マシン (VM) 上で実行される場合に限ります。

キュー トリガーは、関数がキュー メッセージを複数回同時に処理することを自動的に防止します。

host.json プロパティ

host.json ファイルには、キュー トリガーの動作を制御する設定が含まれています。 使用可能な設定の詳細については、「host.json 設定」を参照してください。

次のステップ