Substituir valores de variáveis

Use substitutions no ficheiro de configuração de compilação para substituir variáveis específicas no momento da compilação.

As substituições são úteis para variáveis cujo valor não é conhecido até ao momento da compilação ou para reutilizar um pedido de compilação existente com valores de variáveis diferentes.

O Cloud Build oferece substituições incorporadas ou pode definir as suas próprias substituições. Use substitutions no steps da compilação e no images para resolver os respetivos valores no momento da compilação.

Esta página explica como usar substituições predefinidas ou definir as suas próprias substitutions.

Usar substituições predefinidas

O Cloud Build fornece as seguintes substituições predefinidas para todas as compilações:

  • $PROJECT_ID: ID do seu projeto do Google Cloud
  • $BUILD_ID: ID da sua compilação
  • $PROJECT_NUMBER: o número do seu projeto
  • $LOCATION: a região associada à sua compilação

O Cloud Build fornece as seguintes substituições predefinidas para compilações invocadas por acionadores:

  • $TRIGGER_NAME: o nome associado ao acionador
  • $COMMIT_SHA: o ID de confirmação associado à sua compilação
  • $REVISION_ID: o ID de confirmação associado à sua compilação
  • $SHORT_SHA : os primeiros sete carateres de COMMIT_SHA
  • $REPO_NAME: o nome do seu repositório
  • $REPO_FULL_NAME: o nome completo do seu repositório, incluindo o utilizador ou a organização
  • $BRANCH_NAME: o nome da sua filial
  • $TAG_NAME: o nome da sua etiqueta
  • $REF_NAME: o nome da sua ramificação ou etiqueta
  • $TRIGGER_BUILD_CONFIG_PATH: o caminho para o ficheiro de configuração de compilação usado durante a execução da compilação; caso contrário, uma string vazia se a compilação estiver configurada inline no acionador ou usar um Dockerfile ou um Buildpack.
  • $SERVICE_ACCOUNT_EMAIL: email da conta de serviço que está a usar para a compilação. Esta é uma conta de serviço predefinida ou uma conta de serviço especificada pelo utilizador.
  • $SERVICE_ACCOUNT: o nome do recurso da conta de serviço, no formato projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL

O Cloud Build fornece as seguintes substituições predefinidas específicas do GitHub disponíveis para acionadores de pedidos de obtenção:

  • $_HEAD_BRANCH : ramo principal do pedido de envio
  • $_BASE_BRANCH : ramo base do pedido de envio
  • $_HEAD_REPO_URL : URL do repositório principal do pedido de obtenção
  • $_PR_NUMBER : número do pedido de envio

Se não estiver disponível uma substituição predefinida (como com compilações sem origem ou com compilações que usam a origem de armazenamento), as ocorrências da variável em falta são substituídas por uma string vazia.

Quando inicia uma compilação com gcloud builds submit, pode especificar variáveis que normalmente provêm de compilações acionadas com o argumento --substitutions. Especificamente, pode fornecer manualmente valores para:

  • $TRIGGER_NAME
  • $COMMIT_SHA
  • $REVISION_ID
  • $SHORT_SHA
  • $REPO_NAME
  • $REPO_FULL_NAME
  • $BRANCH_NAME
  • $TAG_NAME
  • $REF_NAME
  • $TRIGGER_BUILD_CONFIG_PATH
  • $SERVICE_ACCOUNT_EMAIL
  • $SERVICE_ACCOUNT

Por exemplo, o comando seguinte usa a substituição TAG_NAME:

gcloud builds submit --config=cloudbuild.yaml \
    --substitutions=TAG_NAME="test"

O exemplo seguinte usa as substituições predefinidas $BUILD_ID, $PROJECT_ID, $PROJECT_NUMBER e $REVISION_ID.

YAML 

steps:
# Uses the ubuntu build step:
# to run a shell script; and
# set env variables for its execution
- name: 'ubuntu'
  args: ['bash', './myscript.sh']
  env:
  - 'BUILD=$BUILD_ID'
  - 'PROJECT_ID=$PROJECT_ID'
  - 'PROJECT_NUMBER=$PROJECT_NUMBER'
  - 'REV=$REVISION_ID'

# Uses the docker build step to build an image called my-image
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/my-image', '.']

# my-image is pushed to Container Registry
images:
- 'gcr.io/$PROJECT_ID/my-image'

JSON 

{
  "steps": [{
      "name": "ubuntu",
      "args": [
        "bash",
        "./myscript.sh"
      ],
      "env": [
        "BUILD=$BUILD_ID",
        "PROJECT_ID=$PROJECT_ID",
        "PROJECT_NUMBER=$PROJECT_NUMBER",
        "REV=$REVISION_ID"
      ]
    }, {
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/my-image", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/my-image"
  ]
}

O exemplo abaixo mostra um pedido de compilação que usa o passo de compilação docker para compilar uma imagem e, em seguida, envia a imagem para o Container Registry usando a substituição $PROJECT_ID predefinida:

Neste exemplo:

  • O pedido de compilação tem um passo de compilação, que usa o passo de compilação docker em gcr.io/cloud-builders para compilar a imagem do Docker.
    • O campo args no passo especifica os argumentos a transmitir para o comando docker. Neste caso, build -t gcr.io/my-project/cb-demo-img . é invocado (depois de $PROJECT_ID ser substituído pelo ID do seu projeto).

  • O campo images contém o nome da imagem. Se a compilação for bem-sucedida, a imagem resultante é enviada para o Container Registry. Se a imagem não for criada com êxito pela compilação, a compilação falha.

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
images:
- gcr.io/$PROJECT_ID/cb-demo-img

JSON

{
  "steps": [{
      "name": "gcr.io/cloud-builders/docker",
      "args": ["build", "-t", "gcr.io/$PROJECT_ID/cb-demo-img", "."]
    }],
  "images": [
    "gcr.io/$PROJECT_ID/cb-demo-img"
  ]
}

Usar substituições definidas pelo utilizador

Também pode definir as suas próprias substituições. As substituições definidas pelo utilizador têm de estar em conformidade com as seguintes regras:

  • As substituições têm de começar por um caráter de sublinhado (_) e usar apenas letras maiúsculas e números (respeitando a expressão regular _[A-Z0-9_]+). Isto evita conflitos com substituições incorporadas. Para usar uma expressão que comece por $, tem de usar $$. Thus:
    • $FOO is invalid since it is not a built-in substitution.
    • $$FOO, que é avaliada como a string literal $FOO.
  • O número de parâmetros está limitado a 200. O comprimento de uma chave de parâmetro está limitado a 100 bytes e o comprimento de um valor de parâmetro está limitado a 4000 bytes.

    • Pode especificar variáveis de duas formas: $_FOO ou ${_FOO}:

    • Ambas as expressões $_FOO e ${_FOO} são avaliadas como o valor de _FOO. No entanto, ${} permite que a substituição funcione sem espaços circundantes, o que permite substituições como ${_FOO}BAR.
    • $$ allows you to include a literal $ in the template. Thus:
      • $_FOO evaluates to the value of _FOO.
      • $$_FOO avalia a string literal $_FOO.
      • $$$_FOO avalia a string literal $ seguida do valor de _FOO.

      Para usar as substituições, use o --substitutionsargumento no comando gcloud ou especifique-os no ficheiro de configuração.

      O exemplo seguinte mostra uma configuração de compilação com duas substituições definidas pelo utilizador denominadas _NODE_VERSION_1 e _NODE_VERSION_2:

      YAML 

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_1}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
         '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build',
         '--build-arg',
         'node_version=${_NODE_VERSION_2}',
         '-t',
         'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}',
         '.']
substitutions:
    _NODE_VERSION_1: v6.9.1 # default value
    _NODE_VERSION_2: v6.9.2 # default value
images: [
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}',
    'gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}'
]

      JSON 

      {
    "steps": [{
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_1}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
            "."
        ]
    }, {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "--build-arg",
            "node_version=${_NODE_VERSION_2}",
            "-t",
            "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}",
            "."
        ]
    }],
    "substitutions": {
        "_NODE_VERSION_1": "v6.9.1"
        "_NODE_VERSION_1": "v6.9.2"
    },
    "images": [
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_1}",
        "gcr.io/$PROJECT_ID/build-substitutions-nodejs-${_NODE_VERSION_2}"
    ]
}

      Para substituir o valor de substituição especificado no ficheiro de configuração de compilação, use a flag --substitutions no comando gcloud builds submit. Tenha em atenção que as substituições são um mapeamento de variáveis para valores e não para matrizes ou sequências. Pode substituir os valores das variáveis de substituição predefinidas, exceto para $PROJECT_ID e $BUILD_ID. O comando seguinte substitui o valor predefinido de _NODE_VERSION_1 especificado no ficheiro de configuração de compilação acima:

      gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_NODE_VERSION_1="v6.9.4",_NODE_VERSION_2="v6.9.5" .

      Por predefinição, a compilação devolve um erro se houver uma variável de substituição em falta ou uma substituição em falta. No entanto, pode definir a opção ALLOW_LOOSE para ignorar esta verificação.

      O fragmento seguinte imprime "hello world" e define uma substituição não utilizada. Uma vez que a opção de substituição ALLOW_LOOSE está definida, a compilação vai ser bem-sucedida apesar da substituição em falta.

      YAML 

      steps:
- name: 'ubuntu'
  args: ['echo', 'hello world']
substitutions:
    _SUB_VALUE: unused
options:
    substitutionOption: 'ALLOW_LOOSE'

      JSON 

      {
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "unused"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

      Se a sua compilação for invocada por um acionador, a opção ALLOW_LOOSE é definida por predefinição. Neste caso, a compilação não devolve um erro se houver uma variável de substituição em falta ou uma substituição em falta. Não pode substituir a opção ALLOW_LOOSE para compilações invocadas por acionadores.

      Se a opção ALLOW_LOOSE não for especificada, as chaves não correspondentes no mapeamento de substituições ou no pedido de compilação resultam num erro. Por exemplo, se o pedido de compilação incluir $_FOO e o mapeamento de substituições não definir _FOO, recebe um erro após executar a compilação ou invocar um acionador se o acionador incluir variáveis de substituição.

      As seguintes variáveis de substituição contêm sempre um valor de string vazio predefinido, mesmo que não defina a opção ALLOW_LOOSE:

      • $REPO_NAME
      • $REPO_FULL_NAME
      • $BRANCH_NAME
      • $TAG_NAME
      • $COMMIT_SHA
      • $SHORT_SHA

      Quando define uma variável de substituição, não está limitado a strings estáticas. Também tem acesso à carga útil do evento que invocou o seu acionador. Estes estão disponíveis como associações de carga útil. Também pode aplicar expansões de parâmetros bash em variáveis de substituição e armazenar a string resultante como uma nova variável de substituição. Para saber mais, consulte o artigo Usar associações de carga útil e expansões de parâmetros bash em substituições.

      Substituições dinâmicas

      Pode fazer referência ao valor de outra variável numa substituição definida pelo utilizador definindo a opção dynamicSubstitutions como true no ficheiro de configuração de compilação. Se a sua compilação for invocada por um acionador, o campo dynamicSubstitutions é sempre definido como true e não precisa de ser especificado no ficheiro de configuração da compilação. Se a compilação for invocada manualmente, tem de definir o campo dynamicSubstitutions como true para que as expansões de parâmetros bash sejam interpretadas quando executar a compilação.

      O ficheiro de configuração de compilação seguinte mostra a variável de substituição ${_IMAGE_NAME} que faz referência à variável ${PROJECT_ID}. O campo dynamicSubstitutions está definido como true, pelo que a referência é aplicada quando invoca uma compilação manualmente:

      YAML 

      steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '${_IMAGE_NAME}', '.']
substitutions:
    _IMAGE_NAME: 'gcr.io/${PROJECT_ID}/test-image'
options:
    dynamicSubstitutions: true

      JSON 

      {
   "steps": [
      {
         "name": "gcr.io/cloud-builders/docker",
         "args": [
            "build",
            "-t",
            "${_IMAGE_NAME}",
            "."
         ]
      }
   ],
   "substitutions": {
      "_IMAGE_NAME": "gcr.io/${PROJECT_ID}/test-image"
   },
   "options": {
      "dynamic_substitutions": true
   }
}

      Para mais informações, consulte o artigo Aplicar expansões de parâmetros bash.

      Mapeamento de substituições para variáveis de ambiente

      Os scripts não suportam diretamente substituições, mas suportam variáveis de ambiente. Pode mapear substituições para variáveis de ambiente, quer automaticamente de uma só vez, quer manualmente definindo cada variável de ambiente por si.

      Mapeie substituições automaticamente

      • Ao nível da criação. Para mapear automaticamente todas as substituições para variáveis de ambiente, que vão estar disponíveis durante toda a compilação, defina automapSubstitutions como true como opção ao nível da compilação. Por exemplo, o ficheiro de configuração de compilação seguinte mostra a substituição $_USER definida pelo utilizador e a substituição $PROJECT_ID predefinida mapeadas para variáveis de ambiente:

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'"
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }
}

      • Ao nível do passo. Para mapear automaticamente todas as substituições e torná-las disponíveis como variáveis de ambiente num único passo, defina o campo automapSubstitutions como true nesse passo. No exemplo seguinte, apenas o segundo passo mostra as substituições corretamente, porque é o único com o mapeamento de substituições automáticas ativado:

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": true
    }
  ],
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

        Além disso, pode disponibilizar as substituições como variáveis de ambiente em toda a compilação e, em seguida, ignorá-las num passo. Defina automapSubstitutions como true ao nível da compilação e, em seguida, defina o mesmo campo como false no passo em que quer ignorar as substituições. No exemplo seguinte, embora as substituições de mapeamento estejam ativadas ao nível da compilação, o ID do projeto não é impresso no segundo passo, porque automapSubstitutions está definido como false nesse passo:

        YAML 

        steps:
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Hello $_USER"
- name: 'ubuntu'
  script: |
    #!/usr/bin/env bash
    echo "Your project ID is $PROJECT_ID"
  automapSubstitutions: false
options:
  automapSubstitutions: true
substitutions:
  _USER: "Google Cloud"

        JSON 

        {
  "steps": [
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Hello $_USER'"
    },
    {
      "name": "ubuntu",
      "script": "#!/usr/bin/env bash echo 'Your project ID is $PROJECT_ID'",
      "automap_substitutions": false
    }
  ],
  "options": {
    "automap_substitutions": true
  },
  },
  "substitutions": {
    "_USER": "Google Cloud"
  }

      Mapeie substituições manualmente

      Pode mapear manualmente as substituições para variáveis de ambiente. Todas as variáveis de ambiente são definidas ao nível do passo através do campo env, e o âmbito das variáveis está restrito ao passo onde são definidas. Este campo recebe uma lista de chaves e valores.

      O exemplo seguinte mostra como mapear a substituição $PROJECT_ID para a variável de ambiente BAR:

      YAML 

      steps:
- name: 'ubuntu'
  env:
  - 'BAR=$PROJECT_ID'
  script: 'echo $BAR'

      JSON 

      {
  "steps": [
    {
      "name": "ubuntu",
      "env": [
        "BAR=$PROJECT_ID"
      ],
      "script": "echo $BAR"
    }
  ]
}

      O que se segue?