Cloud Tasks キューを構成する

このページでは、Google Cloud CLI の gcloud コマンドを使用して Cloud Tasks キューを構成する方法について説明します。

概要

Cloud Tasks キューの構成はキューのすべてのタスクに適用されます。構成は、キューの作成時だけでなく、キューの作成後にも行うことができます。

キューの構成には、次の基本的な 3 つの設定項目があります。

ルーティング
レート上限
再試行パラメータ

キューレベルのルーティング

キューレベルでルーティングを構成すると、タスクレベルで設定されたルーティングがオーバーライドされます。これは、Cloud Tasks をターゲットサービスの前にあるバッファとして使用する場合や、キュー内のすべてのタスクのルーティングを変更する必要がある場合に便利です。

キューレベルのルーティングは、次のものに適用されます。

現在キュー内にあるタスク
キューレベルのルーティングが設定された後にキューに追加されるタスク

制限事項

キューレベルのルーティングには、Cloud Key Management Service（Cloud KMS）の顧客管理の暗号鍵（CMEK）との互換性がありません。CMEK が有効になっている場合、次の操作はできません。

キューレベルのルーティングがあるキューにタスクを作成する
キューレベルのルーティングを適用する

HTTP タスクのキューレベルルーティングを構成する

キューレベルのルーティングを適用する

キューの作成時またはキューの更新時に、タスクレベルのルーティングをオーバーライドするようにキューを構成できます。キューレベルのルーティングを構成するには、キューの uriOverride パラメータを優先ルートに設定します。既存のキューに更新としてキューレベルのルーティングを適用する場合、変更を適用する前にキューを一時停止し、変更を適用してから 1 分間待ってキューを再開します。新しい構成が有効になるまで最大 1 分かかることがあります。そのため、キューの再開を待機すると、古い構成でタスクがディスパッチされるのを防ぐことができます。

キューレベルのルーティングを更新または削除する

キューを一時停止します。
Console
Google Cloud コンソールを使用してキューを一時停止するには:
1. Console で Cloud Tasks キューのページを開きます。
  
  Cloud Tasks キューのページに移動
2. 一時停止するキューの名前を選択して、[キューの一時停止] をクリックします。
3. 削除を確認します。
gcloud
```
gcloud tasks queues pause QUEUE_ID
```
QUEUE_ID は、プロジェクトの ID に置き換えます。
キューレベルのルーティングを更新または削除します。
- キューレベルのルーティングを更新するには、更新したルートに uriOverride パラメータを設定します。
- REST API または RPC API を使用してキューレベルのルーティングを削除するには:
  - REST API: 空のペイロードを含むキューの patch リクエストと httpTarget に設定された updateMask パラメータ。
  - RPC API: 空のペイロードを含むキューの updateQueueRequest リクエストと http_target に設定された update_mask パラメータ。
次の例では、REST API を使用して、ホストタスクのルーティング先を更新しています。
```
curl -X PATCH -d @- -i \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
"https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID?updateMask=httpTarget.uriOverride" << EOF
{
"httpTarget": {"uriOverride":{"host":"NEW_HOST"}}
}
EOF
```
以下を置き換えます。
- PROJECT_ID: Google Cloud プロジェクトの ID。これは、ターミナルで次のコマンドを実行することで取得できます。
```
gcloud config get-value project
```
- LOCATION: キューの場所。
- QUEUE_ID: キューの ID。
- ACCESS_TOKEN: 自分のアクセストークン。これは、ターミナルで次のコマンドを実行することで取得できます。
  1. ```
  gcloud auth application-default login
```
2. ```
gcloud auth application-default print-access-token
```
- NEW_HOST: キューをルーティングする新しいホスト。
1 分ほど待ちます。

新しい構成が有効になるまで最大 1 分かかることがあります。そのため、キューの再開を待機すると、古い構成でタスクがディスパッチされるのを防ぐことができます。
キューを再開します。
Console
Google Cloud コンソールを使用してキューを再開するには:
1. Console で Cloud Tasks キューのページを開きます。
  
  Cloud Tasks キューのページに移動
2. 一時停止するキューの名前を選択して、[キューの再開] をクリックします。
3. 削除を確認します。
gcloud
```
gcloud tasks queues resume QUEUE_ID
```
QUEUE_ID は、プロジェクトの ID に置き換えます。

App Engine タスクのキューレベルのルーティングを構成する

App Engine タスクのキューレベルのルーティングを構成するには、キューの appEngineRoutingOverride パラメータを、優先する App Engine サービスとバージョンに設定します。

このデフォルト以外のキューレベルのルーティングを設定してタスクレベルのルーティングをオーバーライドするには、gcloud を使用します。

  gcloud tasks queues update QUEUE_ID\
      --routing-override=service:SERVICE,version:VERSION

以下を置き換えます。

SERVICE: タスク処理を担当する App Engine ワーカーサービスです。
VERSION: アプリのバージョン。

たとえば、キュー内のすべてのタスクを処理するために SERVICE というワーカーサービスを設定すると、そのサービスとデフォルトバージョンにルーティングできます。

  gcloud tasks queues update QUEUE_ID \
      --routing-override=service:SERVICE

キューについて説明コマンド（Describe）を使用します。

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

以下を置き換えます。

QUEUE_ID: キュー ID（略称）
LOCATION: キューの場所

出力は次のようになります。

appEngineRoutingOverride:
  host: SERVICE.PROJECT_ID.appspot.com
  service: SERVICE
name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: 1000
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

App Engine ターゲットのキューレベルルーティングを削除する

キューレベルのルーティングが削除されると、タスクレベルのルーティングは、現在キューにあるタスクと、今後キューに追加されるタスクの両方に適用されます。キューレベルのルーティングを削除するには、次のコマンドを実行します。

  gcloud tasks queues update QUEUE_ID \
      --clear-routing-override

レート制限の定義

キューによってディスパッチされる同時タスクの最大レートと最大数を設定できます。

  gcloud tasks queues update QUEUE_ID \
      --max-dispatches-per-second=DISPATCH_RATE \
      --max-concurrent-dispatches=MAX_RUNNING

以下を置き換えます。

DISPATCH_RATE: ディスパッチレート（バケット内のトークンが更新されるレート）。タスクが比較的安定している状況では、これはタスクがディスパッチされる割合に相当します。
MAX_RUNNING: 一度に実行できるキュー内のタスクの最大数。

たとえば、パラメータを設定せずにキューを作成した場合は、次の関数を呼び出して同時タスクの最大数を更新できます。

  gcloud tasks queues update QUEUE_ID \
          --max-concurrent-dispatches=MAX_CONCURRENT_DISPATCHES

Describe のキュー:

  gcloud tasks queues describe QUEUE_ID --location=LOCATION

以下を置き換えます。

QUEUE_ID: キュー ID（略称）
LOCATION: キューの場所

出力は次のようになります。

name: projects/PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
rateLimits:
  maxBurstSize: 100
  maxConcurrentDispatches: MAX_CONCURRENT_DISPATCHES
  maxDispatchesPerSecond: 500.0
retryConfig:
  maxAttempts: 100
  maxBackoff: 3600s
  maxDoublings: 16
  minBackoff: 0.100s
state: RUNNING

`gcloud` コマンドと `queue.yaml` を使用した処理速度の定義

キュー処理速度を定義する Cloud Tasks API の方法と、queue.yaml ファイルのアップロードによる方法では、どちらもキューで同じ基盤メカニズムを使用するにもかかわらず、わずかな違いがあります。

どちらの場合も、トークンバケットアルゴリズムを使用して、タスクの実行レートが制御されます。名前付きの各キューには、トークンを保持するバケットがあります。

アプリケーションで 1 つのタスクが実行されるたびに、バケットからトークンが 1 つ削除されます。キューのバケットのトークンがなくなるまでタスクの処理を続けます。キューに指定した max_dispatches_per_second レートに基づいて、システムからバケットに新しいトークンが続けて補充されます。処理対象のタスクがキューにあって、そのキューのバケットにトークンがある場合、システムはトークンと同じ数のタスクを、設定した max_concurrent_dispatches 値まで、同時に処理します。

負荷が不均等になると、バケット内のトークンの数が大幅に増加し、リクエストの急増に伴い、処理が急増する場合があります。この場合、キューの実際のディスパッチレートが max_dispatches_per_second レートを超え、システムリソースが消費され、ユーザーリクエストの処理とリソースの競合が発生する可能性があります。ダウンストリームサービスの比較的遅い SLA に基づいてディスパッチレートを管理するキューを使用している場合、HTTP 429（リクエストが多すぎます）や 503（サービスを利用できません）などのエラーが発生します。

Cloud Tasks API メソッドを使用する場合、キューのディスパッチレートを定義する 2 つのフィールドがあります。

max_dispatches_per_second
max_concurrent_dispatches

3 つ目のフィールド max_burst_size は、max_dispatches_per_second に設定した値に基づいてシステムによって計算されます。

queue.yaml メソッドを使用する場合は、3 つの要素すべてを設定できます。

max_concurrent_requests（max_concurrent_dispatches と同等）
rate（max_dispatches_per_second と同等）
bucket_size（max_burst_size と同等）

ほとんどの場合、Cloud Tasks API メソッドを使用してシステムに max_burst_size を設定させると、リクエストのバーストをとても効率的に管理できます。ただし、特に目標のレートが比較的低い場合には、queue.yaml メソッドを使用して手動で bucket_size を小さい値に設定するか、Cloud Tasks API で max_concurrent_dispatches を小さい値に設定すると、より細かく制御できます。

再試行パラメータの設定

タスクが正常に完了しない場合、Cloud Tasks は設定されたパラメータに従って、指数バックオフによりタスクを再試行します。キュー内で失敗したタスクを再試行する最大回数を指定したり、再試行の制限時間を設定したり、試行間隔を制御したりできます。

  gcloud tasks queues update QUEUE_ID \
      --max-attempts=MAX_ATTEMPTS \
      --min-backoff=MIN_INTERVAL \
      --max-backoff=MAX_INTERVAL \
      --max-doublings=MAX_DOUBLINGS \
      --max-retry-duration=MAX_RETRY_DURATION

以下を置き換えます。

MAX_ATTEMPTS: 最初の試行を含むタスクの最大試行回数。このフラグを unlimited に設定すると、再試行が無制限に許可されます。
MIN_INTERVAL: 再試行の間に待機する最小時間です。値は「s」で終わる文字列でなければなりません（5s など）。
MAX_INTERVAL: 再試行の間に待機する最大時間です。値は「s」で終わる文字列でなければなりません（5s など）。
MAX_DOUBLINGS: 失敗したタスクの再試行間隔が一定になるまでの、間隔が倍増する最大回数。
MAX_RETRY_DURATION: 失敗したタスクを再試行する最大時間で、タスクが最初に試行された時点から測定されます。値は「s」で終わる文字列でなければなりません（5s など）。

キューが正常に構成されたことを確認します。

    gcloud tasks queues describe QUEUE_ID --location=LOCATION

以下を置き換えます。

QUEUE_ID: キュー ID（略称）
LOCATION: キューの場所

次のステップ

HTTP ターゲットタスクの作成方法を学習する。
App Engine タスクの作成方法を学習する。
Cloud Logging の設定を学習する。
RPC API リファレンスでキュー管理の詳細を学習する。
REST API リファレンスでキュー管理の詳細を学習する。
Cloud Tasks gcloud コマンドの一覧を確認する。

Cloud Tasks キューを構成する

概要

キューレベルのルーティング

制限事項

HTTP タスクのキューレベル ルーティングを構成する

キューレベルのルーティングを適用する

キューレベルのルーティングを更新または削除する

Console

gcloud

Console

gcloud

App Engine タスクのキューレベルのルーティングを構成する

App Engine ターゲットのキューレベル ルーティングを削除する

レート制限の定義

gcloud コマンドと queue.yaml を使用した処理速度の定義

再試行パラメータの設定

次のステップ

HTTP タスクのキューレベルルーティングを構成する

App Engine ターゲットのキューレベルルーティングを削除する

`gcloud` コマンドと `queue.yaml` を使用した処理速度の定義