次の方法で共有

Azure Functions の Azure Queue storage トリガー

  • [アーティクル]

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

従量課金プランと Premium プランに対する Azure Queue Storage のスケーリングの決定は、ターゲット ベースのスケーリングによって行われます。 詳しくは、「ターゲット ベースのスケーリング」をご覧ください。

重要

この記事では、タブを使用して、Node.js プログラミング モデルの複数のバージョンに対応しています。 v4 モデルは一般提供されており、JavaScript と TypeScript の開発者にとって、より柔軟で直感的なエクスペリエンスが得られるように設計されています。 v4 モデルの動作の詳細については、Azure Functions Node.js 開発者ガイドを参照してください。 v3 と v4 の違いの詳細については、移行ガイドを参照してください。

Azure Functions では、Python の 2 つのプログラミング モデルがサポートされています。 バインドを定義する方法は、選択したプログラミング モデルによって異なります。

Python v2 プログラミング モデルでは、Python 関数コードでデコレーターを使用してバインドを直接定義できます。 詳細については、「Python 開発者ガイド」を参照してください。

この記事は、両方のプログラミング モデルをサポートしています。

例

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

A C# 関数は、次の C# モードのいずれかを使用して作成できます。

  • 分離されたワーカー モデル: ランタイムから分離されたワーカー プロセスで実行されるコンパイル済みの C# 関数。 分離ワーカー プロセスは、LTS および 非 LTS バージョンの .NET および .NET Framework で実行されている C# 関数をサポートするために必要です。 分離ワーカー プロセス関数の拡張機能では、Microsoft.Azure.Functions.Worker.Extensions.* 名前空間が使用されます。
  • インプロセス モデル: Functions ランタイムと同じプロセスで実行されるコンパイル済みの C# 関数。 このモデルの一部では、主に C# ポータルの編集のためにサポートされている C# スクリプトを使用して Functions を実行できます。 インプロセス関数の拡張機能では、Microsoft.Azure.WebJobs.Extensions.* 名前空間が使用されます。

重要

インプロセス モデルのサポートは 2026 年 11 月 10 日に終了します。 完全なサポートのために、分離ワーカー モデルにアプリを移行することを強くお勧めします。

次の例は、キュー項目が処理されるたびに input-queue キューをポーリングし、いくつかのメッセージを出力キューに書き込む C# 関数を示しています。

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)
{
    // Use a string array to return more than one message.
    string[] messages = {
        $"Album name = {myQueueItem.Name}",
        $"Album songs = {myQueueItem.Songs}"};

    _logger.LogInformation("{msg1},{msg2}", messages[0], messages[1]);

    // Queue Output messages
    return messages;
}

次の Java の例は、キュー myqueuename に格納されるトリガーされたメッセージを記録するストレージ キュー トリガー関数を示しています。

@FunctionName("queueprocessor")
public void run(
    @QueueTrigger(name = "msg",
                queueName = "myqueuename",
                connection = "myconnvarname") String message,
    final ExecutionContext context
) {
    context.getLogger().info(message);
}

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

import { app, InvocationContext } from '@azure/functions';

export async function storageQueueTrigger1(queueItem: unknown, context: InvocationContext): Promise<void> {
    context.log('Storage queue function processed work item:', queueItem);
    context.log('expirationTime =', context.triggerMetadata.expirationTime);
    context.log('insertionTime =', context.triggerMetadata.insertionTime);
    context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
    context.log('id =', context.triggerMetadata.id);
    context.log('popReceipt =', context.triggerMetadata.popReceipt);
    context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
}

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: storageQueueTrigger1,
});

使用セクションでは queueItem について説明しています。 ここに表示されているその他すべての変数については、「メッセージのメタデータ」セクションを参照してください。

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

const { app } = require('@azure/functions');

app.storageQueue('storageQueueTrigger1', {
    queueName: 'myqueue-items',
    connection: 'MyStorageConnectionAppSetting',
    handler: (queueItem, context) => {
        context.log('Storage queue function processed work item:', queueItem);
        context.log('expirationTime =', context.triggerMetadata.expirationTime);
        context.log('insertionTime =', context.triggerMetadata.insertionTime);
        context.log('nextVisibleTime =', context.triggerMetadata.nextVisibleTime);
        context.log('id =', context.triggerMetadata.id);
        context.log('popReceipt =', context.triggerMetadata.popReceipt);
        context.log('dequeueCount =', context.triggerMetadata.dequeueCount);
    },
});

使用セクションでは queueItem について説明しています。 ここに表示されているその他すべての変数については、「メッセージのメタデータ」セクションを参照してください。

次の例では、トリガーを使用してキュー メッセージを読み取って関数に渡す方法を示します。

ストレージ キュー トリガーは function.json ファイルで定義され、そこで type は queueTrigger に設定されます。

{
  "bindings": [
    {
      "name": "QueueItem",
      "type": "queueTrigger",
      "direction": "in",
      "queueName": "messages",
      "connection": "MyStorageConnectionAppSetting"
    }
  ]
}

Run.ps1 ファイルのコードによってパラメーターが $QueueItem として宣言され、関数でキュー メッセージを読み取ることができるようになります。

# Input bindings are passed in via param block.
param([string] $QueueItem, $TriggerMetadata)

# Write out the queue message and metadata to the information log.
Write-Host "PowerShell queue trigger function processed work item: $QueueItem"
Write-Host "Queue item expiration time: $($TriggerMetadata.ExpirationTime)"
Write-Host "Queue item insertion time: $($TriggerMetadata.InsertionTime)"
Write-Host "Queue item next visible time: $($TriggerMetadata.NextVisibleTime)"
Write-Host "ID: $($TriggerMetadata.Id)"
Write-Host "Pop receipt: $($TriggerMetadata.PopReceipt)"
Write-Host "Dequeue count: $($TriggerMetadata.DequeueCount)"

次の例では、トリガーを使用してキュー メッセージを読み取って関数に渡す方法を示します。 この例は、v1 と v2 のどちらの Python プログラミング モデルを使用するかによって異なります。

import logging
import azure.functions as func

app = func.FunctionApp()

@app.function_name(name="QueueFunc")
@app.queue_trigger(arg_name="msg", queue_name="inputqueue",
                   connection="storageAccountConnectionString")  # Queue trigger
@app.queue_output(arg_name="outputQueueItem", queue_name="outqueue",
                 connection="storageAccountConnectionString")  # Queue output binding
def test_function(msg: func.QueueMessage,
                  outputQueueItem: func.Out[str]) -> None:
    logging.info('Python queue trigger function processed a queue item: %s',
                 msg.get_body().decode('utf-8'))
    outputQueueItem.set('hello')

属性

インプロセスと分離ワーカー プロセスの C# ライブラリはどちらも、QueueTriggerAttribute 属性を使用して関数を定義します。 C# スクリプトでは、C# スクリプト ガイドで説明されているように、代わりに function.json 構成ファイルを使用します。

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

[Function(nameof(QueueFunction))]
[QueueOutput("output-queue")]
public string[] Run([QueueTrigger("input-queue")] Album myQueueItem, FunctionContext context)

この例では、属性自体に接続文字列設定を設定する方法も示しています。

注釈

QueueTrigger 注釈を使用すると、関数をトリガーするキューにアクセスできます。 次の例では、message パラメーターを使用して、キュー メッセージを関数で使用できるようにします。

package com.function;
import com.microsoft.azure.functions.annotation.*;
import java.util.Queue;
import com.microsoft.azure.functions.*;

public class QueueTriggerDemo {
    @FunctionName("QueueTriggerDemo")
    public void run(
        @QueueTrigger(name = "message", queueName = "messages", connection = "MyStorageConnectionAppSetting") String message,
        final ExecutionContext context
    ) {
        context.getLogger().info("Queue message: " + message);
    }
}
プロパティ 説明
name 関数シグネチャのパラメーター名を宣言します。 関数がトリガーされると、このパラメーターの値にはキュー メッセージの内容が含められます。
queueName ストレージ アカウントのキュー名を宣言します。
connection ストレージ アカウントの接続文字列を示します。

デコレーター

Python v2 プログラミング モデルにのみ適用されます。

デコレーターを使用して定義された Python v2 関数の場合、queue_trigger デコレーターの次のプロパティによって Queue Storage トリガーが定義されます。

プロパティ 説明
arg_name 関数シグネチャのパラメーター名を宣言します。 関数がトリガーされると、このパラメーターの値にはキュー メッセージの内容が含められます。
queue_name ストレージ アカウントのキュー名を宣言します。
connection ストレージ アカウントの接続文字列を示します。

function.json を使用して定義された Python 関数については、「構成」セクションを参照してください。

構成

"Python v1 プログラミング モデルにのみ適用されます。"

次の表では、app.storageQueue() メソッドに渡される options オブジェクトに対して設定できるプロパティについて説明します。

プロパティ 説明
queueName ポーリングするキューの名前。
connection Azure キューへの接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

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

function.json のプロパティ 説明
type queueTrigger に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
direction function.json ファイルの場合のみ。 in に設定する必要があります。 このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。
name 関数コードでキュー項目ペイロードを含む変数の名前。
queueName ポーリングするキューの名前。
connection Azure キューへの接続方法を指定するアプリ設定または設定コレクションの名前。 「接続」を参照してください。

完全な例については、セクションの例を参照してください。

ローカルで開発する場合は、Values コレクション内の local.settings.json ファイルにアプリケーション設定を追加します。

使用法

Note

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

Queue トリガーの使用方法は、拡張機能パッケージのバージョンと、関数アプリで使用される C# モダリティによって異なります。これは、次のいずれかのモードになります。

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

バージョンを選択すると、モードとバージョンの使用状況の詳細が表示されます。

キュー トリガーは、次の型にバインドできます。

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

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

QueueTrigger 注釈を使用すると、関数をトリガーしたキュー メッセージにアクセスできます。

関数の最初の引数としてキュー項目にアクセスします。 ペイロードが JSON の場合、値はオブジェクトに逆シリアル化されます。

name ファイルのバインドの name パラメーターで指定された名前と一致する文字列パラメーターを使用して、キュー メッセージにアクセスします。

QueueMessage として型指定されたパラメーターを使用して、キュー メッセージにアクセスします。

メタデータ

キュー トリガーは、いくつかのメタデータ プロパティを提供します。 これらのプロパティは、メッセージ メタデータへのこのアクセスを提供する言語ワーカーに対して、他のバインディングのバインド式の一部として、またはコード内のパラメーターとして使用できます。

メッセージ メタデータ プロパティは、 CloudQueueMessage クラスのメンバーです。

メッセージ メタデータ プロパティには、 context.triggerMetadataからアクセスできます。

メッセージ メタデータ プロパティには、渡された $TriggerMetadata パラメーターからアクセスできます。

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

渡されたバインディング パラメーター (前の例のmsg) から、次のメッセージ メタデータ プロパティにアクセスできます。

プロパティ 説明
body 文字列としてのキュー ペイロード。
dequeue_count このメッセージがデキューされた回数。
expiration_time メッセージが期限切れになる時刻。
id キュー メッセージ ID。
insertion_time メッセージがキューに追加された時刻。
time_next_visible メッセージが次に表示される時刻。
pop_receipt メッセージのポップ受信。

接続

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

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

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

接続文字列

接続文字列を取得するには、「ストレージ アカウント アクセス キーを管理する」の手順に従います。

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

アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。 たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "AzureWebJobsMyStorage" という名前のアプリ設定を探します。connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。

ID ベースの接続

バージョン 5.x 以上の拡張機能を使用している場合 (non-.NET 言語スタックの場合は bundle 3.x 以上)、シークレットで接続文字列を使用する代わりに、アプリで Microsoft Entra ID を使用できます。 ID を使用するには、トリガーとバインドの構成の connection プロパティにマップされる共通のプレフィックスに設定を定義します。

connection を "AzureWebJobsStorage" に設定する場合は、「ID を使用してホスト ストレージに接続する」を参照してください。 その他のすべての接続では、拡張機能に次のプロパティが必要です。

プロパティ 環境変数テンプレート 説明 値の例
Queue サービス URI <CONNECTION_NAME_PREFIX>__queueServiceUri1 接続している Queue サービスのデータ プレーン URI。HTTPS スキームを使用します。 https://<storage_account_name>.queue.core.windows.net

1 <CONNECTION_NAME_PREFIX>__serviceUri はエイリアスとして使用できます。 両方の形式が指定された場合、queueServiceUri の形式が使用されます。 全体の接続構成が BLOB、キュー、テーブル間で使用される場合、serviceUri 形式は指定できません。

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

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

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

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

重要

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

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

[バインドの種類] 組み込みロールの例
トリガー ストレージ キュー データ閲覧者、ストレージ キュー データのメッセージ プロセッサ
出力バインド ストレージ キュー データ共同作成者、ストレージ キュー データのメッセージ送信者

有害メッセージ

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

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

ピーク ロック

ピーク ロック パターンは、ストレージ サービスによって提供される可視性メカニズムを使用して、キュー トリガーに対して自動的に行われます。 メッセージはトリガーされた関数によってデキューされるため、非表示としてマークされます。 キューによってトリガーされる関数を実行すると、キュー内のメッセージに対して次のいずれかの結果を得ることができます。

  • 関数の実行が正常に完了し、メッセージがキューから削除されます。
  • 関数の実行が失敗し、Functions ホストは、host.json ファイル内の visibilityTimeout 設定に基づいてメッセージの可視性を更新。 既定の可視性タイムアウトは 0 です。これは、メッセージが再処理のためにキューにすぐに再び表示されることを意味します。 visibilityTimeout設定を使用して、処理に失敗したメッセージの再処理を遅らせることができます。 このタイムアウト設定は、関数アプリ内のすべてのキューによってトリガーされる関数に適用されます。
  • Functions ホストは、関数の実行中にクラッシュします。 この一般的でないイベントが発生した場合、ホストは処理中のメッセージに visibilityTimeout を適用できません。 代わりに、メッセージは、ストレージ サービスによって設定された既定の 10 分のタイムアウトのままにされます。 10 分後、メッセージは再処理のためにキューに再び表示されます。 このサービス定義の既定のタイムアウトは変更できません。

ポーリング アルゴリズム

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

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

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

ローカル開発時の最大ポーリング間隔は、既定で 2 秒です。

Note

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

コンカレンシー

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

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

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

host.json プロパティ

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

次のステップ