Ausführungsbenachrichtigungen für BigQuery Data Transfer Service

Diese Seite bietet einen Überblick der Ausführungsbenachrichtigungen für den BigQuery Data Transfer Service.

Überblick

Sie können für BigQuery Data Transfer Service zwei Arten von Ausführungsbenachrichtigungen konfigurieren:

Pub/Sub-Benachrichtigungen: maschinenlesbare Benachrichtigungen, die bei einer erfolgreichen oder fehlgeschlagenen Übertragung gesendet werden
E-Mail-Benachrichtigungen: für Menschen lesbare Benachrichtigungen, die bei einer fehlgeschlagenen Übertragung gesendet werden

Sie können jeden Typ einzeln konfigurieren oder Pub/Sub- und E-Mail-Ausführungsbenachrichtigungen zusammen verwenden.

Pub/Sub-Benachrichtigungen

Pub/Sub-Benachrichtigungen senden Informationen zu Übertragungen an ein Pub/Sub-Thema. Pub/Sub-Benachrichtigungen werden durch abgeschlossene Übertragungen mit einem der folgenden Status ausgelöst:

SUCCEEDED
FAILED
CANCELLED

Sie können Benachrichtigungen an alle Pub/Sub-Themen in jedem Projekt senden, für das Sie ausreichende Berechtigungen haben. Nach dem Eingang beim jeweiligen Pub/Sub-Thema kann die Nachricht an eine beliebige Anzahl von Abonnenten dieses Themas weitergeleitet werden.

Hinweis

Vor dem Konfigurieren von Pub/Sub-Ausführungsbenachrichtigungen für Übertragungen sollten Sie Folgendes tun:

Aktivieren Sie die Pub/Sub API für das Projekt, das die Benachrichtigungen erhalten wird.

API aktivieren
Achten Sie auf ausreichende Berechtigungen für das Projekt, das die Benachrichtigungen erhalten wird:
- Wenn Sie der Inhaber des Projekts sind, das die Benachrichtigungen erhalten wird, haben Sie wahrscheinlich die erforderliche Berechtigung.
- Wenn Sie Themen zum Empfangen von Benachrichtigungen erstellen möchten, benötigen Sie die Berechtigung pubsub.topics.create.
- Wenn Sie neue oder vorhandene Themen verwenden möchten, benötigen Sie die Berechtigungen pubsub.topics.getIamPolicy und pubsub.topics.setIamPolicy Wenn Sie ein Thema erstellen, haben Sie normalerweise bereits die Berechtigung dafür. Die folgende vordefinierte IAM-Rolle hat sowohl die Berechtigung pubsub.topics.getIamPolicy als auch pubsub.topics.setIamPolicy: pubsub.admin. Weitere Informationen finden Sie unter Pub/Sub-Zugriffssteuerung.
Achten Sie darauf, dass ein bestehendes Cloud Pub/Sub-Thema vorhanden ist, an das Sie Benachrichtigungen senden möchten.

Benachrichtigungsformat

Benachrichtigungen, die an ein Pub/Sub-Thema gesendet werden, bestehen aus zwei Teilen:

Attribute: Eine Reihe von Schlüssel/Wert-Paaren, die das Ereignis beschreiben
Nutzlast: Ein String, der die Metadaten des geänderten Objekts enthält

Attribute

Attribute sind Schlüssel/Wert-Paare, die in allen Benachrichtigungen enthalten sind, die von BigQuery Data Transfer Service an Ihr Pub/Sub-Thema gesendet werden. Benachrichtigungen enthalten immer die folgenden Schlüssel/Wert-Paare, unabhängig von der Nutzlast der Benachrichtigung:

Attributname	Beispiel	Beschreibung
eventType	`TRANSFER_RUN_FINISHED`	Die Art des Ereignisses, das gerade aufgetreten ist. `TRANSFER_RUN_FINISHED` ist der einzig mögliche Wert.
payloadFormat	`JSON_API_V1`	Das Format der Objektnutzlast. `JSON_API_V1` ist der einzig mögliche Wert.

Nutzlast

Die Nutzlast ist ein String, der die Metadaten der Übertragung enthält. Der Nutzlasttyp ist derzeit nicht konfigurierbar und wird nur für zukünftige Änderungen der API-Version bereitgestellt.

Nutzlasttyp	Beschreibung
JSON_API_V1	Die Nutzlast ist ein JSON-serialisierter UTF-8-String, der die Ressourcendarstellung einer Übertragung (`TransferRun`) enthält.

E-Mail-Benachrichtigungen

E-Mail-Benachrichtigungen senden bei fehlgeschlagenen Übertragungen für Menschen lesbare E-Mail-Nachrichten. Diese Nachrichten werden an den Nutzer gesendet, der die Übertragung eingerichtet hat. Die Nachrichten sind nicht konfigurierbar.

Wenn andere Nutzer E-Mail-Benachrichtigungen zu Übertragungen erhalten sollen, richten Sie E-Mail-Weiterleitungsregeln ein, um die Nachrichten zu verteilen. Bei Verwendung von Gmail können Sie Gmail-Nachrichten automatisch an ein anderes Konto weiterleiten.

Die E-Mail-Benachrichtigung wird von BigQuery Data Transfer Service gesendet. Sie enthält Details zur Konfiguration und Ausführung der Übertragung sowie einen Link zum Ausführungsverlauf der fehlgeschlagenen Übertragung. Beispiel:

From: bigquery-data-transfer-service-noreply@google.com
To: user_who_set_up_transfer
Title: BigQuery Data Transfer Service — Transfer Run Failure —
display_name

Transfer Configuration
Display Name: display_name
Source: data_source
Destination: project_id

Run Summary
Run: run_name
Schedule Time: schedule_time
Run Time: run_time
View Run History

Google LLC 1600 Amphitheatre Parkway, Mountain View, CA 94043

This email was sent because you indicated you are willing to receive Run
Notifications from the BigQuery Data Transfer Service. If you do not wish to
receive such emails in the future, click View Transfer Configuration and
un-check the "Send E-mail Notifications" option.

Benachrichtigungen aktivieren

So aktivieren Sie Benachrichtigungen:

Console

Rufen Sie in der Google Cloud Console die Seite "BigQuery" auf.

Zur Seite „BigQuery“
Klicken Sie im Navigationsmenü auf Datenübertragungen.
Klicken Sie auf Übertragung erstellen, um Benachrichtigungen für eine neue Übertragung zu aktivieren. Klicken Sie auf den Namen der Übertragung und dann auf Bearbeiten, um Benachrichtigungen für eine vorhandene Übertragung anzupassen.
Klicken Sie im Abschnitt Benachrichtigungsoptionen auf die Ein-/Aus-Schaltflächen neben den zu aktivierenden Benachrichtigungstypen.
- E-Mail-Benachrichtigungen: Wenn Sie diese Option aktivieren, erhält der Übertragungsadministrator eine E-Mail-Benachrichtigung, wenn eine Übertragung fehlschlägt.
- Pub/Sub-Benachrichtigungen: Wenn Sie diese Option aktivieren, wählen Sie den Namen des Themas aus oder klicken Sie auf Thema erstellen. Mit dieser Option werden Pub/Sub-Ausführungsbenachrichtigungen für Ihre Übertragung konfiguriert.

Java

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Java in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Java API.

Richten Sie zur Authentifizierung bei BigQuery die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für Clientbibliotheken einrichten.

import com.google.api.gax.rpc.ApiException;
import com.google.cloud.bigquery.datatransfer.v1.CreateTransferConfigRequest;
import com.google.cloud.bigquery.datatransfer.v1.DataTransferServiceClient;
import com.google.cloud.bigquery.datatransfer.v1.ProjectName;
import com.google.cloud.bigquery.datatransfer.v1.TransferConfig;
import com.google.protobuf.Struct;
import com.google.protobuf.Value;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;

// Sample to get run notification
public class RunNotification {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    final String datasetId = "MY_DATASET_ID";
    final String pubsubTopicName = "MY_TOPIC_NAME";
    final String query =
        "SELECT CURRENT_TIMESTAMP() as current_time, @run_time as intended_run_time, "
            + "@run_date as intended_run_date, 17 as some_integer";
    Map<String, Value> params = new HashMap<>();
    params.put("query", Value.newBuilder().setStringValue(query).build());
    params.put(
        "destination_table_name_template",
        Value.newBuilder().setStringValue("my_destination_table_{run_date}").build());
    params.put("write_disposition", Value.newBuilder().setStringValue("WRITE_TRUNCATE").build());
    params.put("partitioning_field", Value.newBuilder().build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Scheduled Query Name")
            .setDataSourceId("scheduled_query")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .setNotificationPubsubTopic(pubsubTopicName)
            .build();
    runNotification(projectId, transferConfig);
  }

  public static void runNotification(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient dataTransferServiceClient = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = dataTransferServiceClient.createTransferConfig(request);
      System.out.println(
          "\nScheduled query with run notification created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("\nScheduled query with run notification was not created." + ex.toString());
    }
  }
}

Python

Bevor Sie dieses Beispiel anwenden, folgen Sie den Schritten zur Einrichtung von Python in der BigQuery-Kurzanleitung zur Verwendung von Clientbibliotheken. Weitere Angaben finden Sie in der Referenzdokumentation zur BigQuery Python API.