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.

Der BigQuery-Notifier bietet Ihnen die Möglichkeit zum Anwenden von Filtern auf die Builds, die Sie in der Datenbank speichern möchten. Sie können Builds beispielsweise nach Trigger-ID, Tags oder Substitutionswerten gruppieren. Der BigQuery-Notifier schreibt auch Daten in BigQuery in einem standardisierten Format mit berechneten Feldern, auf die das Build-Objekt nicht sofort zugreifen kann, z. B. Image-Größe oder Ausführungsdauer. Wie Sie Logeinträge in BigQuery oder ein anderes Ziel exportieren, erfahren Sie unter Logs mit der Google Cloud Console exportieren.

Hinweise

Cloud Build, Cloud Run, Pub/Sub, and BigQuery APIs aktivieren.
Aktivieren Sie die APIs

Installieren Sie die Google Cloud CLI.

BigQuery-Benachrichtigungen konfigurieren

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

So konfigurieren Sie BigQuery-Benachrichtigungen:

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 auf das Stiftsymbol in der Zeile, die das Compute Engine-Standarddienstkonto enthält. Der Tab Zugriff 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. Mit der Rolle BigQuery-Dateneditor erhalten Sie Lese- und Schreibzugriff auf Ihre Daten. Die Rolle Storage-Objekt-Betrachter gewährt Lesezugriff auf Cloud Storage-Objekte.
  
  Hinweis: Wenn Sie Berechtigungen auf Bucket-Ebene statt auf Projektebene gewähren möchten, fügen Sie die Rolle Inhaber von Legacy-Storage-Objekten zum Bucket hinzu, wenn Sie diesen erstellen. Weitere Informationen finden Sie unter Rollen auf Projektebene im Vergleich zu Rollen auf Bucket-Ebene.
6. Klicken Sie auf Speichern.
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"
    params:
      buildStatus: $(build.status)
    delivery:
      table: projects/project-id/datasets/dataset-name/tables/table-name
    template:
      type: golang
      uri: gs://example-gcs-bucket/bq.json
```
Wobei:
- buildStatus ist ein benutzerdefinierter Parameter. Dieser Parameter übernimmt den Wert von ${build.status}, dem Status des Builds.
- project-id ist die ID des Google 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 Feld uri verweist auf die Datei bq.json. Diese Datei bezieht sich auf eine in Cloud Storage gehostete JSON-Vorlage und stellt die Informationen dar, die in die BigQuery-Tabelle eingefügt werden sollen.
  
  Experimentell — Customizing notifications using templates
  
  Diese Funktion unterliegt den „Nutzungsbedingungen für Pre-GA-Angebote“ im Abschnitt „Allgemeine Nutzungsbedingungen“ der dienstspezifischen Nutzungsbedingungen. Pre-GA-Funktionen sind „wie besehen“ verfügbar und werden möglicherweise nur eingeschränkt unterstützt. Weitere Informationen finden Sie in den Beschreibungen der Startphase.
Ein Beispiel für eine Vorlagendatei finden Sie in der Datei bq.json im Repository „cloud-build-notifiers-“.

Das table-name in Ihrer Notifier-Konfigurationsdatei kann auf folgende Elemente verweisen:
- Eine nicht vorhandene Tabelle
- Eine leere Tabelle ohne Schema
- Eine vorhandene Tabelle mit einem Schema, das den Schemaspezifikationen in dem BigQuery-Notifier entspricht
  
  Hinweis: Verweise auf eine vorhandene Tabelle mit einer Schemaspezifikation, die nicht mit dem BigQuery-Notifier übereinstimmt, führen zu einem Fehler.
Wir empfehlen, die Build-Trigger-ID als Filter anzugeben, da Sie mit den Build-Trigger-ID 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-Build-Trigger beschreiben trigger-name

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

Hinweis: Daten werden nur für Build-Ereignisse mit einem Terminalstatus wie SUCCESS oder FAILURE gespeichert.

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 Filterbeispiele finden Sie unter CEL zum Filtern von Build-Ereignissen verwenden.
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.
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
```
Wobei:
- service-name ist der Name des Cloud Run-Dienstes, in dem Sie das Image bereitstellen.
  
  Hinweis: service-name verweist auf den neuen Notifier-Dienst, den Sie erstellen.
- config-path ist der Pfad zur Konfigurationsdatei für den BigQuery-Notifier gs://bucket-name/config-file-name.
- project-id ist die ID des Google 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.

Hinweis: Bei der Ausführung dieses Befehls werden Sie möglicherweise aufgefordert, zusätzliche Argumente wie --region oder --platform anzugeben. Weitere Informationen zu den Parametern, die Sie an den Befehl gcloud run deploy übergeben können, finden Sie unter In Cloud Run bereitstellen. Wenn Sie den Notifier mit diesem Befehl nicht bereitstellen können, lesen Sie die Anleitung zur Fehlerbehebung in Cloud Run. Hier finden Sie Lösungen zum Beheben von Bereitstellungsfehlern.
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
```
Wobei:
- project-id ist die ID des Google Cloud-Projekts.
- project-number ist die Nummer Ihres Google Cloud-Projekts.
Hinweis: Wenn das Pub/Sub-Dienstkonto in Ihrem Projekt nicht vorhanden ist, lesen Sie Abos erstellen und verwenden.
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.
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
```
Wobei:
- service-name ist der Name des Cloud Run-Dienstes, in dem Sie das Image bereitstellen.
- project-id ist die ID des Google Cloud-Projekts.
Erstellen Sie das Thema cloud-builds, um Build-Update-Nachrichten für Ihren Notifier zu erhalten:
```
gcloud pubsub topics create cloud-builds
```
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
```
Wobei:
- 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 des Google Cloud-Projekts.

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

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

Build-Daten ansehen

So rufen Sie Build-Daten in BigQuery auf:

Öffnen Sie die Seite der BigQuery-Konsole:

Zur Seite „BigQuery“
Klicken Sie unter Ressourcen auf die Projekt-ID, die Sie zum Konfigurieren des BigQuery-Notifiers verwenden.
Klicken Sie auf den Namen des Datasets.
Klicken Sie auf den Namen der Tabelle.

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.

CLI

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 die Abfragebeispiele auf dieser Seite verwenden möchten, müssen Sie das Flag --nouse_legacy_sql in Ihrem Befehl angeben. Das bq-Befehlszeilentool verwendet Legacy-SQL, die Beispielabfragen jedoch 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 mit der BigQuery-Konsole ab:

Öffnen Sie die Seite der BigQuery-Konsole:

Zur Seite „BigQuery“
Klicken Sie unter Ressourcen auf den Tabellennamen, den Sie abfragen möchten.
Schreiben Sie die SQL-Abfrage in dem Abfrageeditor.

Mit Abfragen auf Build-Daten zugreifen

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`

Build-Anzahl nach Status gruppiert

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

Häufigkeit der täglichen Bereitstellung 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 "Cloud Build BigQuery Notifier" im cloud-build-notifiers-Repository auf GitHub. Informationen zum Abfragen von Daten mit BigQuery finden Sie unter Daten abfragen und aufrufen.

Build-Ereignisse mit CEL filtern

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 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 des Images im Feld filter mit build.images an, wobei image-name der vollständige Name des Images ist, wie in Artifact Registry aufgeführt, z. B. us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Im folgenden Beispiel filtert filter nach Build-Ereignissen, für die entweder us-east1-docker.pkg.dev/my-project/docker-repo/image-one oder us-east1-docker.pkg.dev/my-project/docker-repo/image-two als Image-Namen angegeben sind:

filter: "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" in build.images || "us-east1-docker.pkg.dev/my-project/docker-repo/image-one" 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

Wobei:

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

Informationen zu Cloud Build-Benachrichtigungen
Build-Benachrichtigungen abonnieren
Build-Konfigurationsdatei für Cloud Build schreiben