创建等候程序

本页介绍如何创建 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 的属性中,提供它的 namelocationtimeout 和结束条件:

    - 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

    gcloud 命令行工具中,运行以下命令:

    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 工具会返回如下响应:

      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

gcloud 命令行工具中,当您发出创建 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."
  }
}

后续步骤