Utilizzo delle associazioni di payload e delle espansioni di parametri bash nelle sostituzioni

Questa pagina spiega come utilizzare le associazioni di payload e applicare le espansioni di parametri bash alle variabili di sostituzione associate al trigger di build. Se non hai familiarità con l'utilizzo delle variabili di sostituzione nella configurazione della build, consulta Sostituzione dei valori delle variabili.

Cloud Build ti consente di archiviare parti del payload dell'evento del trigger come variabile di sostituzione. Un payload evento è il corpo dell'evento che chiama un trigger. Le variabili associate a un payload sono dette associazioni e sono disponibili per le build richiamate da eventi sia push che pull. Le associazioni consentono di accedere a dati aggiuntivi relativi alla build, ad esempio la lingua associata al codice sorgente e l'autore di una richiesta di pull.

Cloud Build consente inoltre agli utenti di applicare espansioni dei parametri bash ai valori delle variabili di sostituzione. Le espansioni dei parametri Bash consentono di manipolare le stringhe associate alle variabili. Puoi manipolare le stringhe utilizzando le lettere maiuscole o sostituendo una sottostringa.

Puoi utilizzare associazioni di payload e applicare espansioni dei parametri bash quando definisci o aggiorni un trigger di build nella console Google Cloud e in un file di configurazione di Cloud Build. Inoltre, puoi applicare le espansioni dei parametri bash quando esegui build manuali.

Associazioni di payload

Puoi archiviare parti del payload degli eventi del trigger come valore di una variabile di sostituzione. Le associazioni di payload sono disponibili come valori variabili per le build richiamate da eventi push e pull e possono essere utilizzate per accedere al payload JSON quando il codice sorgente si trova in repository GitHub o Cloud Source Repositories. Per scoprire di più sui payload di eventi GitHub, vedi Payload eventi webhook. Per scoprire di più sui payload di eventi per Cloud Source Repositories, consulta Notifiche per Cloud Source Repositories.

Puoi accedere alle informazioni di un payload di eventi utilizzando un prefisso designato, che rappresenta la radice del payload di eventi. Partendo dal prefisso, puoi utilizzare la sintassi JSONPath per accedere al payload ed eseguire il pull dei dati da quest'ultimo. A seconda del tipo di evento sono disponibili i seguenti prefissi del payload:

Prefisso	Origine	Description
`push`	GitHub	Consente di accedere ai campi all'interno del payload JSON per gli eventi push
`pull_request`	GitHub	Consente di accedere ai campi all'interno del payload JSON per gli eventi di richieste di pull
`issue_comment`	GitHub	Consente di accedere ai campi all'interno del payload JSON per gli eventi di commento relativi ai problemi associati a una richiesta di pull
`csr`	Cloud Source Repositories	Consente di accedere ai campi all'interno del payload JSON per gli eventi push

Per qualsiasi evento associato all'app GitHub, sono disponibili anche i valori delle variabili integrate is_collaborator e perm_level. Lo stato dell'utente viene controllato per rilevare eventi push e pull in base ai valori della variabile push.pusher.name, pull_request.pull_request.user.login e issue_comment.comment.user.login. La tabella seguente mostra come includere questi valori come valori di variabili per il tuo trigger quando il codice sorgente è in GitHub:

Nome variabile	Valore variabile	Descrizione della variabile
`_PERM_LEVEL`	`$(perm_level)`	Consente di ottenere il livello di autorizzazione dell'utente
`_IS_COLLABORATOR`	`$(is_collaborator)`	Restituisce `true` se l'utente è un collaboratore

Puoi utilizzare i valori della variabile is_collaborator e perm_level per eventi push, eventi di richiesta pull ed eventi di richiesta di pull controllati da un commento. Non è necessario anteporre un prefisso ai valori di queste variabili.

Creazione di sostituzioni utilizzando associazioni di payload

Per creare una variabile di sostituzione che utilizzi un'associazione di payload:

Apri la pagina Attivatori.
Se non hai creato un trigger di build, fai clic su Crea trigger. Altrimenti, seleziona un trigger esistente.
In Variabili di sostituzione, fai clic su Aggiungi variabile.
Aggiungi un nome per la Variabile seguendo la convenzione descritta di seguito:
- Le sostituzioni devono iniziare con un trattino basso (_) e utilizzare solo lettere maiuscole e numeri (rispettando l'espressione regolare [A-Z0-9_]+). In questo modo si evitano conflitti con le sostituzioni integrate.
- Il numero massimo di parametri è 100. La lunghezza di una chiave parametro è limitata a 100 byte, mentre la lunghezza di un valore parametro è limitata a 4000 byte.
Per scoprire di più su come definire e utilizzare le sostituzioni definite dall'utente, consulta Utilizzo delle sostituzioni definite dall'utente.

Aggiungi un valore per la variabile, utilizzando un prefisso supportato.

Se il codice sorgente è in GitHub, puoi fare riferimento alle informazioni nel payload dell'evento all'interno delle variabili di sostituzione che utilizzano le associazioni di payload. Per accedere al payload JSON di un evento push, utilizza il prefisso push o body. Nell'esempio seguente, il prefisso push nel valore della variabile viene utilizzato come punto di ingresso per accedere alle informazioni dal payload JSON della build:

Nome variabile	Valore variabile	Descrizione della variabile
`_PUSH_NAME`	`$(push.repository.name)`	Restituisce il nome del repository associato all'evento push
`_COMMITS`	`$(push.commits)`	Ottieni l'array di oggetti commit che descrivono ogni commit push
`_OWNER`	`$(push.repository.owner.name)`	Ottieni il nome del proprietario del repository
`_URL`	`$(push.repository.html_url)`	Consente di ottenere l'URL del repository GitHub
`_LANGUAGE`	`$(push.repository.language)`	Consente di ottenere la lingua del codice sorgente incluso nel push

Per un elenco dei campi a cui puoi accedere utilizzando il prefisso push, consulta PushEvent.

Per accedere al payload JSON di un evento di richiesta di pull, utilizza il prefisso pull_request o body. Nell'esempio seguente, il prefisso pull_request nel valore della variabile viene utilizzato come punto di ingresso per accedere alle informazioni dal payload JSON della build:

Nome variabile	Valore variabile	Descrizione della variabile
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	Consente di ottenere l'ID della richiesta di pull
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	Consente di ottenere il titolo della richiesta di pull
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	Consente di ottenere il corpo della richiesta di pull
`_USERNAME`	`$(pull_request.pull_request.user.login)`	Si ottiene il nome utente del mittente della richiesta di pull
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	Ottieni l'ora in cui la richiesta di pull è stata unita

Per un elenco dei campi a cui puoi accedere utilizzando il prefisso pull_request, consulta PullRequestEvent.

Per accedere al payload JSON di un evento di commit, utilizza il prefisso commit. Nell'esempio seguente, il prefisso commit nel valore della variabile viene utilizzato come entrypoint per accedere alle informazioni dal payload JSON della build:

Nome variabile	Valore variabile	Descrizione della variabile
`_COMMIT_URL`	`$(commit.url)`	Ottieni l'URL associato al commit
`_COMMIT_USER`	`$(commit.author.login)`	Ottieni il nome utente dell'autore del commit
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	Consente di ottenere il messaggio di commit associato al commit
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	Consente di ottenere la data associata all'impegno
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	Restituisce il numero di aggiunte associate ai file nel commit

Per un elenco dei campi a cui puoi accedere utilizzando il prefisso commit, consulta Ottenere un commit.

Se abiliti il controllo dei commenti per un trigger richiamato da una richiesta di pull, l'evento che richiama il trigger è invece un IssueCommentEvent e il prefisso associato è issue_comment. Nei seguenti esempi, il prefisso issue_comment nel valore della variabile viene utilizzato come punto di ingresso per accedere alle informazioni dal payload JSON della build:

Nome variabile	Valore variabile	Descrizione della variabile
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	Consente di ottenere l'ID della richiesta di pull
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	Consente di ottenere il titolo della richiesta di pull
`_STATE`	`$(issue_comment.state)`	Consente di ottenere lo stato della richiesta di pull (ad esempio aperta, chiusa e così via)
`_LABELS`	`$(issue_comment.issue.labels)`	Consente di ottenere l'elenco delle etichette associate alla richiesta di pull
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	Consente di ottenere l'URL associato all'etichetta corrispondente alla descrizione

Per un elenco dei campi a cui puoi accedere utilizzando il prefisso issue_comment, consulta IssueCommentEvent.

Se il codice sorgente si trova in Cloud Source Repositories, puoi fare riferimento alle informazioni nel payload degli eventi all'interno delle variabili di sostituzione che utilizzano le associazioni di payload. Per accedere al payload JSON da un evento push, utilizza il prefisso csr o body. Nell'esempio seguente, il prefisso csr nel valore della variabile viene utilizzato come punto di ingresso per accedere alle informazioni dal payload JSON della build.

Nome variabile	Valore variabile	Descrizione della variabile
`_REPO_NAME`	`$(csr.name)`	Consente di ottenere il nome del repository
`_REPO_URL`	`$(csr.url)`	Consente di ottenere l'URL del repository
`_CREATED_REPO`	`$(csr.createRepoEvent)`	Indica se un utente ha creato un repository
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	Il nome dell'riferimento (ad es. "refs/heads/primary-branch")

Per visualizzare i campi aggiuntivi a cui puoi accedere in Cloud Source Repositories, vedi Dati delle notifiche.

Espansioni del parametro Bash

Puoi applicare le espansioni dei parametri bash alle variabili predefinite e alle variabili definite dall'utente. Esempi di operazioni supportate sono la sostituzione di sottostringhe, lo slicing delle stringhe e l'uso delle lettere maiuscole. Ad esempio, potresti voler sostituire una sottostringa in una variabile predefinita e aggiungerla come tag immagine.

Le espansioni dei parametri bash che puoi specificare per le variabili di sostituzione sono le seguenti:

Espansioni barra	Description
`${var}`	Espande il valore di stringa memorizzato in `var`
`${var^}`	Scrivi in maiuscolo il primo carattere della stringa
`${var^^}`	Scrivi in maiuscolo tutti i caratteri della stringa
`${var,}`	Scrivi in minuscolo il primo carattere della stringa
`${var,,}`	Scrivi in minuscolo tutti i caratteri nella stringa
`${var:position}`	Rimuove i primi `position` caratteri dalla stringa
`${var:position:length}`	Taglia la stringa a partire dal valore numerico specificato in `position` e include fino al valore numerico specificato in `length`
`${var/substring/replacement}`	Sostituisce l'istanza più a sinistra del valore specificato in `substring` con il valore specificato in `replacement`
`${var//substring/replacement}`	Sostituisce tutte le istanze del valore specificato in `substring` con il valore specificato in `replacement`
`${var/#substring/replacement}`	Sostituisce la prima istanza del valore specificato in `substring` con il valore specificato in `replacement` solo se `substring` è un prefisso di `var`
`${var/%substring/replacement}`	Sostituisce l'ultima istanza del valore specificato in `substring` con il valore specificato in `replacement` solo se `substring` è un suffisso di `var`
`${#var}`	Recupera la lunghezza della stringa
`${var:-default}`	Valuta `var` in `default` a meno che `var` non sia già definito

Puoi anche specificare pattern da trovare per le seguenti espansioni di parametri bash:

Espansioni barra	Description
`${var#pattern}`	Rimuove i caratteri dal lato sinistro di una stringa fino all'istanza più a sinistra dell'elemento `pattern` specificato
`${var##pattern}`	Rimuove i caratteri dal lato sinistro di una stringa fino all'istanza più a destra dell'elemento `pattern` specificato
`${var%pattern}`	Rimuove i caratteri dal lato destro di una stringa fino alla prima istanza del valore `pattern` specificato
`${var%%pattern}`	Rimuove i caratteri dal lato destro di una stringa fino all'istanza più a sinistra dell'elemento `pattern` specificato

I pattern che puoi specificare includono:

Sequenza	Description
`*`	Corrisponde a zero o più caratteri alfanumerici
`?`	Corrisponde a qualsiasi carattere alfanumerico
`[ccc]`	Corrisponde a qualsiasi carattere singolo in `ccc`, inclusi gli intervalli compresi tra `a-z` e `0-9`
`[^c]`	Corrisponde a qualsiasi carattere alfanumerico non incluso in `c`, incluso un intervallo di caratteri in cui `lo` <= `c` <= `hi`
`c`	Corrisponde a qualsiasi carattere alfanumerico `c`
`\c`	Corrisponde a qualsiasi carattere `c`, inclusi caratteri non alfanumerici come `*`, `?` o `\`

Applicazione delle espansioni dei parametri bash

Per applicare l'espansione dei parametri bash a una variabile di sostituzione integrata o definita dall'utente:

Apri la pagina Attivatori.
Se non hai creato un trigger di build, fai clic su Crea trigger. Altrimenti, seleziona un trigger esistente.
In Variabili di sostituzione, fai clic su Aggiungi variabile.
Aggiungi un nome per la Variabile seguendo la convenzione descritta di seguito:
- Le sostituzioni devono iniziare con un trattino basso (_) e utilizzare solo lettere maiuscole e numeri (rispettando l'espressione regolare [A-Z0-9_]+). In questo modo si evitano conflitti con le sostituzioni integrate.
- Il numero massimo di parametri è 100. La lunghezza di una chiave parametro è limitata a 100 byte, mentre la lunghezza di un valore parametro è limitata a 4000 byte.
Per scoprire di più su come definire e utilizzare le sostituzioni definite dall'utente, consulta Utilizzo delle sostituzioni definite dall'utente.

Aggiungi un valore per la variabile, applicando un'espansione dei parametri bash supportata a una variabile di sostituzione integrata o a un'altra variabile di sostituzione definita dall'utente.

Nell'esempio seguente, la variabile di sostituzione integrata $BRANCH_NAME ha un valore predefinito di Feature_Secret_Project_#v2. La seguente tabella mostra alcuni esempi di espansioni dei parametri bash che puoi applicare a $BRANCH_NAME:

Nome variabile	Espansione barra	Valore variabile	Description
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	minuscolo tutti i caratteri della stringa
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	elimina tutti i caratteri dal lato destro della stringa corrispondenti al pattern specificato
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	elimina tutti i caratteri fino al primo trattino basso
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	sostituisce tutti i trattini bassi con un trattino
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	crea un nome per l'immagine utilizzando la variabile `_BRANCH_FOR_IMAGE_NAME` definita sopra

Supponiamo che _IMAGE_NAME sia definito nell'attivatore come valore specificato nella tabella precedente, my-app-secret-project-prod. Questo valore ora sostituirà qualsiasi definizione di _IMAGE_NAME nel file di configurazione della build. Nell'esempio seguente, il valore della variabile specificato per _IMAGE_NAME (my-app-secret-project-prod) sostituisce il valore predefinito di _IMAGE_NAME (test-image) quando viene richiamato il trigger di build.

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

Il campo dynamicSubstitutions, impostato su true nell'esempio precedente, consente di interpretare le espansioni dei parametri bash. Se la tua build viene richiamata da un trigger, il campo dynamicSubstitutions è sempre impostato su true e non deve essere specificato nel file di configurazione della build. Se la build viene richiamata manualmente, devi impostare il campo dynamicSubstitutions su true affinché le espansioni dei parametri Bash vengano interpretate durante l'esecuzione della build.

Utilizzo delle espansioni dei parametri bash con associazioni di payload

Puoi applicare le espansioni dei parametri bash alle variabili associate alle associazioni di payload creando una nuova variabile che faccia riferimento alla variabile contenente l'associazione oppure unendo insieme le associazioni con le espansioni dei parametri bash. La seguente tabella elenca alcuni esempi di come utilizzare l'espansione dei parametri bash con associazioni di payload:

Nome variabile	Valore variabile	Descrizione della variabile
`_URL`	`$(push.repository.html_url)`	Consente di ottenere l'URL del repository
`_URL_CAPITAL`	`${_URL^^}`	Utilizza un'espansione del parametro bash per utilizzare l'iniziale maiuscola per tutti i caratteri dell'URL.
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	Aggiunge un prefisso all'URL in maiuscolo del repository
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	Crea un nome di applicazione che includa l'URL del repository e i primi sette caratteri dell'ID payload

Passaggi successivi

Scopri come sostituire i valori delle variabili.
Scopri come creare un file di configurazione di compilazione di base.
Scopri come creare e gestire i trigger di build.
Scopri come eseguire le build manualmente.