建立等候程序

本頁說明如何建立等候程序資源。如要進一步瞭解等候程序，請參閱 Runtime Configurator 基礎知識一文。

等候程序資源會先等待系統符合某些成功或失敗條件後，才會傳回回應。您可以針對成功和失敗的情況設定基數條件，其中等候程序會等待系統在特定路徑的前置字串底下建立一定數量的變數。系統建立變數後，等候程序就會傳回回應。您的應用程式程式碼就可以根據成功或失敗情況做出回應。如果變數的目前狀態已符合成功或失敗結束條件，則等候程序會立即傳回成功或失敗回應。

事前準備

建立等候程序

如何建立等候程序：

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

    定義等候程序的最佳做法：

    • 每個等候程序只允許使用一個成功條件和一個失敗條件。
    • 每個路徑都應保留一個等候程序。
    • 系統會一律優先評估失敗條件，然後再評估成功條件。
    • 請勿在條件之間重疊路徑前置字串。

  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] 是這項要求的 RuntimeConfig 資源。
    • [SUCCESS_PATH_PREFIX] 是要監看成功條件的路徑前置字串。
    • [SUCCESS_NUMBER] 是系統將路徑視為成功時，路徑底下存在的變數數量。

    • [TIMEOUT_SECS] 是等候程序逾時之前的等待秒數。

      gcloud CLI 會傳回類似下方的回應：

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

      建立等候程序後，工具會輪詢相關的 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 說明文件。

輪詢等候程序

建立等候程序後，請輪詢相關的 Operations 資源，以確認等候程序是否達成任何結束條件。如果等候程序已達成結束條件或逾時，作業會傳回 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，並且傳回在 等候程序回應一節中說明的其中一個回應。

如要進一步瞭解此方法，請參閱 waiters().create 說明文件。

等候程序回應

成功結束條件

如果等候程序符合成功結束條件，作業會傳回下列等候程序資源：

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

後續步驟