このページでは、Waiter リソースを作成する方法について説明します。ウェイターの詳細については、Runtime Configurator の基礎知識をお読みください。
Waiter リソースは、レスポンスを返す前に、特定の成功または失敗の条件を待ちます。成功についても失敗についても、ウェイターがいくつかの変数が特定の前置パス名で作成されるのを待つ基数条件を設定します。変数が作成された後、ウェイターが返されます。その後、アプリケーション コードは、成功または失敗にレスポンスすることができます。変数の現在の状態が、すでに成功または失敗の終了条件のいずれかに一致する場合、ウェイターはすぐに成功または失敗を返します。
始める前に
- このガイドのコマンドラインの例を使用する場合、gcloud コマンドライン ツールをインストールします。
- このガイドの API の例を使用する場合は、API アクセスを設定します。
- Runtime Configurator の基礎知識を読みます。
- RuntimeConfig リソースの作成と削除を読みます。
- データの設定と取得を読みます。
ウェイターの作成
ウェイターを作成するには:
ウェイターの成功、および必要に応じて失敗条件を決定します。
たとえば、次のサンプルコードは、
/status/success
の下でのパスの数が 3 ならウェイターが正常に値を返し、/status/failure
の下でのパスが 2 なら失敗します。{ 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]', 'timeout': '360s', 'success': { 'cardinality': { 'path': '/status/success', 'number': 3 } }, 'failure': { 'cardinality': { 'path': '/status/failure', 'number': 2 } } }
ウェイターを定義するためのベスト プラクティス:
- 1 つのウェイターに 1 つの成功条件および失敗条件のみが許可されます。
- パスごとに 1 つのウェイターを維持する必要があります。
- 失敗条件は常に成功条件の前に評価します。
- 条件間でパス接頭辞が重ならないようにしてください。
ウェイターを作成します。
Deployment Manager
Deployment Manager でウェイターを作成するには、ウェイターのタイプを指定します。
runtimeconfig.v1beta1.waiter
ウェイターのプロパティで、
name
、location
、timeout
、およびウェイターの終了条件を指定します。- name: [NAME] type: runtimeconfig.v1beta1.waiter properties: parent: $(ref.[CONFIG_NAME].name) waiter: [WAITER_NAME] timeout: [TIMEOUT_SECS] success: cardinality: path: [SUCCESS_PATH_PREFIX] number: [SUCCESS_NUMBER]
ここで
[NAME]
は、リソース名です。[CONFIG_NAME]
は、このリクエストの Config リソースです。[WAITER_NAME]
は、このウェイターの名前です。[TIMEOUT_SECS]
は、ウェイターがタイムアウトするまで待機する秒数です。たとえば、300 秒では300s
を使用します。[SUCCESS_PATH_PREFIX]
は、成功条件を監視するためのパス接頭辞です。[SUCCESS_NUMBER]
は、このパスの下で成功したものと考えられる変数の数です。
gcloud
Google Cloud CLI を使用する場合:
gcloud beta runtime-config configs waiters create [WAITER_NAME] \ --config-name [CONFIG_NAME] \ --success-cardinality-path [SUCCESS_PATH_PREFIX] \ --success-cardinality-number [SUCCESS_NUMBER] --timeout [TIMEOUT_SECS]
ここで
[WAITER_NAME]
は、このウェイターの名前です。[CONFIG_NAME]
は、このリクエストの Runtime Config リソースです。[SUCCESS_PATH_PREFIX]
は、成功条件を監視するためのパス接頭辞です。[SUCCESS_NUMBER]
は、このパスの下で成功したものと考えられる変数の数です。[TIMEOUT_SECS]
は、ウェイターがタイムアウトするまで待機する秒数です。gcloud CLI から次のようなレスポンスが返されます。
Created [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/example-waiter].
ツールは、ウェイターを作成した後で、該当するレスポンスの 1 つをウェイターが返すまで Operations リソースをポーリングします。
この
gcloud
コマンドの詳細については、runtime-config configs waiters
のリファレンス ドキュメントをご覧ください。
API
API で、次の URI に
POST
リクエストを送ります。https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters
ここで
[PROJECT_ID]
はこのリクエストのプロジェクト ID です。[CONFIG_NAME]
は、このリクエストの構成の名前です。
リクエスト ペイロードには、ウェイター名、成功条件、タイムアウト期間を含める必要があります。
{ 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]', 'timeout': '[TIMEOUT_SEC]', 'success': { 'cardinality': { 'path': '[SUCCESS_PATH_PREFIX]', 'number': '[SUCCESS_NUMBER]' } } }
ここで
[PROJECT_ID]
はこのリクエストのプロジェクト ID です。[CONFIG_NAME]
は、このリクエストの構成の名前です。[WAITER_NAME]
は、作成するウェイターの名前です。[TIMEOUT_SECS]
は、ウェイターがタイムアウトするまで待機する秒数です。[SUCCESS_PATH_PREFIX]
は、成功条件を監視するためのパス接頭辞です。[SUCCESS_NUMBER]
は、このパスの下で成功したものと考えられる変数の数です。
成功した場合、リクエストは完了のためにポーリングしたオペレーション オブジェクトの名前を返します。
{ "name": "projects/[PROJECT_ID]/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]" }
次に、ウェイターが返ったときに定期的にチェックするためには、ウェイターのポーリングを行います。
このメソッドの詳細については、
waiters().create
のドキュメントをご覧ください。
ウェイター ポーリング
ウェイターを作成した後、関連する Operation リソースをポーリングし、ウェイターが終了条件のいずれかを満たしているかチェックします。ウェイターが終了条件を満たしている、またはタイムアウトした場合、オペレーションは done
として返り、ウェイターの結果に基づいてレスポンスを返します。
ウェイターをポーリングするには、gcloud
か、API を使用します。
gcloud
Google Cloud CLI を使用する場合、ウェイターを作成するリクエストを行うと、ツールが自動的にポーリングを実行して、ウェイターが返されるのを待機します。ツールはウェイターをポーリングする間に、以下のようなレスポンスを出力します。
Waiting for waiter [WAITER_NAME] to finish...
ツールがウェイターの作成後にウェイターをポーリングしないようにするには、作成リクエストに --async
フラグをつけます。
API
REST API では、次の URI に対して GET
リクエストを作成し、ウェイター オペレーションのステータスを取得します。
https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]
ここで
[PROJECT_ID]
はこのリクエストのプロジェクト ID です。[CONFIG_NAME]
は、このリクエストの構成の名前です。[WAITER_NAME]
は、ポーリングするウェイターの名前です。
オペレーションが進行中の場合、API は、次のようなレスポンスを返し、ステータスなしのレスポンスが返されます。
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}
オペレーションが完了している場合は、オペレーションのステータスが done
となり、ウェイター レスポンス セクションに記載されているレスポンスの 1 つが返されます。
このメソッドの詳細については、waiters().create
のドキュメントをご覧ください。
ウェイター レスポンス
成功終了条件
ウェイターが成功終了条件を満たした場合、オペレーションは Waiter リソースを返します。
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"response": {
"@type": "type.googleapis.com/google.cloud.runtimeconfig.v1beta1.Waiter",
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]",
"timeout": "360.000s",
"failure": {
"cardinality": {
"path": "[SUCCESS_PATH_PREFIX]",
"number": "[SUCCESS_NUMBER]"
}
},
"success": {
"cardinality": {
"path": "[FAILURE_PATH_PREFIX]",
"number": [FAILURE_NUMBER]
}
},
"createTime": "2016-04-12T18:02:13.316695490Z",
"done": true
}
}
失敗条件
ウェイターが失敗終了条件を満たしているか、タイムアウトになった場合、エラーが返り、処理が失敗します。
失敗条件を満たしたとき
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"error": {
"code": 9,
"message": "Failure condition satisfied."
}
}
ウェイターがタイムアウトしたとき
{
"name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
"done": true,
"error": {
"code": 4,
"message": "Timeout expired."
}
}
次のステップ
- Runtime Configurator について学習する。
- 変数を設定して取得する方法を学習する。
- 特定の変数を監視するを設定する。
- RuntimeConfig リソースの作成と削除を行う。
- v1beta1 リファレンスを参照する。
- Runtime Configurator の割り当てを参照する。