Usar associações de payload e expansões de parâmetros bash em substituições

Esta página explica como usar associações de carga útil e aplicar expansões de parâmetros bash a variáveis de substituição associadas ao seu acionador de compilação. Se não souber como usar variáveis de substituição na configuração de compilação, consulte o artigo Substituir valores de variáveis.

O Cloud Build permite-lhe armazenar partes da carga útil do evento do seu acionador como uma variável de substituição. Uma carga útil de evento é o corpo do evento que invoca um acionador. As variáveis associadas a uma carga útil são denominadas associações e estão disponíveis para compilações invocadas por eventos push e pull. As associações permitem-lhe aceder a dados adicionais relacionados com a sua compilação, como o idioma associado ao seu código fonte e o autor de um pedido de obtenção.

O Cloud Build também permite que os utilizadores apliquem expansões de parâmetros bash aos valores das variáveis de substituição. As expansões de parâmetros do Bash permitem-lhe manipular strings associadas a variáveis existentes. Pode manipular strings colocando letras em maiúsculas ou substituindo uma substring.

Pode usar associações de carga útil e aplicar expansões de parâmetros do bash quando define ou atualiza um acionador de compilação na Google Cloud consola e numficheiro de configuração do Cloud Build. Além disso, pode aplicar expansões de parâmetros bash quando executa compilações manuais.

Associações de payloads

Pode armazenar partes da carga útil do evento do acionador como um valor de variável de substituição. As associações de carga útil estão disponíveis como valores de variáveis para compilações invocadas por eventos push e pull, e podem ser usadas para aceder à carga útil JSON quando o código fonte está em repositórios do GitHub ou Cloud Source Repositories. Para saber mais sobre os payloads de eventos do GitHub, consulte o artigo Payloads de eventos de webhook. Para saber mais sobre os payloads de eventos para o Cloud Source Repositories, consulte o artigo Notificações para o Cloud Source Repositories.

Pode aceder a informações de um payload de evento através de um prefixo designado, que representa a raiz do payload de evento. Começando pelo prefixo, pode usar a sintaxe JSONPath para aceder à carga útil e extrair dados da mesma. Os seguintes prefixos de payload estão disponíveis consoante o tipo de evento:

Prefixo	Fonte	Descrição
push	GitHub	Permite-lhe aceder a campos no payload JSON para eventos push
pull_request	GitHub	Permite-lhe aceder a campos no payload JSON para eventos de pedido de obtenção
issue_comment	GitHub	Permite-lhe aceder a campos no payload JSON para eventos de comentários de problemas associados a um pedido de envio
csr	Cloud Source Repositories	Permite-lhe aceder a campos no payload JSON para eventos push

Nota: também pode aceder a payloads através do prefixo body em vez do prefixo indicado acima para qualquer evento. Por exemplo, pode usar o prefixo body para aceder ao corpo do payload de um evento de acionador de webhook ou de um evento do Pub/Sub.

Para qualquer evento associado à app GitHub, os valores das variáveis incorporadas is_collaborator e perm_level também estão disponíveis. O estado do utilizador é verificado para eventos push e pull pelos valores das variáveis push.pusher.name, pull_request.pull_request.user.login e issue_comment.comment.user.login. A tabela seguinte mostra como incluir estes elementos como valores de variáveis para o acionador 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)	Obtém o nível de autorização do utilizador
_IS_COLLABORATOR	$(is_collaborator)	Produz true se o utilizador for um colaborador

Pode usar os valores das variáveis is_collaborator e perm_level para eventos push, eventos de pedido de obtenção e eventos de pedido de obtenção restritos por um comentário. Não tem de preceder estes valores variáveis com um prefixo.

Criar substituições através de associações de payload

Para criar uma variável de substituição que use uma associação de payload:

1. Abra a página Acionadores.

2. Se não tiver criado um acionador de compilação, clique em Criar acionador. Caso contrário, selecione um acionador existente.

3. Em Variáveis de substituição, clique em Adicionar variável.

4. Adicione um nome à sua variável seguindo a convenção descrita abaixo:

   • As substituições têm de começar com 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.

   • O número de parâmetros está limitado a 100. 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.

   Para saber como definir e usar substituições definidas pelo utilizador, consulte o artigo Usar substituições definidas pelo utilizador.

5. Adicione um valor à variável, usando um prefixo compatível.

   Se o seu código fonte estiver no GitHub, pode consultar informações no payload de eventos nas variáveis de substituição através de associações de payloads. Para aceder ao payload JSON de um evento push, use o prefixo push ou body. No exemplo seguinte, o prefixo push no valor da variável é usado como um ponto de entrada para aceder a informações do payload JSON da sua compilação:

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

   Para ver uma lista dos campos aos quais pode aceder através do prefixo push, consulte PushEvent.

   Para aceder ao payload JSON de um evento de pedido de obtenção, use o prefixo pull_request ou body. No exemplo seguinte, o pull_requestprefixo no valor da variável é usado como um ponto de entrada para aceder a informações do payload JSON da sua compilação:

   Nome da variável	Valor da variável	Descrição da variável
   _PULL_REQUEST_ID	$(pull_request.pull_request.id)	Obtém o ID do pedido de envio
   _PULL_REQUEST_TITLE	$(pull_request.pull_request.title)	Obtém o título do pedido de envio
   _PULL_REQUEST_BODY	$(pull_request.pull_request.body)	Obtém o corpo do pedido de envio
   _USERNAME	$(pull_request.pull_request.user.login)	Obtém o nome de utilizador do remetente do pedido de obtenção
   _MERGE_TIME	$(pull_request.pull_request.merged_at)	Obtém a hora em que o pedido de envio foi unido

   Para ver uma lista dos campos aos quais pode aceder através do prefixo pull_request, consulte PullRequestEvent.

   Para aceder ao payload JSON de um evento de confirmação, use o prefixo commit. No exemplo seguinte, o prefixo commit no valor da variável é usado como um ponto de entrada para aceder a informações do payload JSON da sua compilaçã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 utilizador do autor da confirmação
   _COMMIT_MESSAGE	$(commit.commit.message)	Obtém 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 ficheiros na confirmação

   Para ver uma lista dos campos aos quais pode aceder através do prefixo commit, consulte o artigo Obtenha uma confirmação.

   Se ativar o Controlo de comentários para um acionador invocado por um pedido de obtenção, o evento que invoca o acionador é, em alternativa, um IssueCommentEvent e o prefixo associado é issue_comment. Nos exemplos seguintes, o prefixo issue_comment no valor da variável é usado como um ponto de entrada para aceder a informações do payload JSON da sua compilação:

   Nome da variável	Valor da variável	Descrição da variável
   _PULL_REQUEST_ID	$(issue_comment.issue.id)	Obtém o ID do pedido de envio
   _PULL_REQUEST_TITLE	$(issue_comment.issue.title)	Obtém o título do pedido de envio
   _STATE	$(issue_comment.state)	Obtém o estado do pedido de envio (ou seja, aberto, fechado, etc.)
   _LABELS	$(issue_comment.issue.labels)	Obtém a lista de etiquetas associadas ao pedido de obtenção
   _LABELS_URL	$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)	Obtém o URL associado à etiqueta que corresponde à descrição

   Para ver uma lista dos campos aos quais pode aceder através do prefixo issue_comment, consulte IssueCommentEvent.

   Nota: se usar body como prefixo, isto refere-se a issue_comment e não a um evento de pedido de obtenção único. Para aceder a campos associados a um único pedido de obtenção, use o prefixo pull_request.

   Se o seu código-fonte estiver nos repositórios de origem na nuvem, pode consultar as informações na carga útil do evento em variáveis de substituição através de associações de carga útil. Para aceder ao payload JSON a partir de um evento push, use o prefixo csr ou body. No exemplo seguinte, o prefixo csr no valor da variável é usado como um ponto de entrada para aceder a informações do payload JSON da sua compilação.

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

   Para ver campos adicionais aos quais pode aceder nos Cloud Source Repositories, consulte Dados de notificação.

Nota: também pode usar associações de carga útil no ficheiro de configuração de compilação, mas só são interpretadas quando a compilação é invocada por um acionador.

Expansões de parâmetros do Bash

Pode aplicar expansões de parâmetros bash a variáveis predefinidas e variáveis definidas pelo utilizador. Exemplos de operações suportadas incluem a substituição de substrings, a divisão de strings e a utilização de maiúsculas. Por exemplo, pode querer substituir uma substring numa variável predefinida e usar a variável como uma etiqueta de imagem.

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

Expansões do Bash	Descrição
${var}	Expande o valor da string armazenado em var
${var^}	Coloca em maiúscula o primeiro caráter na string
${var^^}	Aplica maiúsculas a todos os carateres na string
${var,}	Põe o primeiro caráter da string em minúsculas
${var,,}	Converte todos os carateres na string em minúsculas
${var:position}	Remove os primeiros position carateres da string
${var:position:length}	Divide a string a partir do valor numérico especificado em position e inclui até ao 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 apenas 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 apenas se substring for um sufixo de var
${#var}	Obtém o comprimento da string
${var:-default}	Avalia var como default, a menos que var já esteja definido

Nota: ${var:=default} e ${var=default} comportam-se de forma semelhante a ${var:-default} e não atribuem um valor a var se ainda não estiver definido.

Também pode especificar padrões para correspondência com as seguintes expansões de parâmetros do bash:

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

Os padrões que pode especificar incluem:

Padrão	Descrição
*	Corresponde a zero ou mais carateres alfanuméricos
?	Corresponde a qualquer caráter alfanumérico individual
[ccc]	Corresponde a qualquer caráter individual em ccc, incluindo intervalos entre a-z ou 0-9
[^c]	Corresponde a qualquer caráter alfanumérico não em c, incluindo um intervalo de carateres em que lo <= c <= hi
c	Corresponde a qualquer caráter alfanumérico c
\c	Corresponde a qualquer caráter c, incluindo carateres não alfanuméricos, como *, ? ou \

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 utilizador:

1. Abra a página Acionadores.

2. Se não tiver criado um acionador de compilação, clique em Criar acionador. Caso contrário, selecione um acionador existente.

3. Em Variáveis de substituição, clique em Adicionar variável.

4. Adicione um nome à sua variável seguindo a convenção descrita abaixo:

   • As substituições têm de começar com 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.

   • O número de parâmetros está limitado a 100. 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.

   Para saber como definir e usar substituições definidas pelo utilizador, consulte o artigo Usar substituições definidas pelo utilizador.

5. Adicione um valor para a sua variável, aplicando uma expansão de parâmetros bash suportada a uma variável de substituição incorporada ou a outra variável de substituição definida pelo utilizador.

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

   Nome da variável	Expansão do Bash	Valor da variável	Descrição
   _BRANCH_LOWERCASE	${$BRANCH_NAME,,}	feature_secret_project_#v2	Converte todos os carateres na string em minúsculas
   _BRANCH_NO_SUFFIX	${_BRANCH_LOWERCASE%_\#v2}	feature_secret_project	elimina todos os carateres do lado direito da string que correspondem ao padrão especificado
   _BRANCH_NO_PREFIX	${_BRANCH_NO_SUFFIX#*_}	secret_project	Elimina todos os carateres até ao 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

   Supondo que _IMAGE_NAME está definido no seu acionador como o valor especificado na tabela acima, my-app-secret-project-prod. Este valor vai substituir qualquer definição de _IMAGE_NAME no ficheiro de configuração de compilação. No exemplo seguinte, o valor da variável especificado para _IMAGE_NAME (my-app-secret-project-prod) substitui o valor predefinido de _IMAGE_NAME (test-image) quando o acionador 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 do bash sejam interpretadas. Se a sua compilação for invocada por um acionador, o campo dynamicSubstitutions é sempre definido como true e não tem 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 do bash sejam interpretadas quando executar a compilação.

Usar expansões de parâmetros bash com associações de carga útil

Pode aplicar expansões de parâmetros bash a variáveis associadas a associações de payloads criando uma nova variável para referenciar a variável que contém a associação ou juntando associações com expansões de parâmetros bash. A tabela seguinte apresenta exemplos de como pode usar a expansão de parâmetros do bash com associações de payload:

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

Nota: não são permitidas operações aninhadas. Por exemplo, não pode aninhar uma associação de carga útil numa expansão de parâmetros bash: ${$(push.repository.html_url)^^}.

O que se segue?

• Saiba como substituir valores de variáveis.
• Saiba como criar um ficheiro de configuração de compilação básico.
• Saiba como criar e gerir acionadores de compilação.
• Saiba como executar compilações manualmente.