queue.xml リファレンス

Python |Java |PHP |Go |Node.js

注: このリファレンスでは、App Engine SDK for Java に基づくツール（たとえば、appcfg ツール）で使用される XML 形式の構成ファイルを使用しています。gcloud コマンドラインなどの Cloud SDK ベースのツールや、Cloud SDK ベースの Maven、Gradle、Eclipse、IntelliJ の各プラグインを使用する場合は YAML 形式のリファレンスをご覧ください。

App Engine SDK を使用してタスクキューを管理するアプリケーションでは、queue.xml という構成ファイルを使用してこれらのキューを定義します。Java アプリケーションの場合、このファイルはアプリケーションの WEB-INF ディレクトリに格納されます。queue.xml を使用して push キューと pull キューの両方を構成できます。push キューの場合、デフォルトのキューがあるので、この構成ファイルは省略できます。pull キューは queue.xml で明示的に構成する必要があります。

注意: タスクキュー サービス用のキュー作成は、Cloud Tasks API で使用可能なキュー管理メソッドを使用して管理することもできますが、queue.xml メソッドをキュー管理メソッドと混在させると予期しない結果が生じる可能性があるため、推奨されません。詳細については、キュー管理と queue.yaml の概要をご覧ください。現在、Cloud Tasks のドキュメントを利用するには、アクセス権をリクエストする必要があります。アクセス権はここでリクエストできます。

例

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

<queue-entries>
  <queue>
    <name>my-push-queue</name>
    <rate>1/s</rate>
  </queue>
</queue-entries>

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

<queue-entries>
  <queue>
    <name>fooqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <task-retry-limit>7</task-retry-limit>
      <task-age-limit>2d</task-age-limit>
    </retry-parameters>
  </queue>
  <queue>
    <name>barqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>0</max-doublings>
    </retry-parameters>
  </queue>
  <queue>
    <name>bazqueue</name>
    <rate>1/s</rate>
    <retry-parameters>
      <min-backoff-seconds>10</min-backoff-seconds>
      <max-backoff-seconds>200</max-backoff-seconds>
      <max-doublings>3</max-doublings>
    </retry-parameters>
  </queue>
</queue-entries>

構文

queue.xml ファイルは、ルート要素が <queue-entries> の XML ファイルです。このディレクティブには、<queue> 要素で指定された名目つきのキューが 0 個以上含まれます。キューの定義では、次のような要素を指定できます。

要素	説明
<bucket-size>（push キュー）	省略可。タスクキューでは、トークン バケット アルゴリズムを使用して、タスクの実行レートが制御されます。名前付きの各キューには、bucket_size 値で指定されている最大個数以内のトークンを保持するトークン バケットがあります。アプリケーションで 1 つのタスクが実行されるごとに、バケットからトークンが 1 つ削除されます。キューのバケットにトークンがなくなるまで、そのキュー内のタスクの処理を続けます。キューに対してユーザーが指定したレートに基づいて、App Engine はバケットに新しいトークンを補充し続けます。 キューに数多くのタスクがあり、レートが高い場合は、バケットサイズによってキューの処理レートが制限されます。バケットサイズの最大値は 500 です。これにより、タスクがキューに投入されるとすぐに処理が開始されるようにレートを高くすると同時に、数多くのタスクが短時間にキューに投入された場合のリソース使用量を制限することができます。 キューの bucket_size を指定していない場合、デフォルト値は 5 です。多くの場合、デフォルトのサイズでは小さすぎるため、より大きい値を設定することをおすすめします。推奨サイズは処理レートを 5 で割った値（レート ÷ 5）です。
<max-concurrent-requests>（push キュー）	省略可。指定されたキューから同時に実行できるタスクの最大数を設定します。この値は整数です。デフォルトでは、キューごとに実行できるタスクは 1,000 個までです。 現在のタスクの数を制限すると、キューの実行レートをより詳細に制御して、同時に実行されるタスクの数が多くなりすぎないようにすることができます。また、Datastore での競合を防止し、他のキューやオンライン処理でリソースを使用できるようになります。
<mode>	省略可。キューモードを指定します。この設定のデフォルト値は push です。その場合、キューは push キューとして識別されます。pull キューを使用する場合は、このモードを pull に設定します。
<name>	必須。キューの名前です。これは QueueFactory.getQueue() を呼び出すときに指定する名前です。 キュー名には大文字、小文字、数字、ハイフンを使用できます。キュー名の最大長は 100 文字です。 どのアプリケーションにも default という名の push キューがあります。このキューには、1 秒あたり 5 タスクというレートがあらかじめ設定されていますが、queue.xml でデフォルト キューを定義することにより、このレートを変更できます。queue.xml でデフォルト キューを構成しない場合、デフォルト キューは、最初に使用されるまで Google Cloud Platform Console に表示されません。default という名前のキューを定義することにより、このキューの設定をカスタマイズすることができます。
<rate>（push キュー）	必須。このキューでタスクを処理する頻度です。値は数値の後にスラッシュと時間の単位を付けたものです。単位は、s が秒、m が分、h が時間、d が日を表します。たとえば 5/m という値は、タスクが 1 分あたり 5 回のレートで処理されることを示します。 数値が 0（0/s など）の場合、キューは「一時停止」となり、タスクの処理は行われません。
<retry-parameters>	省略可。push キューで失敗したタスクの再試行回数を構成します。この要素を追加して、特定のキューで失敗するタスクの最大再試行回数を指定できます。再試行の制限時間を設定したり、再試行の間隔を制御したりすることもできます。 再試行パラメータに次のサブ要素を含めることができます。 <task-retry-limit> これは、実際には、タスクの最大試行回数の全体的な制限です。0 または 1 を指定した場合、タスクが失敗するとそのタスクは再試行されません。task_age_limit とともに指定すると、両方の制限に達するまでタスクが再試行されます。このパラメータが指定されていない場合、タスクは無期限に再試行されます。 <task-age-limit>（push キュー） 失敗したタスクを再試行する制限時間。タスクを最初に実行した時点から計測されます。値は数値の後に時間の単位を付けたものです。単位は、s が秒、m が分、h が時間、d が日を表します。たとえば、5d という値は、タスクの実行を最初に試みてから 5 日間という制限を指定します。task_retry_limit と共に指定すると、App Engine は両方の上限に達するまでタスクを再試行します。 <min-backoff-seconds>（push キュー） タスクが失敗してから再試行するまでの最小待機時間（秒数）。 <max-backoff-seconds>（push キュー） タスクが失敗してから再試行するまでの最大待機時間（秒数）。 <max-doublings>（push キュー） 失敗したタスクの再試行間隔が一定になるまでの、間隔が倍増する最大回数。定数は 2**max_doublings * min_backoff_seconds です。
<target>（push キュー）	省略可。サービス / バージョン、フロントエンド バージョン、またはバックエンドの名前となる文字列です。このキューに追加されたすべてのタスクを実行するための名前です。 タスクの HTTP リクエストを構築するときは、文字列の前にアプリのドメイン名を付加します。たとえば、アプリケーション ID が my-app で、ターゲットを my-version.my-service に設定すると、URL のホスト名が my-version.my-service.my-app.appspot.com に設定されます。 ターゲットを指定しない場合は、タスクをキューに登録したのと同じバージョンのアプリケーションで呼び出されます。つまり、キューのターゲットを指定せずに、デフォルトのアプリケーション バージョンからタスクをキューに登録した場合、タスクはデフォルトのアプリケーション バージョンで呼び出されます。タスクをキューに追加してからタスクが実行されるまでの間にデフォルトのアプリケーション バージョンが変更された場合、タスクは新しいデフォルト バージョンで実行されることに注意してください。 サービスをディスパッチ ファイルと一緒に使用している場合、タスクの HTTP リクエストがインターセプトされて、別のサービスに再ルーティングされる可能性があります。

次の要素を <queue-entries> ルート要素内で設定し、アプリ内のすべてのキューに指定できます。

要素

説明

<total-storage-limit>

省略可。タスクキュー ストレージ（100M）で利用可能な、デフォルトで割り当てられたストレージ制限をオーバーライドする文字列。例: <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.xml ファイルは、デフォルト サービスの WEB-INF ディレクトリに配置する必要があります。

現在使用中のバージョンを変更せずにキュー構成ファイルをデプロイするには、次のコマンドを使用します。

appcfg.sh update_queues <application directory>

<application directory> を、アプリケーションのメイン ディレクトリのパスに置き換えます。

キューを削除する

キューを削除するには、次の手順を行います。

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

2. queue.xml ファイルに対する変更をアップロードします。

   [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.sh update_queues [YOUR_APP_DIR]
   

   Windows の場合

   [PATH_TO_APP_ENGINE_SDK]\bin\appcfg.cmd update_queues [YOUR_APP_DIR]
   

3. GCP Console で、キューを選択して [キューを削除] をクリックし、キューを削除します。

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

GCP Console でキューを削除した場合、同じ名前のキューをもう一度作成するには 7 日間経過している必要があります。