queue.yaml リファレンス

リージョン ID

REGION_ID は、アプリの作成時に選択したリージョンに基づいて Google が割り当てる省略形のコードです。一部のリージョン ID は、一般的に使用されている国や州のコードと類似しているように見える場合がありますが、このコードは国または州に対応するものではありません。2020 年 2 月以降に作成されたアプリの場合、REGION_ID.r は App Engine の URL に含まれています。この日付より前に作成されたアプリの場合、URL のリージョン ID は省略可能です。

詳しくは、リージョン ID をご覧ください。

queue.yaml 構成ファイルは、アプリが使用するほぼすべてのタスクキュー（push または pull）の作成と構成に使用されます。すべての App Engine アプリには、default という名前の自動的に事前構成された push キューがあります。default キューを自分で作成する必要はありませんが、他のキューを追加できます。または、queue.yaml ファイルを使用して default キューの構成を変更することもできます。

Java アプリの場合、このファイルはソースコード ディレクトリの任意の場所に置くことができます。

push キューを構成するには、Cloud Tasks の queue.yaml またはキュー管理メソッドのいずれかを使用しますが、両方を同時に使用することはできません。queue.yaml アップロード メソッドとキュー管理メソッドを混在させると、予期しない結果が生じる可能性があるため、おすすめしません。

pull キューを構成するには、queue.yaml ファイルを使用する必要があります。

例

名前付きのキューを定義し、デフォルトの処理速度をオーバーライドする基本的な例を次に示します。

queue:
- name: my-push-queue
  rate: 1/s

タスクの試行回数を設定し、デフォルトの処理レートを変更する queue.yaml 構成の複雑な例を以下に示します。

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

構文

queue.yaml ファイルは、ルート ディレクティブが queue である YAML ファイルです。このディレクティブには、0 個以上の名前付きキューが含まれています。各キューの定義では以下の要素を指定できます。

要素 説明
<bucket-size>（push キュー）

省略可。タスクキューでは、トークン バケット アルゴリズムを使用して、タスクの実行レートが制御されます。名前付きの各キューには、bucket_size 値で指定されている最大個数以内のトークンを保持するトークン バケットがあります。アプリケーションで 1 つのタスクが実行されるごとに、バケットからトークンが 1 つ削除されます。 キューのバケットにトークンがなくなるまで、そのキュー内のタスクの処理を続けます。キューに対してユーザーが指定したレートに基づいて、App Engine はバケットに新しいトークンを補充し続けます。

キューに数多くのタスクがあり、レートが高い場合は、バケットサイズによってキューの処理レートが制限されます。バケットサイズの最大値は 500 です。これにより、タスクがキューに投入されるとすぐに処理が開始されるようにレートを高くすると同時に、数多くのタスクが短時間にキューに投入された場合のリソース使用量を制限できます。

キューの bucket_size を指定していない場合、デフォルト値は 5 です。多くの場合、デフォルトのサイズでは小さすぎるため、これより大きい値を設定することをおすすめします。たとえば、処理レートに基づいてバケットサイズを決定できます。

この要素の詳細については、max_burst_size の比較説明をご覧ください。

これは、Cloud Tasks API リファレンスにあります。
<max-concurrent-requests>（push キュー）

省略可。指定されたキューから同時に実行できるタスクの最大数を設定します。この値は整数です。デフォルトでは、キューごとに実行できるタスクが 1,000 個までです。推奨される上限は、キューごとに実行できるタスクが 5,000 個までです。キューは、最初に作成されたときや、しばらくアイドル状態だったときは、ゆっくりと増加することに注意してください。

現在のタスクの数を制限すると、キューの実行レートをより詳細に制御して、同時に実行されるタスクの数が多くなりすぎないようにすることができます。また、Datastore での競合を防止し、他のキューやオンライン処理でリソースを使用できるようになります。

この要素の詳細については、Cloud Tasks API リファレンスにある max_concurrent_dispatches の比較説明をご覧ください。
<mode>

省略可。キューモードを指定します。この設定のデフォルト値は push です。デフォルトの場合、キューは push キューとして識別されます。pull キューを使用する場合は、このモードを pull に設定します。
<name>

必須。キューの名前です。これは QueueFactory.getQueue() を呼び出すときに指定する名前です。

キュー名には大文字、小文字、数字、ハイフンを使用できます。キュー名の最大長は 100 文字です。

どのアプリにも default という名の push キューがあります。このキューには、1 秒あたり 5 タスクのレートが事前に設定されています。このデフォルト キューは、最初に使用または構成されるまで Google Cloud コンソールに表示されません。デフォルト キューの変更（デフォルト レートの変更など）は、queue.yaml ファイルで「default」という名前のキューを定義することで構成できます。
<rate>（push キュー）

必須。このキューでタスクを処理する頻度です。値は数値の後にスラッシュと時間の単位を付けたものです。単位は、s が秒、m が分、h が時間、d が日を表します。たとえば 5/m という値は、タスクが 1 分あたり 5 回のレートで処理されることを示します。rate の最大値は 500/s です。

数値が 0（0/s など）の場合、キューは「一時停止」となり、タスクの処理は行われません。

この要素の詳細については、Cloud Tasks API リファレンスにある max_dispatches_per_second の比較説明をご覧ください。
<retry-parameters>

省略可。push キューで失敗したタスクの再試行回数を構成します。この要素を追加して、特定のキューで失敗するタスクの最大再試行回数を指定できます。再試行の制限時間を設定したり、再試行の間隔を制御したりすることもできます。

再試行パラメータに次のサブ要素を含めることができます。

<task-retry-limit>
再試行回数。たとえば、0 を指定した場合、タスクが失敗しても、タスクの再試行は行われません。1 を指定した場合、タスクが失敗すると、タスクの再試行が 1 回だけ行われます。このパラメータが指定されていない場合、タスクは無期限に再試行されます。task_age_limit とともに task_retry_limit を指定すると、両方の制限に達するまで、タスクが再試行されます。
<task-age-limit>（push キュー）
失敗したタスクを再試行する制限時間。タスクを最初に実行した時点から計測されます。値は数値の後に時間の単位を付けたものです。単位は、s が秒、m が分、h が時間、d が日を表します。たとえば、5d という値は、タスクの実行を最初に試みてから 5 日間という制限を指定します。このパラメータが指定されていない場合、タスクは無期限に再試行されます。task_retry_limit とともに指定すると、App Engine は両方の上限に達するまでタスクを再試行します。
<min-backoff-seconds>（push キュー）
タスクが失敗してから再試行するまでの最小待機時間（秒数）。デフォルト値は 0.1 です。
<max-backoff-seconds>（push キュー）
タスクが失敗してから再試行するまでの最大待機時間（秒数）。デフォルト値は 3600 です。
<max-doublings>（push キュー）
失敗したタスクの再試行間隔が一定になるまでの、間隔が倍増する最大回数。定数は 2**max_doublings * min_backoff_seconds です。デフォルト値は 16 です。
<target>（push キュー）

省略可。サービス / バージョン、フロントエンド バージョン、またはバックエンドの名前となる文字列です。このキューに追加されたすべてのタスクを実行するための名前です。デフォルト値は空の文字列です。

タスクの HTTP リクエストを構築するときは、アプリのドメイン名の前に文字列を付加します。たとえば、アプリ ID が my-app で、ターゲットを my-version-dot-my-service に設定すると、URL のホスト名が my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com に設定されます。

ターゲットを指定しない場合は、タスクをキューに登録したのと同じバージョンのアプリケーションで呼び出されます。つまり、キューのターゲットを指定せずに、デフォルトのアプリケーション バージョンからタスクをキューに登録した場合、タスクはデフォルトのアプリケーション バージョンで呼び出されます。タスクをキューに追加してからタスクが実行されるまでの間にデフォルトのアプリケーション バージョンが変更された場合、タスクは新しいデフォルト バージョンで実行されることに注意してください。

サービスをディスパッチ ファイルと一緒に使用している場合、タスクの HTTP リクエストがインターセプトされて、別のサービスに再ルーティングされる可能性があります。

アプリ内のすべてのキューに対して、次の要素を指定できます。

要素 説明
<total-storage-limit>

省略可。タスクキュー ストレージ（100 MB）で利用可能な、デフォルトで割り当てられたストレージ上限をオーバーライドする文字列。次に例を示します。 

<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

この割り当ては、アプリケーションの合計ストレージ容量（Datastore と Blobstore の容量を含む）の一部です。

接尾辞が指定されていない場合、指定する数値は、バイト単位であると解釈されます。次の接尾辞がサポートされています。

  • B（バイト）
  • K（キロバイト）
  • M（メガバイト）
  • G（ギガバイト）
  • T（テラバイト）

<total-storage-limit> がアプリケーションで利用可能な合計ディスク ストレージ容量を超過している場合、上限は利用可能なストレージ容量に制限されます。

キュー構成ファイルのデプロイ

queue.yaml ファイルはソースコードのどこに配置してもかまいません。

現在使用中のバージョンを変更せずにキュー構成ファイルをデプロイするには、環境に応じて、キューファイルがあるディレクトリで次のいずれかのコマンドを使用します。

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

IntelliJ または Eclipse を使用する場合は、デプロイメント フォームを使用して、デプロイ対象の個々の構成ファイルを選択します。

キューを削除する

キューを削除するには:

  1. queue.yaml ファイルからキューの定義を削除します。

  2. 変更した queue.yaml ファイルをアップロードします。

    gcloud app deploy queue.yaml

  3. Google Cloud コンソールでキューを削除し、キューを選択して [キューを削除] をクリックします。

    [タスクキュー] ページに移動

Google Cloud コンソールから削除したキューを同じ名前で再作成する場合は、削除して 7 日経過してから作成する必要があります。