Criar um Waiter

Esta página explica como criar um recurso Waiter. Para saber mais sobre os waiters, leia o artigo Noções básicas do Runtime Configurator.

Um recurso Waiter aguarda uma determinada condição de êxito ou falha antes de devolver uma resposta. Tanto para o êxito como para a falha, define uma condição de cardinalidade, em que o waiter aguarda a criação de um determinado número de variáveis num prefixo de caminho específico. Depois de criadas as variáveis, o waiter é devolvido. Em seguida, o código da aplicação pode responder ao sucesso ou à falha. Se o estado atual das suas variáveis já corresponder às condições de conclusão de êxito ou falha, o waiter devolve êxito ou falha imediatamente.

Antes de começar

Criar um empregado de mesa

Para criar um waiter:

  1. Determine a condição de sucesso e, opcionalmente, de falha para o waiter.

    Por exemplo, o seguinte código de exemplo define as condições de êxito e falha, em que o waiter é devolvido com êxito se o número de caminhos em /status/success for três e falha se o caminho em /status/failure for dois:

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

    Práticas recomendadas para definir um waiter:

    • Só é permitida uma condição de êxito e uma condição de falha por waiter.
    • Deve manter um waiter por caminho.
    • As condições de falha são sempre avaliadas antes das condições de êxito.
    • Não sobreponha prefixos de caminhos entre condições.

  2. Crie o waiter.

    Deployment Manager

    Para criar um waiter no Deployment Manager, especifique o tipo de waiter:

    runtimeconfig.v1beta1.waiter

    Nas propriedades do waiter, indique o name, o location, o timeout e as condições de conclusão do waiter:

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

    where:

    • [NAME] é o nome do recurso.
    • [CONFIG_NAME] é o recurso de configuração para este pedido.
    • [WAITER_NAME] é o nome deste empregado de mesa.
    • [TIMEOUT_SECS] é o número de segundos a aguardar antes de o waiter expirar. Por exemplo, para 300 segundos, use 300s.
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho a observar para uma condição de sucesso.
    • [SUCCESS_NUMBER] é o número de variáveis que existem neste caminho a considerar bem-sucedidas.

    gcloud

    Com a CLI do Google Cloud:

    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]

    where:

    • [WAITER_NAME] é o nome deste empregado de mesa.
    • [CONFIG_NAME] é o recurso RuntimeConfig para este pedido.
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho a observar para uma condição de sucesso.
    • [SUCCESS_NUMBER] é o número de variáveis que existem neste caminho a considerar bem-sucedidas.

    • [TIMEOUT_SECS] o número de segundos a aguardar antes de o tempo limite de espera expirar.

      A CLI gcloud devolve uma resposta como:

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

      Depois de criar o waiter, a ferramenta sonda o recurso Operations relacionado até que o waiter retorne com uma das respostas aplicáveis.

      Para uma referência completa deste comando gcloud, leia a documentação de referência runtime-config configs waiters.

    API

    Na API, faça um pedido POST para o seguinte URI:

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

    where:

    • [PROJECT_ID] é o ID do projeto para este pedido.
    • [CONFIG_NAME] é o nome da configuração para este pedido.

    O payload do pedido tem de conter o nome do waiter, a condição de êxito e a duração do limite de tempo:

    {
 'name': 'projects/[PROJECT_ID]/configs/[CONFIG_NAME]/waiters/[WAITER_NAME]',
 'timeout': '[TIMEOUT_SEC]',
 'success': {
    'cardinality': {
       'path': '[SUCCESS_PATH_PREFIX]',
       'number': '[SUCCESS_NUMBER]'
    }
  }
}

    where:

    • [PROJECT_ID] é o ID do projeto para este pedido.
    • [CONFIG_NAME] é o nome da configuração para este pedido.
    • [WAITER_NAME] é o nome do waiter a criar.
    • [TIMEOUT_SECS] o número de segundos a aguardar antes de o tempo limite de espera expirar.
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho a observar para uma condição de sucesso.
    • [SUCCESS_NUMBER] é o número de variáveis que existem neste caminho a considerar bem-sucedidas.

    Se for bem-sucedido, o pedido devolve o nome do objeto operations que consulta para saber se está concluído:

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

    Em seguida, sondar o waiter para verificar periodicamente quando o waiter regressa.

    Para saber mais sobre o método, leia a waiters().create documentação.

Pedir um empregado de mesa

Depois de criar um waiter, sondar o recurso Operations relacionado para verificar se o waiter cumpriu uma das condições de conclusão. Se o processo de espera tiver cumprido uma condição final ou tiver excedido o tempo limite, a operação é devolvida como done e devolve uma resposta com base nos resultados do processo de espera.

Use gcloud ou a API para chamar um empregado de mesa.

gcloud

Com a CLI do Google Cloud, quando faz um pedido para criar um waiter, a ferramenta faz automaticamente a sondagem e aguarda que o waiter seja devolvido. A ferramenta imprime uma resposta semelhante à seguinte enquanto sondar o waiter:

Waiting for waiter [WAITER_NAME] to finish...

Se não quiser que a ferramenta consulte o waiter após a criação, forneça a flag --async com o seu pedido de criação.

API

Na API REST, faça um pedido GET ao seguinte URI para obter o estado da operação de espera:

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

where:

  • [PROJECT_ID] é o ID do projeto para este pedido.
  • [CONFIG_NAME] é o nome da configuração para este pedido.
  • [WAITER_NAME] é o nome do waiter a sondar.

Se a operação ainda estiver em curso, a API devolve uma resposta semelhante à seguinte, sem um estado:

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

Se a operação estiver concluída, é marcada como done e devolve uma das respostas descritas na secção Respostas do Waiter.

Para saber mais sobre o método, leia a waiters().create documentação.

Respostas do empregado de mesa

Condição de conclusão bem-sucedida

Se o waiter tiver cumprido uma condição de conclusão bem-sucedida, a operação devolve o recurso 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
  }
}

Condição de falha

Se o waiter cumprir a condição de fim failure ou exceder o tempo limite, a operação devolve um erro.

A condição de falha foi cumprida

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

O tempo limite do waiter foi excedido

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

O que se segue?