Notifiche di esecuzione di BigQuery Data Transfer Service

Questa pagina fornisce una panoramica delle notifiche di esecuzione per BigQuery Data Transfer Service.

Esistono due tipi di notifiche di esecuzione che puoi configurare per BigQuery Data Transfer Service:

  • Notifiche Pub/Sub: notifiche leggibili dalla macchina inviate quando l'esecuzione di un trasferimento ha esito positivo o negativo
  • Notifiche via email: notifiche leggibili dall'utente inviate quando l'esecuzione di un trasferimento non riesce

Puoi configurare ogni tipo singolarmente oppure utilizzare sia le notifiche di esecuzione Pub/Sub sia quelle via email.

Notifiche Pub/Sub

Le notifiche Pub/Sub inviano informazioni sulle esecuzioni di trasferimento a un argomento Pub/Sub. Le notifiche Pub/Sub vengono attivate dalle esecuzioni di trasferimento completate nei seguenti stati:

  • SUCCEEDED
  • FAILED
  • CANCELLED

Puoi inviare notifiche a qualsiasi argomento Pub/Sub in qualsiasi progetto per il quale hai le autorizzazioni necessarie. Una volta ricevuto dall'argomento Pub/Sub, il messaggio risultante può essere inviato a un numero qualsiasi di sottoscrittori dell'argomento.

Prima di iniziare

Prima di configurare le notifiche di esecuzione del trasferimento Pub/Sub, devi:

  1. Abilitare l'API Pub/Sub per il progetto che riceverà le notifiche.

    Abilita l'API

  2. Disporre delle autorizzazioni sufficienti per il progetto che riceverà le notifiche:

    • Se sei il proprietario del progetto che riceverà le notifiche, molto probabilmente disponi dell'autorizzazione necessaria.

    • Se prevedi di creare argomenti per ricevere le notifiche, devi disporre delle pubsub.topics.create autorizzazioni.

    • Indipendentemente dal fatto che tu intenda utilizzare argomenti nuovi o esistenti, devi disporre delle autorizzazioni pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy. Se crei un argomento, in genere disponi già dell'autorizzazione per questo. Il seguente ruolo IAM predefinito dispone delle autorizzazioni pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy: pubsub.admin. Per saperne di più, consulta Controllo dell'accesso Pub/Sub.

  3. Avere un argomento Pub/Sub esistente a cui inviare le notifiche.

Formato delle notifiche

Le notifiche inviate all'argomento Pub/Sub sono composte da due parti:

  • Attributi: un set di coppie chiave:valore che descrivono l'evento.
  • Payload: una stringa che contiene i metadati dell'oggetto modificato.

Attributi

Gli attributi sono coppie chiave:valore contenute in tutte le notifiche inviate da BigQuery Data Transfer Service all'argomento Pub/Sub. Le notifiche contengono sempre il seguente set di coppie chiave:valore, indipendentemente dal payload della notifica:

Nome dell'attributo Esempio Descrizione
eventType TRANSFER_RUN_FINISHED Il tipo di evento appena verificatosi. TRANSFER_RUN_FINISHED è l'unico valore possibile.
payloadFormat JSON_API_V1 Il formato del payload dell'oggetto. JSON_API_V1 è l'unico valore possibile.

Payload

Il payload è una stringa che contiene i metadati dell'esecuzione del trasferimento. Al momento, il tipo di payload non è configurabile e viene fornito per adattarsi alle modifiche future della versione dell'API.

Tipo di payload Descrizione
JSON_API_V1 Il payload sarà una stringa con serializzazione JSON UTF-8 contenente la rappresentazione della risorsa di un TransferRun.

Notifiche via email

Le notifiche via email inviano messaggi email leggibili dall'utente quando l'esecuzione di un trasferimento non riesce. Questi messaggi vengono inviati all'indirizzo email dell'amministratore del trasferimento - l'account che ha configurato il trasferimento. Non puoi configurare il contenuto del messaggio né il destinatario del messaggio.

Se hai utilizzato un account di servizio per autenticare una configurazione di trasferimento, potresti non avere accesso all'indirizzo email per ricevere le email di notifica di esecuzione del trasferimento. In questi casi, ti consigliamo di configurare le notifiche Pub/Sub per ricevere le notifiche di esecuzione del trasferimento.

Per inviare notifiche via email di esecuzione del trasferimento a più utenti, configura le regole di inoltro delle email per distribuire i messaggi. Se utilizzi Gmail, puoi Inoltrare automaticamente i messaggi Gmail a un altro account.

La notifica via email viene inviata da BigQuery Data Transfer Service e contiene dettagli sulla configurazione del trasferimento, sull'esecuzione del trasferimento e un link alla cronologia di esecuzione per l'esecuzione non riuscita. Ad esempio:

From: bigquery-data-transfer-service-noreply@google.com
To: TRANSFER_ADMIN
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.

Attivare o modificare le notifiche

Per attivare le notifiche o modificarne una esistente, scegli una delle seguenti opzioni:

Console

  1. Vai alla pagina BigQuery nella Google Cloud console.

    Vai alla pagina BigQuery

  2. Nel menu di navigazione, fai clic su Trasferimenti di dati.

  3. Per attivare le notifiche per un nuovo trasferimento, fai clic su Crea trasferimento. Per modificare le notifiche per un trasferimento esistente, fai clic sul nome del trasferimento e poi su Modifica.

  4. Nella sezione Opzioni di notifica, fai clic sui pulsanti di attivazione/disattivazione accanto ai tipi di notifica da abilitare.

    • Notifiche via email: quando attivi questa opzione, l'amministratore del trasferimento riceve una notifica via email quando l'esecuzione di un trasferimento non riesce.
    • Notifiche Pub/Sub: quando attivi questa opzione, scegli il nome del topic o fai clic su Crea un argomento. Questa opzione configura l'esecuzione delle notifiche di Pub/Sub in relazione al trasferimento.

Java

Prima di provare questo esempio, segui le istruzioni di configurazione Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell' API Java di BigQuery.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

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

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API di BigQuery.Python

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client. 

transfer_config_name = "projects/1234/locations/us/transferConfigs/abcd"
pubsub_topic = "projects/PROJECT-ID/topics/TOPIC-ID"
from google.cloud import bigquery_datatransfer
from google.protobuf import field_mask_pb2

transfer_client = bigquery_datatransfer.DataTransferServiceClient()

transfer_config = bigquery_datatransfer.TransferConfig(name=transfer_config_name)
transfer_config.notification_pubsub_topic = pubsub_topic
update_mask = field_mask_pb2.FieldMask(paths=["notification_pubsub_topic"])

transfer_config = transfer_client.update_transfer_config(
    {"transfer_config": transfer_config, "update_mask": update_mask}
)

print(f"Updated config: '{transfer_config.name}'")
print(f"Notification Pub/Sub topic: '{transfer_config.notification_pubsub_topic}'")

Prezzi delle notifiche di esecuzione

Se configuri le notifiche di esecuzione Pub/Sub, ti verranno addebitati i costi di Pub/Sub. Per saperne di più, consulta la pagina Prezzi di Pub/Sub.

Passaggi successivi