Esta página foi traduzida pela API Cloud Translation.

Como usar vinculações de payload e expansões de parâmetros bash em substituições

Esta página explica como usar vinculações de payload e aplicar expansões de parâmetro bash a variáveis de substituição associadas ao gatilho de compilação. Se você não estiver familiarizado com o uso de variáveis de substituição na configuração da compilação, consulte Como substituir valores de variáveis.

O Cloud Build permite armazenar partes do payload do evento do gatilho como uma variável de substituição. Um payload de evento é o corpo do evento que invoca um gatilho. As variáveis associadas a um payload são chamadas de vinculações e estão disponíveis para builds invocados por eventos de push e pull. As vinculações permitem acessar dados adicionais relacionados ao build, como a linguagem associada ao código-fonte e o autor de uma solicitação de envio.

O Cloud Build também permite que os usuários apliquem expansões de parâmetros bash a valores de variáveis de substituição. As expansões do parâmetro Bash permitem manipular strings associadas a variáveis existentes. É possível manipular strings com letras maiúsculas ou substituir uma substring.

É possível usar vinculações de payload e aplicar expansões de parâmetros bash ao definir ou atualizar um gatilho de build no Google Cloud console e em um arquivo de configuração do Cloud Build. Além disso, você pode aplicar expansões de parâmetros bash ao executar builds manuais.

Vinculações de payload

É possível armazenar partes do payload do evento do gatilho como um valor de variável de substituição. As vinculações de payload estão disponíveis como valores variáveis para builds invocados por eventos push e pull e podem ser usados para acessar o payload JSON quando o código-fonte está nos repositórios do GitHub ou no Cloud Source Repositories. Para saber mais sobre payloads de evento do GitHub, consulte Payloads de evento de webhook. Para saber mais sobre os payloads de eventos do Cloud Source Repositories, consulte Notificações do Cloud Source Repositories.

Você pode acessar informações de um payload de evento usando um prefixo designado, que representa a raiz do payload do evento. Começando com o prefixo, você pode usar a sintaxe JSONPath para acessar o payload e extrair dados dele. Os seguintes prefixos de payload estão disponíveis dependendo do seu tipo de evento:

Prefixo	Origem	Descrição
`push`	GitHub	Permite acessar campos no payload JSON para eventos de push.
`pull_request`	GitHub	Permite que você acesse campos dentro de seu payload JSON para eventos de solicitação de envio
`issue_comment`	GitHub	Permite acessar campos no payload JSON para emitir eventos de comentário associados a uma solicitação de envio
`csr`	Cloud Source Repositories	Permite acessar campos no payload JSON para eventos de push.

Para qualquer evento associado ao aplicativo GitHub, os valores integrados de builds is_collaborator e perm_level também estão disponíveis. O status do usuário é verificado para eventos push e pull pelos valores de variável push.pusher.name, pull_request.pull_request.user.login e issue_comment.comment.user.login. A tabela a seguir mostra como incluí-los como valores de variável do gatilho quando o código-fonte está no GitHub:

Nome da variável	Valor da variável	Descrição da variável
`_PERM_LEVEL`	`$(perm_level)`	Recebe o nível de permissão do usuário
`_IS_COLLABORATOR`	`$(is_collaborator)`	Gera `true` se o usuário for um colaborador

Você pode usar os valores de variável is_collaborator e perm_level para eventos push, eventos de solicitação de envio e eventos de solicitação de envio controlados por um comentário. Você não precisa preceder esses valores de variável com um prefixo.

Como criar substituições usando vinculações de payload

Para criar uma variável de substituição que usa uma vinculação de payload:

Abrir a página Gatilhos
Se você não tiver criado um gatilho de versão, clique em Criar gatilho. Caso contrário, selecione um gatilho existente.
Em variáveis de substituição, clique em Adicionar variável.
Adicione um nome para a variável seguindo a convenção descrita abaixo:
- É obrigatório que as substituições comecem com um sublinhado (_) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular [A-Z0-9_]+). Isso evita conflitos com substituições integradas.
- O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.
Para mais informações sobre como definir e usar substituições definidas pelo usuário, consulte Como usar substituições definidas pelo usuário.

Adicione um valor para sua variável, usando um prefixo compatível.

Se o código-fonte estiver no GitHub, é possível consultar informações no payload de evento dentro de variáveis de substituição usando vinculações de payload. Para acessar o payload JSON de um evento de push, use o prefixo push ou body. No exemplo abaixo, o prefixo push no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

Nome da variável	Valor da variável	Descrição da variável
`_PUSH_NAME`	`$(push.repository.name)`	Recebe o nome do repositório associado ao evento push
`_COMMITS`	`$(push.commits)`	Recebe a matriz de objetos de confirmação que descrevem cada confirmação enviada
`_OWNER`	`$(push.repository.owner.name)`	Recebe o nome do proprietário do repositório.
`_URL`	`$(push.repository.html_url)`	Recebe o URL do repositório do GitHub
`_LANGUAGE`	`$(push.repository.language)`	Recebe o idioma do código-fonte incluído no push.

Para uma lista de campos que você pode acessar usando o prefixo push, consulte PushEvent.

Para acessar o payload JSON de um evento de solicitação de envio, use o prefixo pull_request ou body. No exemplo a seguir, o prefixo pull_request no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

Nome da variável	Valor da variável	Descrição da variável
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	Recebe o ID da solicitação de envio
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	Recebe o título da solicitação de envio
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	Recebe o corpo da solicitação de envio
`_USERNAME`	`$(pull_request.pull_request.user.login)`	Recebe o nome de usuário do remetente da solicitação de envio
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	Recebe o horário em que a solicitação de envio foi mesclada

Para uma lista de campos que você pode acessar usando o prefixo pull_request, consulte PullRequestEvent.

Para acessar o payload JSON de um evento de confirmação, use o prefixo commit. No exemplo a seguir, o prefixo commit no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

Nome da variável	Valor da variável	Descrição da variável
`_COMMIT_URL`	`$(commit.url)`	Obtém o URL associado à confirmação
`_COMMIT_USER`	`$(commit.author.login)`	Obtém o nome de usuário do autor da confirmação
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	Recebe a mensagem de confirmação associada à confirmação.
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	Obtém a data associada à confirmação
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	Obtém o número de adições associadas a arquivos na confirmação

Para uma lista de campos que podem ser acessados usando o prefixo commit, consulte Receber uma confirmação.

Se você ativar Controle de comentários para um gatilho que é invocado por uma solicitação de envio, o evento que invoca o gatilho é um IssueCommentEvent e o prefixo associado é issue_comment. Nos exemplos a seguir, o prefixo issue_comment no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão:

Nome da variável	Valor da variável	Descrição da variável
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	Recebe o ID da solicitação de envio
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	Recebe o título da solicitação de envio
`_STATE`	`$(issue_comment.state)`	Recebe o estado da solicitação de envio (ou seja, aberto, fechado etc.)
`_LABELS`	`$(issue_comment.issue.labels)`	Recebe a lista de rótulos associados à solicitação de envio
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	Recebe o URL associado ao rótulo correspondente à descrição

Para uma lista de campos que você pode acessar usando o prefixo issue_comment, consulte IssueCommentEvent.

Se o código-fonte estiver no Cloud Source Repositories, é possível consultar informações no payload do evento dentro de variáveis de substituição usando vinculações de payload. Para acessar o payload JSON de um evento de push, use o prefixo csr ou body. No exemplo a seguir, o prefixo csr no valor da variável é usado como um ponto de entrada para acessar informações do payload JSON da sua versão.

Nome da variável	Valor da variável	Descrição da variável
`_REPO_NAME`	`$(csr.name)`	Recebe o nome do seu repositório
`_REPO_URL`	`$(csr.url)`	Recebe o URL do seu repositório
`_CREATED_REPO`	`$(csr.createRepoEvent)`	Indica se um usuário criou um repositório.
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	O nome da referência, como "refs/heads/primary-branch"

Para ver campos adicionais que você pode acessar no Cloud Source Repositories, consulte Dados de notificação.

Expansões de parâmetros Bash

É possível aplicar expansões de parâmetro bash a variáveis padrão e variáveis definidas pelo usuário. Exemplos de operações compatíveis incluem substituição de substring, fração de strings e capitalização. Por exemplo, é possível substituir uma substring em uma variável padrão e usar a variável como uma tag de imagem.

As expansões do parâmetro bash que você pode especificar para variáveis de substituição são as seguintes:

Expansões de intervalo	Descrição
`${var}`	Expande o valor da string armazenado em `var`
`${var^}`	Coloca em letra maiúscula a primeira letra do primeiro caractere na string
`${var^^}`	Coloca em letra maiúscula todos os caracteres na string
`${var,}`	Coloca em letra minúscula o primeiro caractere da string
`${var,,}`	Coloca em letra minúscula todos os caracteres da string
`${var:position}`	Remove os primeiros `position` caracteres da string
`${var:position:length}`	Corta a string a partir do valor numérico especificado em `position` e inclui até o valor numérico especificado em `length`
`${var/substring/replacement}`	Substitui a instância mais à esquerda do valor especificado em `substring` pelo valor especificado em `replacement`
`${var//substring/replacement}`	Substitui todas as instâncias do valor especificado em `substring` pelo valor especificado em `replacement`
`${var/#substring/replacement}`	Substitui a primeira instância do valor especificado em `substring` pelo valor especificado em `replacement` somente se `substring` for um prefixo de `var`
`${var/%substring/replacement}`	Substitui a última instância do valor especificado em `substring` pelo valor especificado em `replacement` somente se `substring` for um sufixo de `var`
`${#var}`	Recupera o comprimento da string
`${var:-default}`	Avalia `var` como `default`, a menos que `var` já esteja definido

Também é possível especificar padrões para corresponder às seguintes expansões de parâmetro bash:

Expansões de intervalo	Descrição
`${var#pattern}`	Remove os caracteres do lado esquerdo de uma string até e incluindo a instância mais à esquerda do `pattern` especificado
`${var##pattern}`	Remove os caracteres do lado esquerdo de uma string até e incluindo a instância mais à direita do `pattern` especificado
`${var%pattern}`	Remove os caracteres do lado direito de uma string até e incluindo a primeira instância do `pattern` especificado
`${var%%pattern}`	Remove os caracteres do lado direito de uma string até incluir a instância mais à esquerda de `pattern` especificado

Os padrões que você pode especificar incluem:

Padrão	Descrição
`*`	Corresponde a zero ou mais caracteres alfanuméricos
`?`	Corresponde a qualquer caractere alfanumérico único
`[ccc]`	Corresponde a qualquer caractere em `ccc`, incluindo intervalos entre `a-z` e `0-9`
`[^c]`	Corresponde a qualquer caractere alfanumérico que não está em `c`, incluindo um intervalo de caracteres em que `lo` <= `c` <= `hi`
`c`	Corresponde a qualquer caractere alfanumérico `c`
`\c`	Corresponde a qualquer caractere `c`, incluindo caracteres não alfanuméricos, como `*`, `?` ou `\`

Como aplicar expansões de parâmetros bash

Para aplicar expansões de parâmetros bash a uma variável de substituição integrada ou definida pelo usuário:

Abrir a página Gatilhos
Se você não tiver criado um gatilho de versão, clique em Criar gatilho. Caso contrário, selecione um gatilho existente.
Em variáveis de substituição, clique em Adicionar variável.
Adicione um nome para a variável seguindo a convenção descrita abaixo:
- É obrigatório que as substituições comecem com um sublinhado (_) e que sejam usadas somente letras maiúsculas e números (respeitando a expressão regular [A-Z0-9_]+). Isso evita conflitos com substituições integradas.
- O número de parâmetros é limitado a 100. O comprimento de uma chave de parâmetro é limitado a 100 bytes e o comprimento de um valor de parâmetro é limitado a 4000 bytes.
Para mais informações sobre como definir e usar substituições definidas pelo usuário, consulte Como usar substituições definidas pelo usuário.

Adicione um valor à variável, aplicando uma expansão de parâmetros bash compatível a uma variável de substituição integrada ou a outra variável de substituição definida pelo usuário.

No exemplo a seguir, a variável de substituição integrada $BRANCH_NAME tem um valor padrão de Feature_Secret_Project_#v2. A tabela a seguir mostra exemplos de expansões de parâmetros bash que você pode aplicar a $BRANCH_NAME:

Nome da variável	Expansão bash	Valor da variável	Descrição
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	Coloca em letra minúscula todos os caracteres na string
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	Exclui todos os caracteres do lado direito da string que corresponde ao padrão especificado
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	exclui todos os caracteres até o primeiro sublinhado
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	substitui todos os sublinhados por um traço;
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	constrói o nome da imagem usando a variável `_BRANCH_FOR_IMAGE_NAME` definida acima

Digamos que _IMAGE_NAME seja definido no seu gatilho como o valor especificado na tabela acima, my-app-secret-project-prod. Esse valor agora substituirá qualquer definição de _IMAGE_NAME no arquivo de configuração da compilação. No exemplo a seguir, o valor da variável especificada para _IMAGE_NAME (my-app-secret-project-prod) substitui o valor padrão de _IMAGE_NAME (test-image) quando o gatilho de compilação é invocado.

YAML

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

JSON

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

O campo dynamicSubstitutions, definido como true no exemplo acima, permite que as expansões de parâmetros bash sejam interpretadas. Se o build for invocado por um gatilho, o campo dynamicSubstitutions será sempre definido como true e não precisará ser especificado no arquivo de configuração da compilação. Caso sua versão seja invocada manualmente, defina o campo dynamicSubstitutions como true para que as expansões de parâmetro bash sejam interpretadas ao executar a versão.

Como usar expansões de parâmetros bash com vinculações de payload

É possível aplicar expansões de parâmetros bash a variáveis associadas a vinculações de payload ao criar uma nova variável para fazer referência à variável que contém a vinculação ou ao vincular vinculações com expansões de parâmetro bash. A tabela a seguir lista exemplos de como usar a expansão de parâmetro bash com vinculações de payload:

Nome da variável	Valor da variável	Descrição da variável
`_URL`	`$(push.repository.html_url)`	Recebe o URL do repositório
`_URL_CAPITAL`	`${_URL^^}`	Usa uma expansão de parâmetro bash para colocar todos os caracteres do URL em maiúsculas.
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	Adiciona um prefixo ao URL em letras maiúsculas do repositório
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	Cria um nome de aplicativo que inclui o URL do repositório e os sete primeiros caracteres do ID do payload.

A seguir

Saiba como substituir valores variáveis.
Saiba como criar um arquivo de configuração de compilação básico.
Saiba como criar e gerenciar gatilhos de compilação.
Saiba como executar builds manualmente.