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 all'attivatore di build. Se non hai dimestichezza con l'utilizzo delle variabili di sostituzione nella configurazione della compilazione, consulta la sezione Sostituisci i valori delle variabili.

Cloud Build ti consente di archiviare parti del payload dell'evento dell'attivatore 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 associazioni e sono disponibili per le build richiamate sia dagli eventi push sia da quelli pull. Le associazioni ti consentono di accedere a dati aggiuntivi correlati alla tua build, ad esempio il linguaggio associato al codice sorgente e l'autore di una richiesta 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 Google Cloud console e in un file di configurazione di Cloud Build. Inoltre, puoi applicare le espansioni dei parametri bash quando esegui build manuali.

Associazioni del payload

Puoi memorizzare parti del payload dell'evento dell'attivatore come valore della variabile di sostituzione. Le associazioni del payload sono disponibili come valori variabili per le build invocate dagli eventi push e pull e possono essere utilizzate per accedere al payload JSON quando il codice sorgente si trova nei repository GitHub o Cloud Source Repositories. Per scoprire di più sui payload degli eventi GitHub, consulta Payload degli eventi webhook. Per scoprire di più sui payload degli eventi per Cloud Source Repositories, consulta Notifiche per Cloud Source Repositories.

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

Prefisso	Origine	Descrizione
push	GitHub	Ti consente di accedere ai campi all'interno del payload JSON per gli eventi push
pull_request	GitHub	Ti consente di accedere ai campi all'interno del payload JSON per gli eventi di richiesta pull
issue_comment	GitHub	Ti consente di accedere ai campi all'interno del payload JSON per gli eventi dei commenti relativi ai problemi associati a una richiesta pull
csr	Cloud Source Repositories	Ti consente di accedere ai campi all'interno del payload JSON per gli eventi push

Nota: puoi anche accedere ai payload utilizzando il prefisso body anziché il prefisso elencato sopra per qualsiasi evento. Ad esempio, puoi utilizzare il prefisso body per accedere al corpo del payload per un evento di attivazione webhook o per un evento Pub/Sub.

Per qualsiasi evento associato all'app GitHub, sono disponibili anche i valori delle variabili predefinite 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 variabili per l'attivatore quando il codice sorgente si trova su GitHub:

Nome variabile	Valore variabile	Descrizione della 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 di richiesta di pull e gli eventi di richiesta di pull bloccati da un commento. Non è necessario precedere questi valori variabili 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 compilazione, fai clic su Crea trigger. In caso contrario, seleziona un attivatore esistente.

3. In Variabili di sostituzione, fai clic su Aggiungi variabile.

4. 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 predefinite.

   • Il numero di parametri è limitato a 100. La lunghezza di una chiave del parametro è limitata a 100 byte e la lunghezza di un valore del parametro è limitata a 4000 byte.

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

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

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

   Nome variabile	Valore variabile	Descrizione della variabile
   _PUSH_NAME	$(push.repository.name)	Recupera il nome del repository associato all'evento push
   _COMMITS	$(push.commits)	Recupera l'array di oggetti commit che descrivono ogni commit sottoposto a push
   _OWNER	$(push.repository.owner.name)	Recupera il nome del proprietario del repository
   _URL	$(push.repository.html_url)	Recupera l'URL del tuo repository GitHub
   _LANGUAGE	$(push.repository.language)	Recupera 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 pull request, utilizza il prefisso pull_request o body. Nell'esempio seguente, il prefisso pull_request nel valore della variabile viene utilizzato come punto di contatto per accedere alle informazioni dal payload JSON della build:

   Nome variabile	Valore variabile	Descrizione della variabile
   _PULL_REQUEST_ID	$(pull_request.pull_request.id)	Recupera l'ID della richiesta di pull
   _PULL_REQUEST_TITLE	$(pull_request.pull_request.title)	Recupera il titolo della richiesta di pull
   _PULL_REQUEST_BODY	$(pull_request.pull_request.body)	Recupera il corpo della richiesta di pull
   _USERNAME	$(pull_request.pull_request.user.login)	Recupera il nome utente del mittente della richiesta pull
   _MERGE_TIME	$(pull_request.pull_request.merged_at)	Recupera 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. Nel seguente esempio, il prefisso commit nel valore della variabile viene utilizzato come punto di contatto per accedere alle informazioni dal payload JSON della build:

   Nome variabile	Valore variabile	Descrizione della variabile
   _COMMIT_URL	$(commit.url)	Recupera l'URL associato al commit
   _COMMIT_USER	$(commit.author.login)	Recupera il nome utente dell'autore del commit
   _COMMIT_MESSAGE	$(commit.commit.message)	Recupera il messaggio di commit associato al commit
   _COMMIT_DATE	$(commit.commit.committer.date)	Recupera 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 Eseguire un commit.

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

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

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

   Nota: se utilizzi body come prefisso, si farà riferimento a issue_comment e non a un evento di una singola richiesta di pull. Per accedere ai campi associati a una singola richiesta di pull, utilizza il prefisso pull_request.

   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 le associazioni 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 contatto per accedere alle informazioni del payload JSON della build.

   Nome variabile	Valore variabile	Descrizione della variabile
   _REPO_NAME	$(csr.name)	Recupera il nome del repository
   _REPO_URL	$(csr.url)	Recupera l'URL del tuo 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.

Nota: puoi utilizzare le associazioni del payload anche nel file di configurazione della build, ma verranno interpretate solo quando la build viene invocata da un attivatore.

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, il taglio di stringhe e l'uso di lettere maiuscole. Ad esempio, potresti voler sostituire una sottostringa in una variabile predefinita e utilizzare la variabile come tag immagine.

Le espansioni dei 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^^}	Mette in maiuscolo tutti i caratteri della stringa
${var,}	Mette in minuscolo il primo carattere della stringa
${var,,}	Mette tutti i caratteri della stringa in minuscolo
${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 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

Nota: ${var:=default} e ${var=default} si comportano in modo simile a ${var:-default} e non assegnano un valore a var se non è già definito.

Puoi anche specificare pattern da associare alle 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 del carattere pattern specificato incluso.
${var##pattern}	Rimuove i caratteri dal lato sinistro di una stringa fino all'istanza più a destra del carattere pattern specificato incluso.
${var%pattern}	Rimuove i caratteri dal lato destro di una stringa fino alla prima istanza del carattere pattern specificato incluso.
${var%%pattern}	Rimuove i caratteri dal lato destro di una stringa fino all'istanza più a sinistra del carattere pattern specificato incluso.

I pattern che puoi specificare includono:

Motivo	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]	Corrisponde a qualsiasi carattere alfanumerico non presente 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 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 compilazione, fai clic su Crea trigger. In caso contrario, seleziona un attivatore esistente.

3. In Variabili di sostituzione, fai clic su Aggiungi variabile.

4. 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 predefinite.

   • Il numero di parametri è limitato a 100. La lunghezza di una chiave del parametro è limitata a 100 byte e la lunghezza di un valore del parametro è limitata a 4000 byte.

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

5. Aggiungi un valore per la variabile applicando un'espansione del parametro 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 incorporata $BRANCH_NAME ha un valore predefinito di Feature_Secret_Project_#v2. La tabella seguente mostra alcuni 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	Mette 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 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	genera il nome dell'immagine utilizzando la variabile _BRANCH_FOR_IMAGE_NAME definita sopra

   Supponiamo che _IMAGE_NAME sia definito nell'attivatore 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. Nel seguente esempio, il valore della variabile specificato per _IMAGE_NAME (my-app-secret-project-prod) sostituisce il valore predefinito di _IMAGE_NAME (test-image) quando viene invocato l'attivatore della compilazione.

   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 compilazione viene invocata da un attivatore, il campo dynamicSubstitutions viene sempre impostato su true e non deve essere specificato nel file di configurazione della compilazione. Se la compilazione viene invocata manualmente, devi impostare il campo dynamicSubstitutions su true affinché le espansioni dei parametri bash vengano interpretate durante l'esecuzione della compilazione.

Utilizzo delle espansioni dei 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 tabella seguente elenca esempi di come puoi utilizzare l'espansione dei parametri bash con le associazioni di payload:

Nome variabile	Valore variabile	Descrizione della variabile
_URL	$(push.repository.html_url)	Recupera 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 del repository in lettere maiuscole
APP_NAME_ID	my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}	Crea un nome dell'applicazione che includa l'URL del repository e i primi sette caratteri dell'ID del payload

Nota: le operazioni nidificate non sono consentite. Ad esempio, non puoi nidificare un'associazione di payload all'interno di un'espansione di parametro bash: ${$(push.repository.html_url)^^}.

Passaggi successivi

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