Azure Functions の Azure Queue storage トリガーAzure Queue storage trigger for Azure Functions

Queue storage トリガーは、メッセージが Azure Queue storage に追加されると関数を実行します。The queue storage trigger runs a function as messages are added to Azure Queue storage.

エンコードEncoding

Azure Functions で想定されているのは base64 でエンコードされた文字列です。Functions expect a base64 encoded string. (データを base64 でエンコードされた文字列として準備するために) エンコードの種類を調整する場合、それらはすべて呼び出し元のサービスに実装する必要があります。Any adjustments to the encoding type (in order to prepare data as a base64 encoded string) need to be implemented in the calling service.

Example

キュー トリガーを使用して、キューで新しい項目を受け取ったときに関数を開始します。Use the queue trigger to start a function when a new item is received on a queue. キュー メッセージは、関数への入力として提供されます。The queue message is provided as input to the function.

次の例は、キュー項目が処理されるたびに myqueue-items キューをポーリングし、ログを書き込む C# 関数を示しています。The following example shows a C# function that polls the myqueue-items queue and writes a log each time a queue item is processed.

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

属性と注釈Attributes and annotations

C# クラス ライブラリでは、以下の属性を使用してキュー トリガーを構成します。In C# class libraries, use the following attributes to configure a queue trigger:

  • QueueTriggerAttributeQueueTriggerAttribute

    次の例のように、属性のコンストラクターは監視するキューの名前を受け取ります。The attribute's constructor takes the name of the queue to monitor, as shown in the following example:

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

    次の例で示すように、Connection プロパティを設定して、使用するストレージ アカウント接続ストリングを含むアプリ設定を指定できます。You can set the Connection property to specify the app setting that contains the storage account connection string to use, as shown in the following example:

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

    完全な例については、「」を参照してください。For a complete example, see example.

  • StorageAccountAttributeStorageAccountAttribute

    使用するストレージ アカウントを指定する別の方法を提供します。Provides another way to specify the storage account to use. コンストラクターは、ストレージ接続文字列を含むアプリ設定の名前を受け取ります。The constructor takes the name of an app setting that contains a storage connection string. 属性は、パラメーター、メソッド、またはクラス レベルで適用できます。The attribute can be applied at the parameter, method, or class level. 次の例では、クラス レベルとメソッド レベルを示します。The following example shows class level and method level:

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

使用するストレージ アカウントは、次の順序で決定されます。The storage account to use is determined in the following order:

  • QueueTrigger 属性の Connection プロパティ。The QueueTrigger attribute's Connection property.
  • QueueTrigger 属性と同じパラメーターに適用された StorageAccount 属性。The StorageAccount attribute applied to the same parameter as the QueueTrigger attribute.
  • 関数に適用される StorageAccount 属性。The StorageAccount attribute applied to the function.
  • クラスに適用される StorageAccount 属性。The StorageAccount attribute applied to the class.
  • "AzureWebJobsStorage" アプリ設定。The "AzureWebJobsStorage" app setting.

構成Configuration

次の表は、function.json ファイルと QueueTrigger 属性で設定したバインド構成のプロパティを説明しています。The following table explains the binding configuration properties that you set in the function.json file and the QueueTrigger attribute.

function.json のプロパティfunction.json property 属性のプロパティAttribute property 説明Description
typetype 該当なしn/a queueTrigger に設定する必要があります。Must be set to queueTrigger. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
directiondirection 該当なしn/a function.json ファイルの場合のみ。In the function.json file only. in に設定する必要があります。Must be set to in. このプロパティは、Azure Portal でトリガーを作成するときに自動で設定されます。This property is set automatically when you create the trigger in the Azure portal.
namename 該当なしn/a 関数コードでキュー項目ペイロードを含む変数の名前。The name of the variable that contains the queue item payload in the function code.
queueNamequeueName QueueNameQueueName ポーリングするキューの名前。The name of the queue to poll.
connectionconnection ConnectionConnection このバインドに使用するストレージ接続文字列を含むアプリ設定の名前です。The name of an app setting that contains the Storage connection string to use for this binding. アプリ設定の名前が "AzureWebJobs" で始まる場合は、ここで名前の残りの部分のみを指定できます。If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. たとえば、connection を "MyStorage" に設定した場合、Functions ランタイムは "MyStorage" という名前のアプリ設定を探します。For example, if you set connection to "MyStorage", the Functions runtime looks for an app setting that is named "MyStorage." connection を空のままにした場合、Functions ランタイムは、アプリ設定内の AzureWebJobsStorage という名前の既定のストレージ接続文字列を使用します。If you leave connection empty, the Functions runtime uses the default Storage connection string in the app setting that is named AzureWebJobsStorage.

ローカルで開発している場合、アプリ設定は local.settings.json ファイルに保存されます。When you're developing locally, app settings go into the local.settings.json file.

使用法Usage

string paramName のようなメソッド パラメーターを使用してメッセージ データにアクセスします。Access the message data by using a method parameter such as string paramName. 次の型のいずれにでもバインドできます。You can bind to any of the following types:

  • オブジェクト - Functions ランタイムは、JSON ペイロードを、コードで定義されている任意のクラスのインスタンスに逆シリアル化します。Object - The Functions runtime deserializes a JSON payload into an instance of an arbitrary class defined in your code.
  • string
  • byte[]
  • CloudQueueMessageCloudQueueMessage

CloudQueueMessage にバインドしようとしてエラー メッセージが表示された場合は、適切な Storage SDK バージョンへの参照があることをご確認ください。If you try to bind to CloudQueueMessage and get an error message, make sure that you have a reference to the correct Storage SDK version.

メッセージのメタデータMessage metadata

キュー トリガーは、いくつかのメタデータ プロパティを提供します。The queue trigger provides several metadata properties. これらのプロパティは、他のバインドのバインド式の一部として、またはコードのパラメーターとして使用できます。These properties can be used as part of binding expressions in other bindings or as parameters in your code. これらのプロパティは、CloudQueueMessage クラスのメンバーです。The properties are members of the CloudQueueMessage class.

プロパティProperty 種類Type 説明Description
QueueTrigger string キュー ペイロード (有効な文字列の場合)。Queue payload (if a valid string). キュー メッセージ ペイロードが文字列の場合、QueueTrigger は、function.jsonname プロパティで指定された変数と同じ値になります。If the queue message payload is a string, QueueTrigger has the same value as the variable named by the name property in function.json.
DequeueCount int このメッセージがデキューされた回数。The number of times this message has been dequeued.
ExpirationTime DateTimeOffset メッセージが期限切れになる時刻。The time that the message expires.
Id string キュー メッセージ ID。Queue message ID.
InsertionTime DateTimeOffset メッセージがキューに追加された時刻。The time that the message was added to the queue.
NextVisibleTime DateTimeOffset メッセージが次に表示される時刻。The time that the message will next be visible.
PopReceipt string メッセージのポップ受信。The message's pop receipt.

有害メッセージPoison messages

キュー トリガー関数が失敗すると、Azure Functions は、その関数を特定のキュー メッセージに対して (最初の試行を含め) 最大 5 回再試行します。When a queue trigger function fails, Azure Functions retries the function up to five times for a given queue message, including the first try. 試行が 5 回とも失敗した場合、Functions ランタイム は、 <originalqueuename>-poison という名前のキューにメッセージを追加します。If all five attempts fail, the functions runtime adds a message to a queue named <originalqueuename>-poison. メッセージのログを取得するか、手動での対処が必要であるという通知を送信することにより有害キューからのメッセージを処理する関数が記述できます。You can write a function to process messages from the poison queue by logging them or sending a notification that manual attention is needed.

有害メッセージを手動で処理するには、キュー メッセージの dequeueCount を確認します。To handle poison messages manually, check the dequeueCount of the queue message.

ポーリング アルゴリズムPolling algorithm

キュー トリガーは、アイドル状態のキューのポーリングがストレージ トランザクション コストに与える影響を軽減するために、ランダムな指数バックオフ アルゴリズムを実装します。The queue trigger implements a random exponential back-off algorithm to reduce the effect of idle-queue polling on storage transaction costs.

アルゴリズムでは次のロジックが使用されます。The algorithm uses the following logic:

  • メッセージが見つかると、ランタイムは 2 秒間待機してから、別のメッセージを確認しますWhen a message is found, the runtime waits two seconds and then checks for another message
  • メッセージが見つからない場合は、約 4 秒間待機してから再試行します。When no message is found, it waits about four seconds before trying again.
  • 再試行後もキュー メッセージが取得できなかった場合、待ち時間が最大になるまで再試行が続けられます。既定の最大待ち時間は 1 分間です。After subsequent failed attempts to get a queue message, the wait time continues to increase until it reaches the maximum wait time, which defaults to one minute.
  • 最大待ち時間は、host.json ファイル内の maxPollingInterval プロパティで構成できます。The maximum wait time is configurable via the maxPollingInterval property in the host.json file.

ローカル開発の場合、最大ポーリング間隔は既定で 2 秒に設定されます。For local development the maximum polling interval defaults to two seconds.

課金に関しては、ランタイムによるポーリングに費やされた時間は "無料" であり、お使いのアカウントに対してカウントされません。In regard to billing, time spent polling by the runtime is "free" and not counted against your account.

コンカレンシーConcurrency

待機中のキュー メッセージが複数存在する場合、キュー トリガーはメッセージのバッチを取得し、関数インスタンスを同時に呼び出してそれらを処理します。When there are multiple queue messages waiting, the queue trigger retrieves a batch of messages and invokes function instances concurrently to process them. 既定では、このバッチ サイズは 16 です。By default, the batch size is 16. 処理されている数が 8 まで減少すると、このランタイムは別のバッチを取得し、それらのメッセージの処理を開始します。When the number being processed gets down to 8, the runtime gets another batch and starts processing those messages. そのため、1 つの仮想マシン (VM) 上で 1 関数あたりに処理されている同時実行メッセージの最大数は 24 です。So the maximum number of concurrent messages being processed per function on one virtual machine (VM) is 24. この制限は、各 VM 上のキューによってトリガーされる各関数に個別に適用されます。This limit applies separately to each queue-triggered function on each VM. 関数アプリが複数の VM にスケールアウトした場合、各 VM はトリガーを待機し、関数を実行しようとします。If your function app scales out to multiple VMs, each VM will wait for triggers and attempt to run functions. たとえば、関数アプリが 3 つの VM にスケールアウトした場合、キューによってトリガーされる 1 つの関数の同時実行インスタンスの既定の最大数は 72 です。For example, if a function app scales out to 3 VMs, the default maximum number of concurrent instances of one queue-triggered function is 72.

新しいバッチを取得するためのバッチ サイズとしきい値は、host.json ファイルで構成できます。The batch size and the threshold for getting a new batch are configurable in the host.json file. 関数アプリ内のキューによってトリガーされる関数の並列実行を最小限に抑えたい場合は、このバッチ サイズを 1 に設定できます。If you want to minimize parallel execution for queue-triggered functions in a function app, you can set the batch size to 1. この設定によってコンカレンシーが解消されるのは、関数アプリが 1 つの仮想マシン (VM) 上で実行される場合に限ります。This setting eliminates concurrency only so long as your function app runs on a single virtual machine (VM).

キュー トリガーは、関数がキュー メッセージを複数回処理することを自動的に防止します。関数をべき等として記述する必要はありません。The queue trigger automatically prevents a function from processing a queue message multiple times; functions do not have to be written to be idempotent.

host.json プロパティhost.json properties

host.json ファイルには、キュー トリガーの動作を制御する設定が含まれています。The host.json file contains settings that control queue trigger behavior. 使用可能な設定の詳細については、「host.json 設定」を参照してください。See the host.json settings section for details regarding available settings.

次のステップNext steps