このリリースの HTTP Targets では、Cloud Tasks ハンドラを、パブリック IP アドレスを持つ任意の HTTP エンドポイントで実行できるようになりました。このようなエンドポイントには、Cloud Functions、Cloud Run、GKE、Compute Engine や、場合によってはオンプレミスのウェブサーバーなどがあります。こうしたサービスで、信頼性が高く構成が可能な方法でタスクを実行できるようになります。
このページでは、HTTP Target タスクをプログラムによって作成し、Cloud Tasks キューに入れる方法を説明します。
タスクの名前を指定した場合、Cloud Tasks はその名前を使用してタスクの重複排除を行いますが、必要な処理によってレイテンシが増加する場合があります。
一般に、タスクは HTTP リクエストの形式で作成します。次の例のように、クライアント ライブラリとサービス アカウントを使用することで、Cloud Tasks サーバーとの通信の詳細を管理でき、タスクの作成が簡単になります。
HTTP Target タスクの作成
HTTP ターゲットを含むタスクの場合、次の 2 つの方法でタスクを作成できます。
BufferTask
メソッド(プレビュー): キューがサービスの前にタスクをバッファリングするように設定されている場合は、この方法を使用します。キューにはキューレベルのルーティングが必要です。CreateTask
メソッド: これはより複雑です。タスク オブジェクトを明示的に作成する必要があります。この方法は、キュー内のタスクのルーティング構成が異なる場合に使用します。この場合は、タスクレベルでルーティングを指定します。
BufferTask
メソッド
BufferTask
メソッドを使用するには、キューでキューレベルのルーティングを使用する必要があります(それ以外の場合は、タスクのルーティング情報がありません)。キューでキューレベルのルーティングがまだ使用されていない場合は、HTTP タスクのキューレベルのルーティングを構成するをご覧ください。
クライアント ライブラリで BufferTask
メソッドを使用できますが、アプリケーションで HTTP リクエストを作成します。次の例では、BufferTask
メソッドに従って、curl
を使用してタスクを作成しています。
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2beta3/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \
以下を置き換えます。
HTTP_METHOD
: リクエストの HTTP メソッド(例:GET
やPOST
)。PROJECT_ID
: Google Cloud プロジェクトの ID。 これを取得するには、ターミナルで次のコマンドを実行します。gcloud config get-value project
LOCATION
: キューのロケーション。QUEUE_ID
: キューの ID。
CreateTask
メソッド
CreateTask
メソッドを使用してタスクを作成するには、タスク オブジェクトを明示的に作成して定義する必要があります。タスクを処理するサービスとハンドラを指定する必要があります。
必要に応じて、タスク固有のデータをハンドラに渡すこともできます。また、タスクが実行されるタイミングのスケジューリングや、タスクが失敗した場合の再試行回数の制限など、タスクの構成を微調整することもできます。
次の例では、CreateTask
メソッドを使用して、Cloud Tasks クライアント ライブラリを使用してタスクを作成します。
C#
Python
requirements.txt
ファイルをメモします。
Java
pom.xml
ファイルをメモします。
PHP
composer.json
ファイルをメモします。
Go
Node.js
package.json
ファイルをメモします。
Ruby
HTTP Target ハンドラの認証のサービス アカウントの設定
Cloud Tasks から HTTP Target ハンドラを呼び出すことができます。このハンドラにアクセスするには認証が必要であり、サービス アカウントに適切な認証情報が設定されている必要があります。
現在使用しているサービス アカウントがある場合は、適切なロールを付与します。ここでは、この機能専用の新しいサービス アカウントを作成する方法について説明します。 Cloud Tasks の認証に使用する既存または新しいサービス アカウントは、Cloud Tasks キューと同じプロジェクトにあることが必要です。
Google Cloud Console で、[サービス アカウント] ページに移動します。
必要に応じて、該当するプロジェクトを選択します。
[サービス アカウントを作成] をクリックします。
アカウントの表示名を指定します。コンソールでアカウントに関連するメール アカウント名が作成されます。この名前でアカウントが参照されます。必要に応じて、アカウントの説明を追加することもできます。
[作成して続行] をクリックします。
[ロールを選択] をクリックし、[Cloud Tasks] > [Cloud Tasks へのデータ追加] の順に選択します。このロールにより、タスクをキューに追加する権限がサービス アカウントに付与されます。
[+ 別の役割を追加] をクリックします。
[ロールを選択] をクリックし、[サービス アカウント] > [サービス アカウント ユーザー] の順に選択します。このロールにより、サービス アカウントは、サービスア アカウントの認証情報を使用してキューがトークンを作成することを承認できます。
ハンドラが Google Cloud の一部である場合は、ハンドラが実行されているサービスへのアクセスに関連付けられたロールをサービスア アカウントに付与します。 Google Cloud 内の各サービスには異なるロールが必要です。たとえば、Cloud Run でハンドラにアクセスするには、Cloud Run 起動元のロールが必要です。作成したサービス アカウントまたはプロジェクト内の他のサービス アカウントを使用できます。
[完了] をクリックして、サービス アカウントの作成を完了します。
Cloud Tasks 自体には、Cloud Tasks Service Agent
ロールが付与された独自のサービス アカウントが必要です。これは、Cloud Tasks サービス アカウントに関連付けられた認証情報に基づいてヘッダー トークンを生成し、ハンドラ ターゲットで認証できるようにするためです。このロールが付与された Cloud Tasks のサービス アカウントは、Cloud Task API を有効にすると自動的に作成されます。ただし、2019 年 3 月 19 日より前にこの API を有効にしていた場合は、このロールを手動で追加する必要があります。
認証トークンがある HTTP Target タスクの使用
Cloud Tasks とそのような認証が必要な HTTP Target ハンドラの間で認証を行うために、Cloud Tasks はヘッダー トークンを作成します。このトークンは、メールアドレスで識別される Cloud Tasks Enqueuer
サービス アカウントの認証情報に基づいて生成されます。認証に使用するサービス アカウントは、Cloud Tasks キューが存在するプロジェクトの一部であることが必要です。リクエストは、ヘッダー トークンとともに HTTPS を介してキューからハンドラに送信されます。ID トークンまたはアクセス トークンのいずれかを使用できます。ID トークンは通常、Google Cloud で実行されているハンドラ(Cloud Functions や Cloud Run など)で使用されます。主な例外は、*.googleapis.com
でホストされている Google API で、この API ではアクセス トークンが使用されます。タスク自体で ID(OIDC)トークンまたはアクセス(OAuth)トークンを指定します。
BufferTask
メソッド
BufferTask
メソッドを使用してタスクを作成する場合、キューレベルで設定された OIDC 構成または OAuth 構成はタスクレベルの構成をオーバーライドします。キューレベルで認証を構成するには、Cloud Tasks キューを作成するをご覧ください。ただし、タスクの作成時に認証を行うことができます。次の例では、アプリケーションのデフォルト認証情報を使用してタスクの作成時に認証します。
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2beta3/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \ -H "Authorization: Bearer ACCESS_TOKEN"
以下を置き換えます。
HTTP_METHOD
: リクエストの HTTP メソッド(例:GET
やPOST
)。PROJECT_ID
: Google Cloud プロジェクトの ID。 これを取得するには、ターミナルで次のコマンドを実行します。gcloud config get-value project
LOCATION
: キューのロケーション。QUEUE_ID
: キューの ID。ACCESS_TOKEN
: 自分のアクセス トークン。これを取得するには、ターミナルで次のコマンドを実行します。gcloud auth application-default login
gcloud auth application-default print-access-token
CreateTask
メソッド
次の例では、Cloud Tasks クライアント ライブラリで CreateTask
メソッドを使用して、ヘッダー トークンの作成を含むタスクを作成します。この例では ID トークンが使用されます。
アクセス トークンを使用する場合は、リクエストの作成時に OIDC パラメータを、それぞれの言語に応じて適切な OAuth パラメータに置き換えます。
Python
requirements.txt
ファイルをメモします。
Java
pom.xml
ファイルをメモします。
Go
Node.js
package.json
ファイルをメモします。
独自の HTTP Target タスクハンドラの指定
HTTP Target タスクハンドラは App Engine タスクハンドラとよく似ていますが、次の点が異なります。
- タイムアウト: HTTP Target タスクハンドラでは、デフォルトのタイムアウトは 10 分、最大は 30 分です。
- 認証ロジック: 対象とするサービスで独自のコードを作成してトークンを検証する場合は、ID トークンを使用する必要があります。この操作に関する詳細については、OpenID Connect の、特に ID トークンの検証をご覧ください。
ヘッダー: HTTP Target リクエストには、ハンドラが使用できるタスク固有の情報が含まれたキューによって、ヘッダーが設定されています。これらは App Engine タスク リクエストに設定されたヘッダーと似ていますが、同じではありません。 これらのヘッダーは情報のみを提供します。これらは ID のソースとして使用しないでください。
アプリに対する外部ユーザー リクエストにこのようなヘッダーが含まれている場合、それらは内部ユーザー リクエストによって置換されます。ただし、ログイン済みのアプリケーション管理者からのリクエストは唯一の例外です。アプリケーション管理者は、テストの目的でこのヘッダーを設定することが許可されています。
HTTP Target リクエストには、常に次のヘッダーが含まれます。
ヘッダー 説明 X-CloudTasks-QueueName
キューの名前。 X-CloudTasks-TaskName
タスクの「省略」名。または、作成時に名前が指定されなかった場合は、システムによって生成された一意の ID です。これは、完全なタスク名(task_name = projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
)のmy-task-id
値になります。X-CloudTasks-TaskRetryCount
このタスクが再試行された回数。最初の試行の場合は、この値は 0
です。この試行回数には、5XX エラーコードが原因でタスクが異常終了したため実行フェーズに到達できなかった試行も含まれています。X-CloudTasks-TaskExecutionCount
タスクがハンドラからレスポンスを受け取った合計回数。Cloud Tasks は成功のレスポンスを受け取った時点でタスクを削除するため、それ以前のハンドラからのレスポンスはすべて失敗を意味します。この回数には、5XX エラーコードが原因の失敗は含まれていません。 X-CloudTasks-TaskETA
タスクのスケジュール時間。1970 年 1 月 1 日からの秒数で指定されます。 さらに、Cloud Tasks からのリクエストには次のヘッダーが含まれる場合もあります。
ヘッダー 説明 X-CloudTasks-TaskPreviousResponse
前回の再試行の HTTP レスポンス コード。 X-CloudTasks-TaskRetryReason
タスクを再試行する理由。
Cloud Tasks サービス アカウントに Cloud Tasks サービス エージェントの役割を追加
この操作は、Cloud Tasks API を 2019 年 3 月 19 日より前に有効にした場合のみ必要になります。
コンソールの使用
- プロジェクトのプロジェクト番号は、Google Cloud プロジェクトの設定ページで確認できます。
- その番号をコピーします。
- IAM 管理コンソール ページを開きます。
- [
Add
] をクリックします。[Add members
] 画面が開きます。 [新しいメンバー] ボックスに、次の形式のメールアドレスを追加します。
service-[project-number]@gcp-sa-cloudtasks.iam.gserviceaccount.com
[project-number] は上記でコピーしたプロジェクト番号に置き換えます。
[
Select a role
] プルダウンから [Service Management
] -> [Cloud Tasks Service Agent
] を選択します。[
Save
] をクリックします。
gcloud の使用
プロジェクト番号を確認します。
gcloud projects describe [project-id] --format='table(projectNumber)'
[project-id] は実際のプロジェクト ID に置き換えます。
その番号をコピーします。
コピーしたプロジェクト番号を使用して、Cloud Tasks サービス アカウントに
Cloud Tasks Service Agent
の役割を付与します。gcloud projects add-iam-policy-binding [project-id] --member serviceAccount:service-[project-number]@gcp-sa-cloudtasks.iam.gserviceaccount.com --role roles/cloudtasks.serviceAgent
[project-id] は実際のプロジェクト ID に、[project-number] は上記のプロジェクト番号に置き換えます。
次のステップ
- RPC API リファレンスで HTTP Target タスクの詳細を確認する。
- REST API リファレンスで HTTP Target タスクについて学びます。