BigQuery-Benachrichtigungen konfigurieren

Cloud Build kann Ihnen Benachrichtigungen an bestimmte 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 angeben, die Sie in Ihrer Datenbank speichern möchten. Sie können Builds beispielsweise nach Trigger-ID, Tags oder Substitutionswerten gruppieren. Der BigQuery-Notifier schreibt Daten auch in einem standardisierten Format in BigQuery. Dieses Format enthält berechnete Felder, die nicht sofort über das Build-Objekt zugänglich sind, z. B. die Bildgröße oder die Ausführungsdauer. Informationen zum Exportieren von Logeinträgen nach BigQuery oder an ein anderes Ziel finden Sie unter Logs mit der Google Cloud -Konsole exportieren.

Hinweis

  • Aktivieren Sie die Cloud Build, Cloud Run, Pub/Sub und BigQuery APIs, falls sie noch nicht aktiviert sind.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

    APIs aktivieren

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:

  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 Ihrem Compute Engine-Standarddienstkonto auf das Stiftsymbol. Der Tab Bearbeitungszugriff wird angezeigt.

    4. Klicken Sie auf Weitere Rolle hinzufügen.

    5. Fügen Sie die folgenden Rollen hinzu:

      • Artifact Registry-Leser
      • BigQuery-Dateneditor
      • Storage Object Viewer

      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. Mit der Rolle Storage-Objekt-Betrachter-erhalten Sie Lesezugriff 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"
    params:
      buildStatus: $(build.status)
    delivery:
      table: projects/PROJECT_ID/datasets/DATASET_NAME/tables/TABLE_NAME
    template:
      type: golang
      uri: gs://BUCKET_NAME/bq.json

    Wobei:

    • buildStatus ist ein benutzerdefinierter Parameter. Dieser Parameter nimmt den Wert von ${build.status} an, dem Status des Builds.
    • BUCKET_NAME ist der Name des Buckets.
    • 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 verweist auf eine JSON-Vorlage, die in Cloud Storage gehostet wird, und enthält die Informationen, die in Ihre BigQuery-Tabelle eingefügt werden sollen.

    Ein Beispiel für eine Vorlagendatei finden Sie im Repository für Cloud-Build-Notifier in der Datei bq.json.

    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

    Wir empfehlen, die Build-Trigger-ID als Filter anzugeben, da Sie so 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 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 Filterbeispiele finden Sie unter CEL zum Filtern von Build-Ereignissen verwenden.

  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.

      gcloud storage buckets create gs://BUCKET_NAME/

    2. Laden Sie die Konfigurationsdatei für den Notifier in Ihren Bucket hoch:

      gcloud storage 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 des Google Cloud -Projekts.

    Mit dem Befehl gcloud run deploy wird die neueste Version des gehosteten Images aus der Artifact Registry von Cloud Build 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. Erstellen Sie ein Dienstkonto, das die Pub/Sub-Abonnementidentität darstellen soll:

    gcloud iam service-accounts create SUB_IDENTITY_SERVICE_ACCOUNT \
  --display-name "SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME"

    Wobei:

    • SUB_IDENTITY_SERVICE_ACCOUNT ist ein Name für das Dienstkonto.

    • SUB_IDENTITY_SERVICE_ACCOUNT_DISPLAY_NAME ist ein Anzeigename für das Dienstkonto.

  6. Erteilen Sie dem Dienstkonto der Identität Ihres Pub/Sub-Abos die erforderlichen Berechtigungen zum Erstellen von Authentifizierungstokens in IhremGoogle Cloud -Projekt.

    gcloud iam service-accounts add-iam-policy-binding \
    SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iiam.gserviceaccount.com \
    --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 Ihre Google Cloud Projektnummer.

  7. Weisen Sie dem SUB_IDENTITY_SERVICE_ACCOUNT-Dienstkonto die Cloud Run-Rolle Invoker zu:

    gcloud run services add-iam-policy-binding SERVICE_NAME \
   --member=serviceAccount:SUB_IDENTITY_SERVICE_ACCOUNT@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.

  8. Erstellen Sie das Thema cloud-builds, um Build-Aktualisierungsnachrichten für Ihren Notifier zu empfangen:

    gcloud pubsub topics create cloud-builds

    Sie können auch einen benutzerdefinierten Themennamen in Ihrer Build-Konfigurationsdatei definieren, damit Nachrichten stattdessen an das benutzerdefinierte Thema gesendet werden. In diesem Fall würden Sie ein Thema mit demselben benutzerdefinierten Namen erstellen:

    gcloud pubsub topics create topic-name

    Weitere Informationen finden Sie unter Pub/Sub-Themen für Build-Benachrichtigungen.

  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=SUB_IDENTITY_SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com

Dabei gilt: + SUBSCRIBER_ID ist der Name, den Sie dem Abo geben möchten. + SERVICE_URL ist die von Cloud Run generierte URL für den neuen Dienst. + PROJECT_ID ist die ID des Google Cloud -Projekts.

Note: By default, [subscriptions expire after 31 days of inactivity](/pubsub/docs/subscription-overview#lifecycle).
You can adjust or disable the expiration period by including the
[`--expiration-period` flag](/sdk/gcloud/reference/pubsub/subscriptions/create#--expiration-period)
when creating the subscription.

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:

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

    Zur Seite „BigQuery“

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

  3. Klicken Sie auf den Namen Ihres Datasets.

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

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

  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.

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 für Ihr Feld 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 Bildern filtern möchten, geben Sie den Wert Ihres Bildes im Feld filter mit build.images an. Dabei ist image-name der vollständige Name Ihres Bildes, wie er in Artifact Registry aufgeführt ist, z. B. us-east1-docker.pkg.dev/my-project/docker-repo/image-one:

filter: image-name in build.images

Im folgenden Beispiel filtert filter Build-Ereignisse, bei denen 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 Bildnamen 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 Ersetzung filtern, indem Sie die Ersetzungsvariable im Feld filter mit build.substitutions angeben. Im folgenden Beispiel werden im Feld filter Builds aufgeführt, die die Ersetzungsvariable substitution-variable enthalten. Außerdem wird geprüft, ob substitution-variable mit dem angegebenen substitution-value übereinstimmt:

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

Hierbei gilt:

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

Sie können auch nach Standardwerten für Ersetzungsvariablen 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 Beispiel unten werden mit dem Feld filter Builds mit dem Status FAILURE oder TIMEOUT gefiltert, die auch eine Build-Ersetzungsvariable TAG_NAME mit einem Wert haben, 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