BigQuery-Benachrichtigungen konfigurieren

Cloud Build kann Ihnen Benachrichtigungen an gewünschte Kanäle wie Slack oder Ihren SMTP-Server senden, um Sie über Build-Updates zu informieren. Auf dieser Seite wird erläutert, wie Sie Benachrichtigungen mit dem BigQuery-Notifier konfigurieren.

Mit dem BigQuery-Notifier können Sie Filter für Builds festlegen, die in Ihrer Datenbank gespeichert werden sollen. Sie können beispielsweise Builds nach Trigger-ID, Tags oder Substitutionswerten gruppieren. BigQuery-Notifier schreibt auch Daten in einem standardisierten Format in BigQuery, das berechnete Felder, die für das Build-Objekt nicht sofort zugänglich sind, wie Bildgröße oder Ausführungsdauer. Informationen zum Exportieren von Logeinträgen nach BigQuery oder zu einem anderen Ziel finden Sie unter Logs mit der Google Cloud Console exportieren.

Hinweis

  • Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs aktivieren.

    Aktivieren Sie die APIs

Cloud Build-Notifier

Cloud Build sendet alle Build-Ereignisaktualisierungen zusammen mit Build-Metadaten zum Thema cloud-builds an Pub/Sub. Cloud Build-Notifier können so konfiguriert werden, dass sie dieses Thema überwachen, die empfangenen Nachrichten filtern und Nachrichten an Ihren Dienst senden.

Cloud Build-Notifier sind Docker-Images, die als Container in Cloud Run ausgeführt werden können. Beim Abfragen durch eine Abonnentenanwendung verwenden Cloud Build-Notifier Pull-Abos, um Nachrichten an den konfigurierten Dienst zu senden. Alle Notifier verwenden eine gemeinsame YAML-Spezifikation für die Konfiguration, die in Cloud Storage gespeichert ist.

Cloud Build hält bereitstellbare Notifier-Images im cloud-build-notifiers-Repository vor. In der folgenden Tabelle sind die verfügbaren Notifier aufgeführt:

Notifier Beschreibung
bigquery schreibt Build-Daten in eine BigQuery-Tabelle
http sendet eine JSON-Nutzlast an einen anderen HTTP-Endpunkt
slack verwendet einen Slack-Webhook, um Nachrichten auf einem Slack-Kanal zu posten
smtp sendet E-Mails über einen SMTP-Server

BigQuery-Benachrichtigungen konfigurieren

Im folgenden Abschnitt wird erläutert, wie Sie HTTP-Benachrichtigungen mit dem BigQuery-Notifier manuell konfigurieren. Wenn Sie diese Konfiguration stattdessen automatisieren möchten, finden Sie weitere Informationen unter Konfiguration für Benachrichtigungen automatisieren.

So konfigurieren Sie BigQuery-Benachrichtigungen:

  1. Gewähren Sie Ihrem Cloud Run-Dienstkonto die Berechtigung zum Erstellen und Schreiben von BigQuery-Tabellen, zum Abrufen von Artifact Registry-Daten für Ihren Build sowie Lese- und Schreibzugriff auf Cloud Storage-Buckets:

    1. Rufen Sie in der Google Cloud Console die IAM-Seite auf.

      Seite "IAM" öffnen

    2. Suchen Sie das Compute Engine-Standarddienstkonto, das mit Ihrem Projekt verknüpft ist:

      Ihr Compute Engine-Standarddienstkonto sieht in etwa so aus:

      project-number-compute@developer.gserviceaccount.com
      
    3. Klicken Sie in der Zeile mit dem Compute Engine-Standarddienstkonto auf das Stiftsymbol. Der Tab Berechtigungen bearbeiten wird angezeigt.

    4. Klicken Sie auf Weitere Rolle hinzufügen.

    5. Fügen Sie die folgenden Rollen hinzu:

      • Artifact Registry-Leser
      • BigQuery-Dateneditor
      • Storage-Objekt-Betrachter

      Mit der Rolle Artifact Registry-Leser können Sie Daten für Ihre Images abrufen. Der BigQuery-Dateneditor bietet Lese- und Schreibzugriff auf Ihre Daten. Die Storage-Objekt-Betrachter bietet Lese- und Schreibzugriff auf Cloud Storage-Objekte.

    6. Klicken Sie auf Speichern.

  2. Schreiben Sie eine Notifier-Konfigurationsdatei, um Ihren BigQuery-Notifier zu konfigurieren und nach Build-Ereignissen zu filtern:

    In der folgenden Beispiel-Notifier-Konfigurationsdatei verwendet das Feld filter die Common Expression Language mit der Variable build, um Build-Ereignisse mit einer angegebenen Trigger-ID zu filtern:

    apiVersion: cloud-build-notifiers/v1
    kind: BigQueryNotifier
    metadata:
      name: example-bigquery-notifier
    spec:
      notification:
        filter: build.build_trigger_id == "123e4567-e89b-12d3-a456-426614174000"
        delivery:
          table: projects/project-id/datasets/dataset-name/tables/table-name
    

    Wobei:

    • project-id ist die ID Ihres Cloud-Projekts.
    • dataset-name ist der Name, den Sie dem Dataset geben möchten.
    • table-name ist der Name, den Sie der Tabelle geben möchten.

    Das table-name in Ihrer Notifier-Konfigurationsdatei kann auf folgende Elemente verweisen:

    • eine nicht vorhandene Tabelle
    • Leere Tabelle ohne Schema
    • Eine vorhandene Tabelle mit einem Schema, das den Schemaspezifikationen in dem BigQuery-Notifier entspricht

    Es empfiehlt sich, die Build-Trigger-ID als Filter anzugeben, da Sie damit Build-Daten für Ihre Trigger korrelieren können. Sie können auch mehrere Trigger-IDs in einer Liste angeben: build.build_trigger_id in ["example-id-123", "example-id-456"].

    Führen Sie den folgenden Befehl aus, um die Trigger-ID abzurufen: wobei trigger-name der Name Ihres Triggers ist.

    gcloud beta builds triggers describe trigger-name

    Der Befehl listet die Felder auf, die dem Trigger zugeordnet sind, einschließlich der Trigger-ID.

    Das Beispiel finden Sie in der Konfigurationsdatei für Notifier für den BigQuery-Notifier.

    Weitere Felder, nach denen Sie filtern können, finden Sie in der Ressource Build. Weitere Beispiele zum Filtern finden Sie im Hilfeartikel Build-Ereignisse mit CEL filtern.

  3. Laden Sie die Notifier-Konfigurationsdatei in einen Cloud Storage-Bucket hoch:

    1. Wenn Sie keinen Cloud Storage-Bucket haben, führen Sie den folgenden Befehl aus, um einen Bucket zu erstellen. Dabei ist bucket-name der Name, den Sie Ihrem Bucket gemäß den Vorgaben für die Benennung geben sollten.

      gsutil mb gs://bucket-name/
      
    2. Laden Sie die Konfigurationsdatei für den Notifier in Ihren Bucket hoch:

      gsutil cp config-file-name gs://bucket-name/config-file-name
      

      Wobei:

      • bucket-name ist der Name des Buckets.
      • config-file-name ist der Name der Konfigurationsdatei für den Notifier.
  4. Stellen Sie den Notifier in Cloud Run bereit.

     gcloud run deploy service-name \
       --image=us-east1-docker.pkg.dev/gcb-release/cloud-build-notifiers/bigquery:latest \
       --no-allow-unauthenticated \
       --update-env-vars=CONFIG_PATH=config-path,PROJECT_ID=project-id
    

    Hierbei gilt:

    • service-name ist der Name des Cloud Run-Dienstes, in dem Sie das Image bereitstellen.
    • config-path ist der Pfad zur Konfigurationsdatei für den BigQuery-Notifier gs://bucket-name/config-file-name.
    • project-id ist die ID Ihres Cloud-Projekts.

    Mit dem Befehl gcloud run deploy wird die neueste Version des erstellten Images aus Artifact Registry abgerufen. Cloud Build unterstützt Notifier-Images neun Monate lang. Nach neun Monaten löscht Cloud Build die Image-Version. Wenn Sie eine frühere Image-Version verwenden möchten, müssen Sie die vollständige semantische Version des Image-Tags im Attribut image Ihres gcloud run deploy-Befehls angeben. Ältere Image-Versionen und Tags finden Sie in Artifact Registry.

  5. Gewähren Sie Pub/Sub-Berechtigungen zum Erstellen von Authentifizierungstokens in Ihrem Projekt:

     gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
    

    Hierbei gilt:

    • project-id ist die ID Ihres Cloud-Projekts.
    • project-number ist die Nummer Ihres Cloud-Projekts.
  6. Erstellen Sie ein Dienstkonto, das die Pub/Sub-Abonnementidentität darstellen soll:

    gcloud iam service-accounts create cloud-run-pubsub-invoker \
      --display-name "Cloud Run Pub/Sub Invoker"
    

    Sie können cloud-run-pubsub-invoker oder einen innerhalb Ihres Google Cloud-Projekts eindeutigen Namen verwenden.

  7. Weisen Sie dem Dienstkonto cloud-run-pubsub-invoker die Cloud Run-Berechtigung Invoker zu:

    gcloud run services add-iam-policy-binding service-name \
       --member=serviceAccount:cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com \
       --role=roles/run.invoker
    

    Hierbei gilt:

    • service-name ist der Name des Cloud Run-Dienstes, in dem Sie das Image bereitstellen.
    • project-id ist die ID Ihres Cloud-Projekts.
  8. Nach der Aktivierung der Pub/Sub API sollte das automatisch erstellte Thema cloud-builds auf der Seite Pub/Sub-Themen angezeigt werden. Wenn das Thema cloud-builds nicht angezeigt wird, führen Sie den folgenden Befehl aus, um das Thema manuell zu erstellen und Build-Update-Nachrichten für Ihren Notifier zu erhalten:

    gcloud pubsub topics create cloud-builds
    
  9. Erstellen Sie einen Pub/Sub-Push-Abonnenten für Ihren Notifier:

     gcloud pubsub subscriptions create subscriber-id \
       --topic=cloud-builds \
       --push-endpoint=service-url \
       --push-auth-service-account=cloud-run-pubsub-invoker@project-id.iam.gserviceaccount.com
    

    Hierbei gilt:

    • subscriber-id ist der Name, den Sie Ihrem Abo geben möchten.
    • service-url ist die von Cloud Run generierte URL für Ihren neuen Dienst.
    • project-id ist die ID Ihres Cloud-Projekts.

Benachrichtigungen sind nun für Ihr Cloud Build-Projekt eingerichtet.

Wenn Sie das nächste Mal einen Build aufrufen, wird Ihre Tabelle mit den neuesten Daten aktualisiert, die dem Filter entsprechen, den Sie für Ihren BigQuery-Notifier konfiguriert haben.

Build-Daten aufrufen

So rufen Sie Build-Daten in BigQuery auf:

  1. Öffnen Sie die Seite der BigQuery-Konsole:

    Zur Seite „BigQuery“

  2. Klicken Sie unter Ressourcen auf die Projekt-ID, die Sie zum Konfigurieren des BigQuery-Notifier verwenden.

  3. Klicken Sie auf den Namen des Datasets.

  4. Klicken Sie auf den Tabellennamen.

Sie können jetzt Informationen zu Ihrer Tabelle einschließlich des Schemas und einer Vorschau Ihrer Build-Daten sehen, wie gelistet in der Tabelle.

Auf Build-Daten zugreifen

Sie können Daten in Ihrer Tabelle mit dem bq-Befehlszeilentool oder der BigQuery-Konsole abfragen.

Befehlszeile

Zum Abfragen von Daten in der Tabelle mit dem bq-Befehlszeilentool führen Sie den folgenden Befehl in Ihrem Terminal aus, wobei sql-query Ihre Abfrage ist:

bq query sql-query

Wenn Sie auf dieser Seite die Abfragebeispiele verwenden möchten, geben Sie das Flag --nouse_legacy_sql seit dem Befehl in Ihrem Befehl an. Das bq-Befehlszeilentool verwendet Legacy-SQL, bei den die Beispielabfragen nicht. Führen Sie den folgenden Befehl in Ihrem Terminal aus, um Daten ohne Legacy-SQL abzufragen:

bq query sql-query --nouse_legacy_sql

Console

So fragen Sie Daten in Ihrer Tabelle mithilfe der BigQuery-Konsole ab:

  1. Öffnen Sie die Seite der BigQuery-Konsole:

    Zur Seite „BigQuery“

  2. Klicken Sie unter Ressourcen auf den Tabellennamen, den Sie abfragen möchten.

  3. Schreiben Sie die SQL-Abfrage in dem Abfrageeditor.

Build-Daten mit Abfragen aufrufen

Die folgenden Beispielabfragen zeigen, wie Sie nach der Konfiguration des BigQuery-Notifiers auf Build-Daten für Ihr Build-Ereignis zugreifen können:

Gesamt-Build-Verlauf

SELECT * FROM `projectID.datasetName.tableName`

Anzahl nach Build gruppiert nach Version

SELECT STATUS, COUNT(*)
FROM `projectID.datasetName.tableName`
GROUP BY STATUS

Tägliche Bereitstellungshäufigkeit für die aktuelle Woche

SELECT DAY, COUNT(STATUS) AS Deployments
FROM (SELECT DATETIME_TRUNC(CreateTime, WEEK) AS WEEK,
      DATETIME_TRUNC(CreateTime, DAY) AS DAY,
      STATUS
      FROM `projectID.datasetName.tableName`
      WHERE STATUS="SUCCESS")
WHERE WEEK = DATETIME_TRUNC(CURRENT_DATETIME(), WEEK)
GROUP BY DAY

Weitere Beispielabfragen finden Sie in der README-Datei für Cloud Build BigQuery Notifier im GitHub-Repository cloud-build-notifiers. Weitere Informationen zum Abfragen von Daten mit BigQuery finden Sie unter Daten abfragen und ansehen.

CEL zum Filtern von Build-Ereignissen verwenden

Cloud Build verwendet CEL mit der Variablen build für Felder in der Ressource Build, um auf Felder zuzugreifen, die mit Ihrem Build-Ereignis verknüpft sind, z. B. Ihre Trigger-ID, Image-Liste oder Ersatzwerte. Sie können den String filter verwenden, um Build-Ereignisse in Ihrer Build-Konfigurationsdatei mit einem beliebigen Feld zu filtern, das in der Ressource Build aufgeführt ist. Die genaue Syntax, die dem Feld zugeordnet ist, finden Sie in der Datei cloudbuild.proto.

Nach Trigger-ID filtern

Wenn Sie nach Trigger-ID filtern möchten, geben Sie den Wert Ihrer Trigger-ID im Feld filter mit build.build_trigger_id an. Dabei ist trigger-id Ihre Trigger-ID als String:

filter: build.build_trigger_id == trigger-id

Nach Status filtern

Geben Sie im Feld filter mithilfe von build.status den Build-Status an, nach dem der Filter gefiltert werden soll.

Das folgende Beispiel zeigt, wie Sie Build-Ereignisse mit dem Status SUCCESS mithilfe des Felds filter filtern:

filter: build.status == Build.Status.SUCCESS

Sie können auch Builds mit unterschiedlichen Status filtern. Das folgende Beispiel zeigt, wie Build-Ereignisse mit dem Status SUCCESS, FAILURE oder TIMEOUT mit dem Feld filter gefiltert werden:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

Weitere Statuswerte, nach denen Sie filtern können, finden Sie in der Referenz zu Build-Ressourcen unter Status.

Nach Tag filtern

Geben Sie zum Filtern nach Tag den Wert Ihres Tags im Feld filter mit build.tags ein, wobei tag-name der Name des Tags ist:

filter: tag-name in build.tags

Mit size können Sie nach der Anzahl der in Ihrem Build-Ereignis angegebenen Tags filtern. Im folgenden Beispiel filtert das Feld filter Build-Ereignisse, bei denen genau zwei Tags angegeben sind, wobei ein Tag als v1 angegeben ist:

filter: size(build.tags) == 2 && "v1" in build.tags

Nach Images filtern

Wenn Sie nach Images filtern möchten, geben Sie den Wert Ihres Images im Feld filter mit build.images an, wobei image-name der vollständige Name des Images ist, wie in Container Registry aufgeführt, z. B. gcr.io/example/image-one:

filter: image-name in build.images

Im folgenden Beispiel filtert filter nach Build-Ereignissen, in denen entweder gcr.io/example/image-one oder gcr.io/example/image-two als Bildnamen angegeben ist:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

Nach Zeitraum filtern

Sie können Build-Ereignisse nach der Erstellungszeit, dem Beginn oder dem Ende eines Builds filtern. Geben Sie dazu in Ihrem Feld filter eine der folgenden Optionen an: build.create_time, build.start_time oder build.finish_time zurück.

Im folgenden Beispiel verwendet das Feld filter timestamp, um Build-Ereignisse mit einer Anfragezeit zu filtern, um den Build am 20. Juli 2020 um 6:00 Uhr zu erstellen:

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

Sie können Build-Ereignisse auch nach Zeitvergleichen filtern. Im folgenden Beispiel verwendet das Feld filter timestamp, um Build-Ereignisse mit einer Startzeit zwischen dem 20. Juli 2020, 6:00 Uhr und dem 30. Juli 2020 um 6:00 Uhr zu filtern. , um die Option zu aktivieren.

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

Weitere Informationen dazu, wie Zeitzonen in CEL ausgedrückt werden, finden Sie in der Sprachdefinition für Zeitzonen.

Zum Filtern nach der Dauer eines Builds können Sie duration verwenden, um Zeitstempel zu vergleichen. Im folgenden Beispiel verwendet das Feld filter duration, um Build-Ereignisse mit Builds zu filtern, die mindestens fünf Minuten lang ausgeführt werden:

filter: build.finish_time - build.start_time >= duration("5m")

Nach Substitution filtern

Sie können nach Substitution filtern, wenn Sie die Substitutionsvariable im Feld filter mit build.substitutions angeben. Im folgenden Beispiel listet das Feld filter Builds auf, die die Substitutionsvariable substitution-variable enthalten, und prüft, ob substitution-variable mit dem angegebenen substitution-value übereinstimmt:

filter: build.substitutions[substitution-variable] == substitution-value

Hierbei gilt:

  • substitution-variable ist der Name der Substitutionsvariablen.
  • substitution-value ist der Name Ihres Substitutionswerts.

Sie können auch nach Standardwerten für Substitutionsvariablen filtern. Im folgenden Beispiel werden im Feld filter Builds mit dem Zweignamen master und Builds mit dem Repository-Namen github.com/user/my-example-repo aufgelistet. Die Standardsubstitutionsvariablen BRANCH_NAME und REPO_NAME werden als Schlüssel an build.substitutions übergeben:

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

Wenn Sie mithilfe von regulären Ausdrücken nach Strings filtern möchten, können Sie die integrierte Funktion matches verwenden. Im folgenden Beispiel filtert das Feld filter nach Builds mit dem Status FAILURE oder TIMEOUT und einer Build-Substitutionsvariablen TAG_NAME mit einem Wert, der dem regulären Ausdruck v{DIGIT}.{DIGIT}.{3 DIGITS}) entspricht.

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

Eine Liste der Standardsubstitutionswerte finden Sie unter Standardsubstitutionen verwenden.

Nächste Schritte