ウェイターを作成する

このページでは、Waiter リソースを作成する方法について説明します。ウェイターの詳細については、Runtime Configurator の基礎知識をお読みください。

Waiter リソースは、レスポンスを返す前に、特定の成功または失敗の条件を待ちます。成功についても失敗についても、ウェイターがいくつかの変数が特定の前置パス名で作成されるのを待つ基数条件を設定します。変数が作成された後、ウェイターが返されます。その後、アプリケーション コードは、成功または失敗にレスポンスすることができます。変数の現在の状態が、すでに成功または失敗の終了条件のいずれかに一致する場合、ウェイターはすぐに成功または失敗を返します。

始める前に

ウェイターの作成

ウェイターを作成するには:

  1. ウェイターの成功、および必要に応じて失敗条件を決定します。

    たとえば、次のサンプルコードは、/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 つのウェイターを維持する必要があります。
    • 失敗条件は常に成功条件の前に評価します。
    • 条件間でパス接頭辞が重ならないようにしてください。

  2. ウェイターを作成します。

    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."
  }
}

次のステップ