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 verwenden und Bash-Parametererweiterungen anwenden, 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:

  1. Seite "Trigger" aufrufen

  2. Wenn Sie noch keinen Build-Trigger erstellt haben, klicken Sie auf Trigger erstellen. Wählen Sie andernfalls einen vorhandenen Trigger aus.

  3. Klicken Sie unter Substitutionsvariablen auf Variable hinzufügen.

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

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

    Wenn sich Ihr Quellcode in GitHub befindet, können Sie mithilfe von Nutzlastbindungen auf Informationen in Ihrer Ereignisnutzlast in Ersatzvariablen verweisen. Verwenden Sie zum Zugreifen auf die JSON-Nutzlast eines Push-Ereignisses das Präfix push oder body. Im folgenden Beispiel wird das Präfix push im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast des 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 Ihr Quellcode in Cloud Source Repositories befindet, können Sie mithilfe von Nutzlastbindungen auf Informationen in Ihrer Ereignisnutzlast in Substitutionsvariablen verweisen. Verwenden Sie zum Zugreifen auf die JSON-Nutzlast eines Push-Ereignisses das Präfix csr oder body. Im folgenden Beispiel wird das Präfix csr im Variablenwert als Einstiegspunkt für den Zugriff auf Informationen aus der JSON-Nutzlast des 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:

  1. Seite "Trigger" aufrufen

  2. Wenn Sie noch keinen Build-Trigger erstellt haben, klicken Sie auf Trigger erstellen. Wählen Sie andernfalls einen vorhandenen Trigger aus.

  3. Klicken Sie unter Substitutionsvariablen auf Variable hinzufügen.

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

  5. 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