Nutzlastbindungen und Bash-Parametererweiterungen in Ersetzungen verwenden

Auf dieser Seite wird erläutert, wie Sie Nutzlastbindungen verwenden und Erweiterungen von Bash-Parametern auf Substitutionsvariablen anwenden, die Ihrem Build-Trigger zugeordnet sind. Wenn Sie nicht mit der Verwendung von Substitutionsvariablen in Ihrer Build-Konfiguration vertraut sind, lesen Sie den Abschnitt Variablenwerte ersetzen.

Mit Cloud Build können Sie Teile der Ereignisnutzlast des Triggers als Substitutionsvariable speichern. Die Ereignisnutzlast ist der Text des Ereignisses, der einen Trigger aufruft. Mit einer Nutzlast verknüpfte Variablen werden als Bindungen bezeichnet und sind für Builds verfügbar, die durch Push- und Pull-Ereignisse aufgerufen werden. Mit Bindungen können Sie auf zusätzliche Daten zu Ihrem Build zugreifen, z. B. die mit Ihrem Quellcode verknüpfte Sprache und den Autor einer Pull-Anfrage.

Mit Cloud Build können Nutzer auch Bash-Parametererweiterungen auf Werte von Substitutionsvariablen anwenden. Mit Bash-Parametererweiterungen können Sie Strings bearbeiten, die mit vorhandenen Variablen verknüpft sind. Sie können Strings bearbeiten, indem Sie Großbuchstaben verwenden oder einen Teilstring ersetzen.

Sie können Nutzlastbindungen und Bash-Parametererweiterungen verwenden, wenn Sie einen Build-Trigger in der Google Cloud Console und in einer Cloud Build-Konfigurationsdatei definieren oder aktualisieren. Außerdem können Sie beim Ausführen von manuellen Builds Bash-Parametererweiterungen anwenden.

Nutzlastbindungen

Sie können Teile der Ereignisnutzlast als Wert der Ersatzvariable speichern. Nutzlastbindungen sind als Variablenwerte für Builds verfügbar, die durch Push- und Pull-Ereignisse aufgerufen werden. Sie können verwendet werden, um auf die JSON-Nutzlast zuzugreifen, wenn sich Ihr Quellcode in GitHub-Repositories oder Cloud Source Repositories befindet. Weitere Informationen zu den Nutzlasten von GitHub-Ereignissen finden Sie unter Webhook-Ereignisnutzlasten. Weitere Informationen zu den Ereignisnutzlasten für Cloud Source Repositories finden Sie unter Benachrichtigungen für Cloud Source Repositories.

Sie können mit einem festgelegten Präfix auf Informationen aus einer Ereignisnutzlast zugreifen, die den Stamm der Ereignisnutzlast darstellt. Ab dem Präfix können Sie mit der JSONPath-Syntax auf die Nutzlast zugreifen und Daten daraus abrufen. Die folgenden Nutzlastpräfixe sind je nach Ereignistyp verfügbar:

Präfix	Quelle	Beschreibung
`push`	GitHub	Ermöglicht den Zugriff auf Felder in Ihrer JSON-Nutzlast für Push-Ereignisse.
`pull_request`	GitHub	Ermöglicht den Zugriff auf Felder in Ihrer JSON-Nutzlast für Pull-Anfrageereignisse
`issue_comment`	GitHub	Ermöglicht den Zugriff auf Felder in Ihrer JSON-Nutzlast für Problemkommentare, die einer Pull-Anfrage zugeordnet sind
`csr`	Cloud Quell-Repositories	Ermöglicht den Zugriff auf Felder in Ihrer JSON-Nutzlast für Push-Ereignisse.

Für jedes mit der GitHub-Anwendung verknüpfte Ereignis sind auch die integrierten Variablenwerte is_collaborator und perm_level verfügbar. Der Status des Nutzers wird auf Push- und Pull-Ereignisse nach den Variablenwerten push.pusher.name, pull_request.pull_request.user.login und issue_comment.comment.user.login geprüft. Die folgende Tabelle zeigt, wie Sie diese als Variablenwerte für Ihren Trigger einschließen, wenn sich Ihr Quellcode in GitHub befindet:

Variablenname	Variablenwert:	Variablenbeschreibung
`_PERM_LEVEL`	`$(perm_level)`	Ruft die Berechtigungsstufe des Nutzers ab
`_IS_COLLABORATOR`	`$(is_collaborator)`	Gibt `true` aus, wenn der Nutzer Mitbearbeiter ist

Sie können die Variablenwerte is_collaborator und perm_level für Push-Ereignisse, Pull-Anfrageereignisse und Pull-Anfrageereignisse verwenden, die durch einen Kommentar verknüpft sind. Diesen Variablenwerten muss kein Präfix vorangestellt werden.

Ersatz mit Nutzlastbindungen erstellen

So erstellen Sie eine Substitutionsvariable, die eine Nutzlastbindung verwendet:

Seite "Trigger" aufrufen
Wenn Sie noch keinen Build-Trigger erstellt haben, klicken Sie auf Trigger erstellen. Wählen Sie andernfalls einen vorhandenen Trigger aus.
Klicken Sie unter Substitutionsvariablen auf Variable hinzufügen.
Fügen Sie einen Namen für Ihre Variable hinzu, indem Sie der unten beschriebenen Konvention folgen:
- Substitutionen müssen mit einem Unterstrich (_) beginnen und dürfen entsprechend dem regulären Ausdruck [A-Z0-9_]+ nur Großbuchstaben und Ziffern enthalten. Dadurch werden Konflikte mit integrierten Substitutionen verhindert.
- Es sind maximal 100 Parameter zulässig. Die Länge des Parameterschlüssels ist auf 100 Byte und die Länge des Parameterwerts auf 4.000 Byte begrenzt.
Weitere Informationen zum Definieren und Verwenden benutzerdefinierter Ersetzungen finden Sie unter Benutzerdefinierte Ersetzungen verwenden.

Fügen Sie einen Wert für Ihre Variable mit einem unterstützten Präfix hinzu.

Wenn sich der Quellcode in GitHub befindet, können Sie in Substitutionsvariablen mithilfe von Nutzlastbindungen auf Informationen in der Ereignisnutzlast zurückgreifen. Verwenden Sie das Präfix push oder body, um auf die JSON-Nutzlast eines Push-Ereignisses zuzugreifen. Im folgenden Beispiel wird das Präfix push im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast Ihres Builds verwendet:

Variablenname	Variablenwert:	Variablenbeschreibung
`_PUSH_NAME`	`$(push.repository.name)`	Ruft den Namen des Repository ab, das dem Push-Ereignis zugeordnet ist
`_COMMITS`	`$(push.commits)`	Ruft das Array der Commit-Objekte ab, die jeden übertragenen Commit beschreiben
`_OWNER`	`$(push.repository.owner.name)`	Ruft den Namen des Repository-Inhabers ab
`_URL`	`$(push.repository.html_url)`	Ruft die URL des GitHub-Repositorys ab
`_LANGUAGE`	`$(push.repository.language)`	Ruft die Sprache Ihres in der Übertragung enthaltenen Quellcodes ab

Eine Liste der Felder, auf die Sie mit dem Präfix push zugreifen können, finden Sie unter PushEvent.

Verwenden Sie zum Zugreifen auf die JSON-Nutzlast eines Pull-Anfrageereignisses das Präfix pull_request oder body. Im folgenden Beispiel wird das Präfix pull_request im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast des Builds verwendet:

Variablenname	Variablenwert:	Variablenbeschreibung
`_PULL_REQUEST_ID`	`$(pull_request.pull_request.id)`	Ruft die ID der Pull-Anfrage an
`_PULL_REQUEST_TITLE`	`$(pull_request.pull_request.title)`	Ruft den Titel der Pull-Anfrage ab
`_PULL_REQUEST_BODY`	`$(pull_request.pull_request.body)`	Ruft den Text der Pull-Anfrage ab
`_USERNAME`	`$(pull_request.pull_request.user.login)`	Ruft den Nutzernamen des Absenders der Pull-Anfrage ab
`_MERGE_TIME`	`$(pull_request.pull_request.merged_at)`	Ruft den Zeitpunkt ab, zu dem die Pull-Anfrage zusammengeführt wurde

Eine Liste der Felder, auf die Sie mit dem Präfix pull_request zugreifen können, finden Sie unter PullRequestEvent.

Verwenden Sie das Präfix commit, um auf die JSON-Nutzlast eines Commit-Ereignisses zuzugreifen. Im folgenden Beispiel wird das Präfix commit im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast des Builds verwendet:

Variablenname	Variablenwert:	Variablenbeschreibung
`_COMMIT_URL`	`$(commit.url)`	Erhält die mit dem Commit verknüpfte URL
`_COMMIT_USER`	`$(commit.author.login)`	Ruft den Nutzernamen des Autors des Commits ab
`_COMMIT_MESSAGE`	`$(commit.commit.message)`	Erhält die mit dem Commit verknüpfte Commit-Nachricht
`_COMMIT_DATE`	`$(commit.commit.committer.date)`	Ruft das mit dem Commit verknüpfte Datum ab
`_COMMIT_ADDITIONS`	`$(commit.files['*'].additions)`	Ermittelt die Anzahl der Hinzufügungen, die mit den Dateien im Commit verknüpft sind

Eine Liste der Felder, auf die Sie mit dem Präfix commit zugreifen können, finden Sie unter Commit abrufen.

Wenn Sie die Kommentarsteuerung für einen Trigger aktivieren, der durch eine Pull-Anfrage ausgelöst wird, ist das Ereignis, das den Trigger aufruft, stattdessen ein IssueCommentEvent und das zugehörige Präfix ist issue_comment. In den folgenden Beispielen wird das Präfix issue_comment im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast des Builds verwendet:

Variablenname	Variablenwert:	Variablenbeschreibung
`_PULL_REQUEST_ID`	`$(issue_comment.issue.id)`	Ruft die ID der Pull-Anfrage an
`_PULL_REQUEST_TITLE`	`$(issue_comment.issue.title)`	Ruft den Titel der Pull-Anfrage ab
`_STATE`	`$(issue_comment.state)`	Ruft den Status der Pull-Anfrage ab (offen, geschlossen usw.)
`_LABELS`	`$(issue_comment.issue.labels)`	Ruft die Liste der mit der Pull-Anfrage verknüpften Labels ab
`_LABELS_URL`	`$(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url)`	Ruft die mit dem Label verknüpfte URL ab, die der Beschreibung entspricht

Eine Liste der Felder, auf die Sie mit dem Präfix issue_comment zugreifen können, finden Sie unter IssueCommentEvent.

Wenn sich der Quellcode in Cloud Source Repositories befindet, können Sie mithilfe von Nutzlastbindungen auf Informationen in der Ereignisnutzlast in Substitutionsvariablen verweisen. Verwenden Sie das Präfix csr oder body, um über ein Push-Ereignis auf die JSON-Nutzlast zuzugreifen. Im folgenden Beispiel wird das Präfix csr im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast Ihres Builds verwendet.

Variablenname	Variablenwert:	Variablenbeschreibung
`_REPO_NAME`	`$(csr.name)`	Ruft den Namen Ihres Repositorys ab.
`_REPO_URL`	`$(csr.url)`	Ruft die URL Ihres Repositorys ab.
`_CREATED_REPO`	`$(csr.createRepoEvent)`	Gibt an, ob ein Nutzer ein Repository erstellt hat.
`_REF_EVENT_NAME`	`$(csr.refUpdateEvent.refUpdates['*'].refName)`	Name der Referenz (z. B. "refs/heads/primary-branch")

Unter Benachrichtigungsdaten finden Sie weitere Felder, auf die Sie in Cloud Source Repositories zugreifen können.

Bash-Parametererweiterungen

Sie können die Bash-Parametererweiterungen auf Standardvariablen und benutzerdefinierte Variablen anwenden. Beispiele für unterstützte Vorgänge sind das Ersetzen von Teilstrings, das Aufteilen von Strings und die Großschreibung. Sie können beispielsweise eine Teilzeichenfolge in einer Standardvariablen ersetzen und diese als Bild-Tag verwenden.

Die Bash-Parametererweiterungen, die Sie für Substitutionsvariablen angeben können, sind:

Bash-Erweiterungen	Beschreibung
`${var}`	Maximiert den in `var` gespeicherten Stringwert
`${var^}`	Das erste Zeichen im String wird großgeschrieben
`${var^^}`	Alle Zeichen im String werden großgeschrieben
`${var,}`	Das erste Zeichen im String wird kleingeschrieben
`${var,,}`	Alle Zeichen im String werden kleingeschrieben
`${var:position}`	Entfernt die ersten `position`-Zeichen aus dem String
`${var:position:length}`	Teilt den String ab dem in `position` angegebenen numerischen Wert auf und schließt bis zu dem in `length` angegebenen numerischen Wert ein
`${var/substring/replacement}`	Ersetzt die Instanz ganz links des in `substring` angegebenen Werts durch den in `replacement` angegebenen Wert
`${var//substring/replacement}`	Ersetzt alle Instanzen des in `substring` angegebenen Werts durch den in `replacement` angegebenen Wert
`${var/#substring/replacement}`	Ersetzt die erste Instanz des in `substring` angegebenen Werts durch den in `replacement` angegebenen Wert, wenn `substring` ein Präfix von `var` ist
`${var/%substring/replacement}`	Ersetzt die letzte Instanz des in `substring` angegebenen Werts nur durch den in `replacement` angegebenen Wert, wenn `substring` ein Suffix von `var` ist
`${#var}`	Ruft die Länge des Strings ab
`${var:-default}`	Wertet `var` auf `default` aus, sofern `var` nicht bereits definiert ist

Sie können auch Muster für die folgenden Bash-Parametererweiterungen angeben:

Bash-Erweiterungen	Beschreibung
`${var#pattern}`	Entfernt Zeichen von der linken Seite eines Strings, bis einschließlich der am weitesten links gelegenen Instanz des angegebenen `pattern`
`${var##pattern}`	Entfernt Zeichen auf der linken Seite eines Strings, bis die rechte Instanz des angegebenen `pattern`-Objekts eingeschlossen wird
`${var%pattern}`	Entfernt Zeichen auf der rechten Seite eines Strings, bis die erste Instanz des angegebenen `pattern`-Elements eingeschlossen ist
`${var%%pattern}`	Entfernt Zeichen von der rechten Seite eines Strings, bis einschließlich der am weitesten links gelegenen Instanz des angegebenen `pattern`

Sie können folgende Muster angeben:

Muster	Beschreibung
`*`	Entspricht null oder mehr alphanumerischen Zeichen
`?`	Stimmt mit einem einzelnen alphanumerischen Zeichen überein
`[ccc]`	Stimmt mit jedem einzelnen Zeichen in `ccc` überein, einschließlich der Bereiche zwischen `a-z` oder `0-9`
`[^c]`	Entspricht jedem alphanumerischen Zeichen, das sich nicht in `c` befindet, einschließlich des Zeichenbereichs, wo `lo` <= `c` <= `hi`
`c`	Stimmt mit jedem alphanumerischen Zeichen `c` überein
`\c`	Stimmt mit einem beliebigen `c`-Zeichen überein, einschließlich nicht alphanumerischer Zeichen wie `*`, `?` oder `\`

Bash-Parametererweiterungen anwenden

So wenden Sie eine Bash-Parametererweiterung auf eine integrierte oder benutzerdefinierte Substitutionsvariable an:

Seite "Trigger" aufrufen
Wenn Sie noch keinen Build-Trigger erstellt haben, klicken Sie auf Trigger erstellen. Wählen Sie andernfalls einen vorhandenen Trigger aus.
Klicken Sie unter Substitutionsvariablen auf Variable hinzufügen.
Fügen Sie einen Namen für Ihre Variable hinzu, indem Sie der unten beschriebenen Konvention folgen:
- Substitutionen müssen mit einem Unterstrich (_) beginnen und dürfen entsprechend dem regulären Ausdruck [A-Z0-9_]+ nur Großbuchstaben und Ziffern enthalten. Dadurch werden Konflikte mit integrierten Substitutionen verhindert.
- Es sind maximal 100 Parameter zulässig. Die Länge des Parameterschlüssels ist auf 100 Byte und die Länge des Parameterwerts auf 4.000 Byte begrenzt.
Weitere Informationen zum Definieren und Verwenden benutzerdefinierter Ersetzungen finden Sie unter Benutzerdefinierte Ersetzungen verwenden.

Fügen Sie einen Wert für Ihre Variable hinzu und wenden Sie eine unterstützte Bash-Parametererweiterung auf eine integrierte Substitutionsvariable oder eine andere benutzerdefinierte Substitutionsvariable an.

Im folgenden Beispiel hat die integrierte Substitutionsvariable $BRANCH_NAME den Standardwert Feature_Secret_Project_#v2. Die folgende Tabelle zeigt Beispiele für Bash-Parametererweiterungen, die Sie auf $BRANCH_NAME anwenden können:

Variablenname	Bash-Erweiterung	Variablenwert:	Beschreibung
`_BRANCH_LOWERCASE`	`${$BRANCH_NAME,,}`	`feature_secret_project_#v2`	Alle Zeichen im String werden kleingeschrieben.
`_BRANCH_NO_SUFFIX`	`${_BRANCH_LOWERCASE%_\#v2}`	`feature_secret_project`	Löscht alle Zeichen auf der rechten Seite des Strings, die mit dem angegebenen Muster übereinstimmen
`_BRANCH_NO_PREFIX`	`${_BRANCH_NO_SUFFIX#*_}`	`secret_project`	löscht alle Zeichen bis zum ersten Unterstrich
`_BRANCH_FOR_IMAGE_NAME`	`${_BRANCH_NO_PREFIX//_/-}`	`secret-project`	ersetzt alle Unterstriche durch einen Bindestrich
`_IMAGE_NAME`	`my-app-${_BRANCH_FOR_IMAGE_NAME}-prod`	`my-app-secret-project-prod`	Konstruiert den Namen für das Image mithilfe der oben definierten Variablen `_BRANCH_FOR_IMAGE_NAME`

Angenommen, _IMAGE_NAME ist in Ihrem Trigger als Wert definiert, der in der obigen Tabelle, my-app-secret-project-prod, angegeben ist. Dieser Wert überschreibt jetzt jede Definition von _IMAGE_NAME in der Build-Konfigurationsdatei. Im folgenden Beispiel ersetzt der angegebene Variablenwert für _IMAGE_NAME (my-app-secret-project-prod) den Standardwert _IMAGE_NAME (test-image), wenn der Build-Trigger aufgerufen wird.

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

Im Feld dynamicSubstitutions, das im obigen Beispiel auf true gesetzt ist, können Bash-Parametererweiterungen interpretiert werden. Wenn Ihr Build von einem Trigger aufgerufen wird, ist das Feld dynamicSubstitutions immer auf true gesetzt und muss nicht in der Build-Konfigurationsdatei angegeben werden. Wenn Ihr Build manuell aufgerufen wird, müssen Sie das Feld dynamicSubstitutions auf true setzen, damit die Bash-Parametererweiterungen beim Ausführen des Builds interpretiert werden.

Bash-Parametererweiterungen mit Nutzlastbindungen verwenden

Sie können Bash-Parametererweiterungen auf Variablen anwenden, die mit Nutzlastbindungen verknüpft sind. Erstellen Sie dazu entweder eine neue Variable, um auf die Variable zu verweisen, oder fügen Sie dazu die Bindungen mit Bash-Parametererweiterungen zusammen. Die folgende Tabelle enthält Beispiele für die Verwendung der Bash-Parametererweiterung mit Nutzlastbindungen:

Variablenname	Variablenwert:	Variablenbeschreibung
`_URL`	`$(push.repository.html_url)`	Ruft die URL des Repositorys ab.
`_URL_CAPITAL`	`${_URL^^}`	Verwendet eine Bash-Parametererweiterung, um alle Zeichen in der URL zu trennen
`_APP_NAME`	`my-app-${_URL_CAPITAL}`	Fügt der Präfix-URL des Repositorys ein Präfix hinzu.
`APP_NAME_ID`	`my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7}`	Erstellt einen Anwendungsnamen, der die Repository-URL und die ersten sieben Zeichen der Nutzlast-ID enthält.

Nächste Schritte

Variablenwerte ersetzen
Einfache Build-Konfigurationsdatei erstellen
Weitere Informationen finden Sie unter Build-Trigger erstellen und verwalten.
Builds manuell ausführen