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

Questa pagina spiega come utilizzare associazioni di payload e applicare il parametro bash espansioni alle variabili di sostituzione associate al trigger di build. Se non hai dimestichezza con l'utilizzo delle variabili di sostituzione nella configurazione della compilazione, consulta la sezione Sostituzioni dei 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 relative alla build, ad esempio il linguaggio associato 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 usare associazioni di payload e applicare espansioni dei parametri bash quando si definisce o si aggiorna un trigger di build nella console Google Cloud 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 sostituzione valore della variabile. Le associazioni di payload sono disponibili come valori di variabili per le build richiamati da eventi push e pull e possono essere utilizzati 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 payload sono disponibili in base al tipo di evento:

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	Ti consente di accedere ai campi all'interno del tuo payload JSON per gli eventi dei commenti relativi ai problemi associati a una richiesta pull
csr	Cloud Source Repositories	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, i valori delle variabili integrate Sono disponibili anche is_collaborator e perm_level. Lo stato dell'utente viene controllata per gli 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 seguente tabella mostra come includerli come valori variabili per si attiva quando il codice sorgente si trova in GitHub:

Nome variabile	Valore variabile	Descrizione delle variabili
_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 delle variabili is_collaborator e perm_level per gli eventi push, eventi di richiesta di pull e eventi di richiesta di pull gestiti 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 del payload:

1. Apri la pagina Attivatori.

2. Se non hai creato un trigger di compilazione, fai clic su Crea trigger. Altrimenti, seleziona un trigger esistente.

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

4. Aggiungi un nome per la variabile seguendo la convenzione delineata. descritti di seguito:

   • Le sostituzioni devono iniziare con un trattino basso (_) e usare 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 del parametro è limitata a 100 byte e la lunghezza di un valore del parametro è limitata a 4000 byte.

   Per saperne di più su come definire e utilizzare sostituzioni definite dall'utente, consulta Utilizzo di 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 contenute nel tuo payload degli eventi all'interno delle variabili di sostituzione, utilizzando 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 un entry point per accedere alle informazioni dal payload JSON della tua 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)	Ottieni l'array di oggetti di commit che descrive ogni commit eseguito tramite push
   _OWNER	$(push.repository.owner.name)	Ottieni il nome del proprietario del repository
   _URL	$(push.repository.html_url)	Ottieni 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 di richiesta pull, 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 delle variabili
   _PULL_REQUEST_ID	$(pull_request.pull_request.id)	Recupera l'ID della richiesta di estrazione
   _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)	Consente di ottenere la data e 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. Nel seguente esempio, il prefisso commit nel valore della variabile viene utilizzato come punto di contatto per accedere alle informazioni del payload JSON della build:

   Nome variabile	Valore variabile	Descrizione delle variabili
   _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)	Consente di ottenere 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 invocato da una richiesta pull, l'evento che lo attiva è 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 accedi alle informazioni dal payload JSON della tua build:

   Nome variabile	Valore variabile	Descrizione delle variabili
   _PULL_REQUEST_ID	$(issue_comment.issue.id)	Recupera l'ID della richiesta di estrazione
   _PULL_REQUEST_TITLE	$(issue_comment.issue.title)	Restituisce 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)	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.

   Nota: se utilizzi body come prefisso, si riferirà a issue_comment e non 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 a le informazioni nel payload dell'evento all'interno delle variabili di sostituzione utilizzando 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 e le 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)	Ottieni 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 i Dati delle notifiche.

Nota: puoi anche utilizzare associazioni di payload nel file di configurazione della build, ma Essere interpretata solo quando la build viene richiamata da un trigger.

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 delle stringhe e l'uso delle maiuscole. Ad esempio, potresti vuoi 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 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 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 a includere l'istanza più a sinistra dell'elemento pattern specificato
${var##pattern}	Rimuove i caratteri dal lato sinistro di una stringa fino a includere l'istanza più a destra del valore pattern specificato
${var%pattern}	Rimuove i caratteri dal lato destro di una stringa fino all'inclusione della prima istanza del valore pattern specificato
${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:

Sequenza	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 compresi tra a-z o 0-9
[^c]	Corrisponde a qualsiasi carattere alfanumerico non in c compreso un intervallo di caratteri dove 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 le espansioni di un parametro bash a un elemento integrato o definito dall'utente variabile di sostituzione:

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 delineata. descritti di seguito:

   • Le sostituzioni devono iniziare con un trattino basso (_) e usare 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 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	tutti i caratteri minuscoli nella 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	genera il nome dell'immagine utilizzando la variabile _BRANCH_FOR_IMAGE_NAME definita sopra

   Supponiamo che _IMAGE_NAME sia definito nell'attivatore come valore specificato nel riportata sopra, my-app-secret-project-prod. Questo valore sostituirà qualsiasi definizione di _IMAGE_NAME nel file di configurazione della build. Nella 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 riportato sopra, consente le espansioni dei parametri bash da interpretare. 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 build viene invocata 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 le associazioni di payload

Puoi applicare le espansioni dei parametri bash alle variabili associate associazioni di payload creando una nuova variabile che faccia riferimento contenente l'associazione o l'unione delle associazioni con bash espansioni dei parametri. Nella tabella seguente sono elencati alcuni esempi. puoi utilizzare l'espansione dei parametri bash con associazioni di payload:

Nome variabile	Valore variabile	Descrizione delle variabili
_URL	$(push.repository.html_url)	Ottieni l'URL del repository
_URL_CAPITAL	${_URL^^}	Utilizza un'espansione del parametro bash per inserire le lettere maiuscole di tutti i caratteri nell'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 include l'URL del repository e i primi sette caratteri dell'ID del payload

Nota: le operazioni nidificate non sono consentite. Ad esempio, non è possibile nidificare un payload associazione all'interno di un'espansione del 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.