Como definir e receber dados

Nesta página explicamos como definir, receber e atualizar variáveis usando o Runtime Configurator. Variáveis são pares de chave-valor que pertencem a um recurso RuntimeConfig. Cada um desses pares contém os dados que você define. Após criar uma variável, será possível definir um inspetor ou encarregado nela.

Para saber mais sobre variáveis e o serviço Runtime Configurator, consulte a documentação Fundamentos do Runtime Configurator.

Para saber como criar um recurso RuntimeConfig, consulte Como criar e excluir recursos RuntimeConfig.

Antes de começar

Como criar uma variável

Variável é um par de chave-valor. A chave dela pode ser simples ou hierárquica. Por exemplo, todas as chaves a seguir são válidas:

  • status
  • users/jane-smith/favorite-color
  • users/total

Somente chaves de nó de folha podem ter valores. No exemplo acima, não é possível atribuir um valor para:

  • users
  • users/jane-smith

Isso porque ambas as chaves contêm outras chaves abaixo delas.

Para criar uma variável, use o Deployment Manager, a ferramenta de linha de comando gcloud ou a API.

Deployment Manager

Para criar uma variável no Deployment Manager, especifique o tipo dela:

runtimeconfig.v1beta1.variable

Nas propriedades da variável, forneça name, location e value da variável:

- name: [NAME]
  type: runtimeconfig.v1beta1.variable
  properties:
    parent: $(ref.[CONFIG_NAME].name)
    variable: [VARIABLE_KEY]
    [value | text]: [VARIABLE_VALUE]

onde:

  • [NAME] é o nome do recurso arbitrário desta variável, Esse não é o nome da própria variável.
  • [CONFIG_NAME] é o recurso Config desta solicitação.
  • [VARIABLE_KEY] é a chave da variável. Por exemplo, status e users/jane-smith/favorite_color são chaves válidas. As chaves de variável podem incluir /. Uma chave de variável pode conter dígitos, letras, traços e barras, e o comprimento máximo do nome é 256 caracteres.
  • [VARIABLE_VALUE] é o valor da variável. Dependendo de você querer atribuir um valor como texto simples ou como uma string codificada com base 64, escolha a propriedade value ou text:
    • value: se fornecer um valor como uma string codificada em base64 , use a propriedade value.
    • text: se fornecer uma string de texto simples, use a propriedade text. A string precisa ser UTF-8 válido.

gcloud

Para criar uma variável com a ferramenta de linha de comando gcloud, use o comando runtime-config configs variables set:

gcloud beta runtime-config configs variables set [VARIABLE_KEY] \
    [VARIABLE_VALUE] --config-name [CONFIG_NAME] [--is-text]

onde:

  • [VARIABLE_KEY] é a chave da variável. Por exemplo, status e users/jane-smith/favorite_color são chaves válidas. As chaves de variável podem incluir /. Uma chave de variável pode conter dígitos, letras, traços e barras, e o comprimento máximo do nome é 256 caracteres.
  • [VARIABLE_VALUE] é o valor da variável. É possível atribuir um valor como texto simples ou como string codificada em based64. Se especificar um valor de texto simples, forneça a sinalização --is-text; caso contrário, a ferramenta de linha de comando gcloud codificará o valor na codificação base64.

    gcloud beta runtime-config configs variables set [VARIABLE_KEY] \
          [VARIABLE_VALUE] --config-name [CONFIG_NAME] --is-text
    

    Também é possível fornecer o valor da variável de um arquivo. Por exemplo:

    cat [FILE_NAME] | gcloud beta runtime-config configs variables set [VARIABLE_KEY] --config-name [CONFIG_NAME]
    

    Observação: você não precisa codificar este valor porque o gcloud executará a codificação para você.

  • [CONFIG_NAME] é o nome do recurso RuntimeConfig em que a variável será criada. Por exemplo, frontend-config.

    Exemplo:

    gcloud beta runtime-config configs variables set example-variable \
          my-test-value --config-name example-config
    

    A ferramenta gcloud retorna uma resposta como:

Created [https://runtimeconfig.googleapis.com/v1beta1/projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]].

Por padrão, todas as variáveis atuais são substituídas silenciosamente. Se você quiser preservar uma variável atual, inclua a sinalização --fail-if-present, que cria a nova variável se ela não existir.

Da mesma forma, também é possível falhar a solicitação da variável que estiver ausente fornecendo a sinalização --fail-if-absent.

Para conseguir a referência completa desse comando gcloud, consulte a documentação de referência de runtime-config variables set.

API

Na API REST, faça uma solicitação POST para o seguinte URI para criar uma nova variável:

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

em que [PROJECT_ID] é o ID do projeto dessa solicitação. O payload da solicitação contém o URI para o recurso RuntimeConfig e o valor de texto simples da chave ou o valor codificado em base64:

{
   "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]"
   "[value | text]": "[VARIABLE_VALUE]" # Choose either 'value' or 'text' but not both
}

onde:

  • [PROJECT_ID] é o ID do projeto da solicitação;
  • [CONFIG_NAME] é o nome da configuração;
  • [VARIABLE_KEY] é a chave da variável. Por exemplo, status e users/jane-smith/favorite_color. As chaves de variável podem incluir /. Uma chave de variável pode conter dígitos, letras, traços e barras, e o comprimento máximo do nome é 256 caracteres.
  • [VARIABLE_VALUE] é o valor da variável. Dependendo de você querer atribuir um valor como texto simples ou como uma string codificada com base 64, escolha a propriedade value ou text:

    • value: se fornecer um valor como uma string codificada em base64 , use a propriedade value.
    • text: se fornecer uma string de texto simples, use a propriedade text. A string precisa ser UTF-8 válido.

    Se o procedimento for bem-sucedido, a API retornará uma resposta como:

    {
    "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
    "value": "dGVhbA==",
    "updateTime": "2016-04-11T21:49:00.773366134Z"
    }

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

Como atualizar uma variável

Deployment Manager

Para atualizar uma variável no Deployment Manager:

  1. Defina ou atualize as propriedades da variável conforme descrito em Como criar uma variável.

  2. Siga as etapas para fazer a solicitação de atualização.

gcloud

Atualize a variável usando o mesmo processo realizado para criá-la.

API

Na REST API, faça uma solicitação PUT para o seguinte URI para atualizar a variável:

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

onde:

  • [PROJECT_ID] é o ID do projeto da solicitação;
  • [CONFIG_NAME] é o nome da configuração;
  • [VARIABLE_VALUE] é o valor da variável. Trata-se da string que foi codificada em base64.

O payload da solicitação precisa ser:

{
   "[value | text]": "[VARIABLE_VALUE]" # Choose either 'value' or 'text' but not both
}

em que [VARIABLE_VALUE] é o valor da variável. Dependendo de você querer atribuir um valor como texto simples ou como uma string codificada base64, escolha a propriedade value ou text:

  • value: se fornecer um valor como uma string codificada em base64, use a propriedade value;
  • text: se fornecer uma string de texto simples, use a propriedade text. A string precisa ser válida em UTF-8.

Se o procedimento for bem-sucedido, a API retornará uma resposta como:

{
  "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
  "value": "dGVhbA==",
  "updateTime": "2016-04-11T21:46:11.591713370Z",
  "state": "UPDATED"
}

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

Como receber o valor de uma variável

Deployment Manager

Receba o valor de uma variável usando um destes métodos:

gcloud

Para criar uma variável com a ferramenta de linha de comando gcloud, use o comando runtime-config configs variables get-value:

gcloud beta runtime-config configs variables get-value [VARIABLE_KEY] --config-name [CONFIG_NAME]

onde:

  • [VARIABLE_KEY] é a chave da variável. Por exemplo, status, users/jane-smith/favorite_color.
  • [CONFIG_NAME] é o nome do recurso RuntimeConfig da variável. Por exemplo, website.

    A ferramenta gcloud retorna uma resposta como:

    example-value

Também é possível conseguir uma lista de variáveis para que tem runtimeconfig.variables.get permissão e os valores delas usando o comando list e fornecendo a sinalização --values. Por exemplo:

gcloud beta runtime-config configs variables list --config-name example-config --values

A ferramenta gcloud retorna uma lista como esta:

NAME                         UPDATE_TIME                     VALUE
not-my-favorite-color/shade  2016-04-18T21:14:59.932428461Z  orange
not-my-favorite-food/group   2016-04-18T21:14:59.932428461Z  vegetables

As variáveis para que você não tem permissão get serão omitidas. Isso inclui variáveis em que você tem a permissão list, mas não a permissão get.

Para conseguir a referência completa desse comando gcloud, consulte a documentação de referência do runtime-config variables.

API

Na REST API, faça uma solicitação GET para o seguinte URI para receber o valor da variável:

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

onde:

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

Se o procedimento for bem-sucedido, a API retornará uma resposta com o valor da variável codificado em base64:

{
  "name": "projects/[PROJECT_ID]/configs/[CONFIG_NAME]/variables/[VARIABLE_KEY]",
  "value": "[VARIABLE_VALUE]",
  "updateTime": "2016-04-11T21:49:00.773366134Z"
}

Você mesmo precisa decodificar o valor para receber a string. Para saber mais sobre o método, consulte a documentação do variables().get.

Se você quiser receber uma lista das variáveis para que você tem permissão runtimeconfig.variables.get e os valores dela, use o método returnValues. Por exemplo:

GET uri: https://runtimeconfig.googleapis.com/v1beta1/projects/myproject/configs/example-config/variables?returnValues=True

A API retorna todas as variáveis para as quais você tem permissão:

{
  "variables": [
    {
      "name": "projects/compute-writers-project/configs/example-config/variables/not-my-favorite-color/shade",
      "updateTime": "2016-04-18T21:14:59.932428461Z",
      "value": "b3Jhbmdl"
    }
  ]
}

Da mesma forma, você mesmo precisa decodificar o valor para receber a string.

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

A seguir