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 dei 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 consente di archiviare parti del payload dell'evento del trigger come variabile di sostituzione. Il payload di un evento è il corpo dell'evento che richiama un trigger. Le variabili associate a un payload sono chiamate binding e sono disponibili per le build richiamate da eventi push e pull. I binding ti consentono di accedere a dati aggiuntivi relativi alla tua build, come la lingua associata al codice sorgente e l'autore di una richiesta di pull.

Cloud Build consente inoltre agli utenti di applicare le espansioni dei parametri bash ai valori delle variabili di sostituzione. Le espansioni dei parametri bash ti consentono di manipolare le stringhe associate alle variabili esistenti. Puoi manipolare le stringhe mettendo le lettere in maiuscolo o sostituendo una sottostringa.

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

Associazioni di payload

Puoi memorizzare parti del payload dell'evento del trigger come valore di una variabile di sostituzione. I binding del payload sono disponibili come valori delle variabili per le build richiamate da eventi push e pull e possono essere utilizzati per accedere al payload JSON quando il codice sorgente si trova in repository GitHub o Cloud Source Repositories. Per scoprire di più sui payload degli eventi GitHub, consulta Payload degli eventi webhook. Per saperne di più sui payload degli eventi per Cloud Source Repositories, consulta Notifiche per Cloud Source Repositories.

Puoi accedere alle informazioni da un payload dell'evento utilizzando un prefisso designato, che rappresenta la radice del payload dell'evento. A partire dal prefisso, puoi utilizzare la sintassi JSONPath per accedere al payload ed estrarre i dati. A seconda del tipo di evento, sono disponibili i seguenti prefissi del payload:

Prefisso Origine Descrizione
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 richiesta di pull
issue_comment GitHub Consente di accedere ai campi all'interno del payload JSON per gli eventi di commento 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 gli eventi push e pull in base ai valori delle variabili push.pusher.name, pull_request.pull_request.user.login e issue_comment.comment.user.login. La tabella seguente mostra come includerli come valori delle variabili per il trigger quando il codice sorgente si trova in GitHub:

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

Puoi utilizzare i valori delle variabili is_collaborator e perm_level per gli eventi push, gli eventi richiesta di pull e gli eventi richiesta di pull controllati da un commento. Non devi precedere questi valori di variabile con un prefisso.

Creazione di sostituzioni utilizzando le associazioni di payload

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

  1. Apri la pagina Trigger.

  2. Se non hai creato un trigger di build, fai clic su Crea trigger. In caso contrario, seleziona un trigger esistente.

  3. Nella sezione Variabili di sostituzione, fai clic su Aggiungi variabile.

  4. Aggiungi un nome alla 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 di parametri è limitato a 100. La lunghezza di una chiave parametro è limitata a 100 byte e la lunghezza di un valore parametro è limitata a 4000 byte.

    Per scoprire di più su come definire e utilizzare le sostituzioni definite dall'utente, vedi Utilizzare le sostituzioni definite dall'utente.

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

    Se il codice sorgente si trova in GitHub, puoi fare riferimento alle informazioni nel payload dell'evento all'interno delle variabili di sostituzione utilizzando i binding del 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 accesso per accedere alle informazioni dal payload JSON della build:

    Nome variabile Valore variabile Descrizione variabile
    _PUSH_NAME $(push.repository.name) Ottiene il nome del repository associato all'evento push
    _COMMITS $(push.commits) Ottiene l'array di oggetti commit che descrivono ogni commit eseguito con push
    _OWNER $(push.repository.owner.name) Ottiene il nome del proprietario del repository
    _URL $(push.repository.html_url) Ottiene l'URL del tuo repository GitHub
    _LANGUAGE $(push.repository.language) Ottiene 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 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 accesso per accedere alle informazioni dal payload JSON della build:

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

    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 punto di accesso per accedere alle informazioni dal payload JSON della build:

    Nome variabile Valore variabile Descrizione variabile
    _COMMIT_URL $(commit.url) Ottiene l'URL associato al commit
    _COMMIT_USER $(commit.author.login) Ottiene il nome utente dell'autore del commit
    _COMMIT_MESSAGE $(commit.commit.message) Ottiene il messaggio di commit associato al commit
    _COMMIT_DATE $(commit.commit.committer.date) Ottiene la data associata al commit
    _COMMIT_ADDITIONS $(commit.files['*'].additions) Ottiene 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 attivi il controllo dei commenti per un trigger richiamato da una richiesta pull, l'evento che richiama il trigger è invece un IssueCommentEvent e il prefisso associato è issue_comment. Negli esempi seguenti, il prefisso issue_comment nel valore della variabile viene utilizzato come punto di accesso per accedere alle informazioni dal payload JSON della build:

    Nome variabile Valore variabile Descrizione variabile
    _PULL_REQUEST_ID $(issue_comment.issue.id) Ottiene l'ID della richiesta di pull
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) Ottiene il titolo della richiesta di pull
    _STATE $(issue_comment.state) Ottiene lo stato della richiesta di pull (ad es. aperta, chiusa e così via).
    _LABELS $(issue_comment.issue.labels) Ottiene l'elenco delle etichette associate alla richiesta di pull
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) Ottiene 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 dell'evento all'interno delle variabili di sostituzione utilizzando i binding del 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 accesso per accedere alle informazioni dal payload JSON della build.

    Nome variabile Valore variabile Descrizione variabile
    _REPO_NAME $(csr.name) Ottiene il nome del tuo repository
    _REPO_URL $(csr.url) Ottiene 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 del riferimento (ad es. "refs/heads/primary-branch")

    Per visualizzare altri campi a cui puoi accedere in Cloud Source Repositories, consulta Dati di notifica.

Espansioni dei parametri bash

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

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

Espansioni di Bash Descrizione
${var} Espande il valore della stringa memorizzato in var
${var^} Mette in maiuscolo il primo carattere della stringa
${var^^} Converte in maiuscolo tutti i caratteri della stringa
${var,} Converte in minuscolo il primo carattere della stringa
${var,,} Converte tutti i caratteri della stringa in minuscolo
${var:position} Rimuove i primi position caratteri dalla stringa
${var:position:length} Suddivide 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 occorrenza 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 come default, a meno che var non sia già definito

Puoi anche specificare pattern da abbinare per le seguenti espansioni dei parametri bash:

Espansioni di Bash Descrizione
${var#pattern} Rimuove i caratteri dal lato sinistro di una stringa fino all'istanza più a sinistra di pattern inclusa.
${var##pattern} Rimuove i caratteri dal lato sinistro di una stringa fino all'ultima istanza del pattern specificato inclusa.
${var%pattern} Rimuove i caratteri dal lato destro di una stringa fino alla prima istanza di pattern specificata inclusa.
${var%%pattern} Rimuove i caratteri dal lato destro di una stringa fino all'istanza più a sinistra di pattern specificato inclusa.

I pattern che puoi specificare includono:

Pattern Descrizione
* Corrisponde a zero o più caratteri alfanumerici
? Corrisponde a qualsiasi singolo carattere alfanumerico
[ccc] Corrisponde a qualsiasi singolo carattere in ccc, inclusi gli intervalli tra a-z o 0-9
[^c] Trova qualsiasi carattere alfanumerico non presente in c, inclusa una gamma di caratteri in cui lo <= c <= hi
c Corrisponde a qualsiasi carattere alfanumerico c
\c Corrisponde a qualsiasi carattere c, inclusi i caratteri non alfanumerici come *, ? o \

Applicazione delle espansioni dei parametri bash

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

  1. Apri la pagina Trigger.

  2. Se non hai creato un trigger di build, fai clic su Crea trigger. In caso contrario, seleziona un trigger esistente.

  3. Nella sezione Variabili di sostituzione, fai clic su Aggiungi variabile.

  4. Aggiungi un nome alla 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 di parametri è limitato a 100. La lunghezza di una chiave parametro è limitata a 100 byte e la lunghezza di un valore parametro è limitata a 4000 byte.

    Per scoprire di più su come definire e utilizzare le sostituzioni definite dall'utente, vedi Utilizzare le sostituzioni definite dall'utente.

  5. 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 tabella seguente mostra esempi di espansioni dei parametri bash che puoi applicare a $BRANCH_NAME:

    Nome variabile Espansione di Bash Valore variabile Descrizione
    _BRANCH_LOWERCASE ${$BRANCH_NAME,,} feature_secret_project_#v2 converte tutti i caratteri della stringa in minuscolo
    _BRANCH_NO_SUFFIX ${_BRANCH_LOWERCASE%_\#v2} feature_secret_project elimina tutti i caratteri dal lato destro della stringa che corrispondono al pattern specificato
    _BRANCH_NO_PREFIX ${_BRANCH_NO_SUFFIX#*_} secret_project elimina tutti i caratteri fino al primo carattere di sottolineatura
    _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 costruisce il nome dell'immagine utilizzando la variabile _BRANCH_FOR_IMAGE_NAME definita sopra

    Supponiamo che _IMAGE_NAME sia definito nel trigger come il 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 l'interpretazione delle espansioni dei parametri bash. Se la 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 di parametri bash con le associazioni di payload

Puoi applicare le espansioni dei parametri bash alle variabili associate alle associazioni di payload creando una nuova variabile per fare riferimento alla variabile contenente l'associazione o concatenando le associazioni con le espansioni dei parametri bash. La seguente tabella elenca esempi di come puoi utilizzare l'espansione dei parametri bash con le associazioni di payload:

Nome variabile Valore variabile Descrizione variabile
_URL $(push.repository.html_url) Ottiene l'URL del repository
_URL_CAPITAL ${_URL^^} Utilizza un'espansione di parametri bash per mettere in maiuscolo 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 dell'applicazione che include l'URL del repository e i primi sette caratteri dell'ID payload

Passaggi successivi