创建 Waiter

本页介绍如何创建 Waiter 资源。如需详细了解 Waiter 资源，请参阅 Runtime Configurator 基础知识。

Waiter 资源在获取某个成功或失败条件后会返回响应。您需要针对成功和失败设置基数条件，其中 Waiter 会等待一定数量的变量在特定路径前缀下创建。创建变量后，该 Waiter 会返回结果。之后，您的应用代码可以针对成功或失败做出响应。如果变量的当前状态已经与成功或失败结束条件匹配，则 Waiter 将立即返回成功或失败。

准备工作

创建 Waiter

如需创建 Waiter，请执行以下操作：

  1. 确定 Waiter 的成功或失败条件。

    例如，以下示例代码设置了成功和失败条件，如果 /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
       }
     }
}

    定义 Waiter 的最佳做法：

    • 每个 Waiter 只允许一个成功条件和一个失败条件。
    • 您应该为每条路径保留一个 Waiter。
    • 始终先评估失败条件，再评估成功条件。
    • 不要重叠条件之间的路径前缀。

  2. 创建 Waiter。

    Deployment Manager

    要在 Deployment Manager 中创建 Waiter，请指定 Waiter 类型：

    runtimeconfig.v1beta1.waiter

    在 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] 是此请求的配置资源。
    • [WAITER_NAME] 是此 Waiter 的名称。
    • [TIMEOUT_SECS] 是等待此 Waiter 超时的秒数。例如，如果是 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] 是此 Waiter 的名称。
    • [CONFIG_NAME] 是此请求的 RuntimeConfig 资源。
    • [SUCCESS_PATH_PREFIX] 是要监视的成功条件的路径前缀。
    • [SUCCESS_NUMBER] 是此路径下存在的被视为成功的变量数。

    • [TIMEOUT_SECS] 是等待此 Waiter 超时的秒数。

      gcloud CLI 会返回如下响应：

      Created [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/example-waiter].

      创建 Waiter 之后，该工具会轮询相关的操作资源，直到 Waiter 返回一个适用的响应。

      如需查看此 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] 是此请求的配置名称。

    请求载荷必须包含 Waiter 名称、成功条件和超时持续时间：

    {
 '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] 是要创建的 Waiter 的名称。
    • [TIMEOUT_SECS] 是等待此 Waiter 超时的秒数。
    • [SUCCESS_PATH_PREFIX] 是要监视的成功条件的路径前缀。
    • [SUCCESS_NUMBER] 是此路径下存在的被视为成功的变量数。

    如果成功，请求将返回您采用轮询方式来判断操作是否完成的操作对象的名称：

    {
    "name": "projects/[PROJECT_ID]/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

    接下来，轮询 Waiter，以定期检查 Waiter 的返回时间。

    如需详细了解该方法，请阅读 waiters().create 文档。

轮询 Waiter

创建 Waiter 后，请轮询相关的操作资源，以检查 Waiter 是否满足其中一个结束条件。如果 Waiter 满足结束条件或超时，操作会返回 done 并根据 Waiter 的结果返回响应。

使用 gcloud 或 API 来轮询 Waiter。

gcloud

在 Google Cloud CLI 中，当您发出创建 Waiter 的请求后，该工具会自动执行轮询并等待 Waiter 返回结果。在轮询 Waiter 时，该工具会输出如下所示的响应：

Waiting for waiter [WAITER_NAME] to finish...

如果您不希望该工具在 Waiter 创建完毕后执行轮询，请在创建请求中提供 --async 标志。

API

在 REST API 中，向以下 URI 发出 GET 请求以获取 Waiter 操作状态：

https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]

其中：

  • [PROJECT_ID] 是此请求的项目 ID。
  • [CONFIG_NAME] 是此请求的配置名称。
  • [WAITER_NAME] 是要轮询的 Waiter 的名称。

如果操作仍在进行，API 会返回如下响应，缺少状态：

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]"
}

如果操作完成，操作将被标记为 done 并返回 Waiter 响应部分中所述的响应之一。

如需详细了解该方法，请阅读 waiters().create 文档。

Waiter 响应

成功结束条件

如果 Waiter 满足成功结束条件，操作将返回 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
  }
}

失败条件

如果 Waiter 满足失败结束条件或超时，操作将返回错误。

满足失败条件

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 9,
    "message": "Failure condition satisfied."
  }
}

Waiter 超时

{
  "name": "projects/[PROJECT_NAME]/configs/[CONFIG_NAME]/operations/waiters/[WAITER_NAME]",
  "done": true,
  "error": {
    "code": 4,
    "message": "Timeout expired."
  }
}

后续步骤