Criação de um Waiter

Esta página explica como criar um recurso Waiter. Para saber mais sobre encarregados, leia Fundamentos do Runtime Configurator.

Esse recurso aguarda uma condição de sucesso ou de falha antes de retornar uma resposta. Tanto para sucesso quanto para falha, você define uma condição de cardinalidade, na qual o encarregado aguarda a criação de determinado número de variáveis em um prefixo de caminho específico. Após a criação das variáveis, o encarregado será retornado. Em seguida, o código do aplicativo responde ao sucesso ou à falha. Se o estado atual das variáveis já corresponde às condições finais de sucesso ou de falha, o encarregado retorna uma delas imediatamente.

Antes de começar

Como criar um encarregado

Para criar um encarregado:

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

    Por exemplo, o código de amostra a seguir define as condições para sucesso e falha, em que o encarregado retorna 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 encarregado:

    • Somente uma condição de sucesso e uma de falha são permitidas por encarregado.
    • Convém manter um encarregado por caminho.
    • As condições de falha sempre são avaliadas antes das condições de sucesso.
    • Não sobreponha prefixos de caminho entre as condições.

  2. Crie o encarregado.

    Deployment Manager

    Especifique o tipo de encarregado para criá-lo no Deployment Manager:

    runtimeconfig.v1beta1.waiter

    Nas propriedades do encarregado, forneça as condições name, location, timeout e as condições finais do encarregado:

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

    onde:

    • [NAME] é o nome do recurso;
    • [CONFIG_NAME] é o recurso Config desta solicitação;
    • [WAITER_NAME] é o nome deste encarregado;
    • [TIMEOUT_SECS] é o número de segundos a serem aguardados antes de expirar o tempo limite do encarregado, por exemplo, para 300 segundos, use 300s;
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho no qual observar uma condição de sucesso;
    • [SUCCESS_NUMBER] é o número de variáveis que existem nesse caminho para ser considerado bem-sucedido;

    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]

    em que:

    • [WAITER_NAME] é o nome deste encarregado;
    • [CONFIG_NAME] é o recurso RuntimeConfig desta solicitação;
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho no qual observar uma condição de sucesso;
    • [SUCCESS_NUMBER] é o número de variáveis que existem nesse caminho para ser considerado bem-sucedido;

    • [TIMEOUT_SECS] é o número de segundos a serem aguardados antes de expirar o tempo limite do encarregado.

      A CLI gcloud retorna uma resposta como esta:

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

      Após a criação do encarregado, a ferramenta pesquisa o recurso Operations relacionado até o encarregado retornar com uma das respostas aplicáveis.

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

    API

    Na API, faça uma solicitação POST para o seguinte URI:

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

    em que:

    • [PROJECT_ID] é o ID do projeto da solicitação;
    • [CONFIG_NAME] é o nome da configuração desta solicitação;

    O payload da solicitação precisa incluir o nome do encarregado, a condição de sucesso e a duração do tempo limite:

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

    onde:

    • [PROJECT_ID] é o ID do projeto da solicitação;
    • [CONFIG_NAME] é o nome da configuração desta solicitação;
    • [WAITER_NAME] é o nome do encarregado que será criado;
    • [TIMEOUT_SECS] é o número de segundos a serem aguardados antes de expirar o tempo limite do encarregado;
    • [SUCCESS_PATH_PREFIX] é o prefixo do caminho no qual observar uma condição de sucesso;
    • [SUCCESS_NUMBER] é o número de variáveis que existem nesse caminho para ser considerado bem-sucedido;

    Se for bem-sucedido, a solicitação retornará o nome do objeto de operações que você pesquisa para execução:

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

    Em seguida, pesquise o encarregado para verificar periodicamente quando ele é retornado.

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

Pesquisa de encarregado

Após criar um encarregado, pesquise o recurso Operations relacionado para verificar se o encarregado atingiu uma das condições finais. Se o encarregado tiver atendido uma condição final ou tiver expirado, a operação retornará como done e retornará uma resposta com base nos resultados do encarregado.

Use gcloud ou a API para pesquisar um encarregado.

gcloud

Com a Google Cloud CLI, quando você faz uma solicitação para criar um encarregado, a ferramenta executa automaticamente a pesquisa e espera até que o encarregado voltar. Enquanto a ferramenta pesquisa o encarregado, ela imprime a resposta conforme mostrado a seguir:

Waiting for waiter [WAITER_NAME] to finish...

Se você não quiser que a ferramenta pesquise o encarregado depois de criá-lo, forneça a sinalização --async com sua solicitação de criação.

API

Na REST API, faça uma solicitação GET para o seguinte URI para ver o status da operação do encarregado:

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

onde:

  • [PROJECT_ID] é o ID do projeto da solicitação;
  • [CONFIG_NAME] é o nome da configuração desta solicitação;
  • [WAITER_NAME] é o nome do encarregado que será pesquisado.

Se a operação ainda estiver em andamento, a API retornará uma resposta sem status, conforme mostrado a seguir:

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

Se a operação estiver concluída, a operação será marcada como done e retornará uma das respostas descritas na seção Respostas do encarregado.

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

Respostas do encarregado

Condição final de sucesso

Se o encarregado atingiu uma condição final de sucesso, a operação retorna o recurso encarregado:

{
  "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 encarregado atingir a condição final de falha ou o tempo limite, a operação retornará um erro.

Condição de falha atingida

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

Tempo limite do encarregado esgotado

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

Próximas etapas