Notifications d'exécution du service de transfert de données BigQuery

Cette page vous offre un aperçu des notifications d'exécution du Service de transfert de données BigQuery.

Présentation

Il existe deux types de notifications d'exécution que vous pouvez configurer pour le Service de transfert de données BigQuery :

• Les notifications Pub/Sub : notifications exploitables par un ordinateur qui sont envoyées lorsqu'une exécution de transfert réussit ou échoue.
• Les notifications par e-mail : notifications lisibles par un humain qui sont envoyées lorsqu'une exécution de transfert échoue.

Vous pouvez configurer chaque type individuellement, ou utiliser à la fois les notifications d'exécution Pub/Sub et celles par e-mail.

Notifications Pub/Sub

Les notifications Pub/Sub envoient des informations sur les exécutions de transfert à un sujet Pub/Sub. Les notifications Pub/Sub sont déclenchées par des transferts terminés dans les états suivants :

• SUCCEEDED
• FAILED
• CANCELLED

Vous pouvez envoyer des notifications à n'importe quel sujet Pub/Sub dans un projet pour lequel vous disposez des autorisations suffisantes. Une fois reçu par le sujet Pub/Sub, le message peut être envoyé à n'importe quel nombre d'abonnés au sujet.

Avant de commencer

Avant de configurer les notifications d'exécution de transfert Pub/Sub, vous devez :

1. Activer l'API Pub/Sub pour le projet qui recevra les notifications.

   Activer l'API

2. Disposer des autorisations suffisantes sur le projet qui recevra les notifications :

   • Si vous êtes propriétaire du projet qui recevra les notifications, vous disposez probablement des autorisations nécessaires.

   • Si vous prévoyez de créer des sujets pour recevoir des notifications, vous devez disposer des autorisations pubsub.topics.create.

   • Si vous prévoyez d'utiliser des sujets nouveaux ou existants, vous devez disposer des autorisations pubsub.topics.getIamPolicy et pubsub.topics.setIamPolicy. Si vous créez un sujet, vous disposez généralement de l'autorisation correspondante. Le rôle Cloud IAM prédéfini suivant inclut les autorisations pubsub.topics.getIamPolicy et pubsub.topics.setIamPolicy : pubsub.admin. Consultez la page Contrôle des accès Pub/Sub pour plus d'informations.

3. Disposer d'un sujet Pub/Sub existant auquel vous souhaitez envoyer des notifications.

Avertissement : Ne supprimez pas l'Agent de service de transfert de données BigQuery à partir du rôle IAM prédéfini pubsub.publisher. La suppression peut entraîner des échecs de notification de publication sur le sujet Pub/Sub.

Attention : Ne spécifiez aucun schéma personnalisé lors de la création du sujet Pub/Sub. La spécification d'un schéma personnalisé peut entraîner l'échec de la publication de la notification.

Format des notifications

Les notifications envoyées au sujet Pub/Sub comprennent deux parties :

• Attributs : ensemble de paires valeur/clé décrivant l'événement
• Charge utile : chaîne contenant les métadonnées de l'objet modifié.

Attributs

Les attributs sont des paires valeur/clé présentes dans toutes les notifications que le service de transfert de données BigQuery envoie à votre sujet Pub/Sub. Les notifications comportent toujours l'ensemble de paires valeur/clé suivant, quelle que soit leur charge utile.

Nom de l'attribut	Exemple	Description
eventType	TRANSFER_RUN_FINISHED	Type d'événement qui vient de se produire. TRANSFER_RUN_FINISHED est la seule valeur possible.
payloadFormat	JSON_API_V1	Format de la charge utile de l'objet. JSON_API_V1 est la seule valeur possible.

Charge utile

La charge utile est une chaîne contenant les métadonnées de l'exécution du transfert. Le type de charge utile n'est pas configurable pour le moment. Il est fourni pour prendre en charge les modifications de la future version de l'API.

Type de charge utile	Description
JSON_API_V1	La charge utile sera une chaîne sérialisée JSON UTF-8 contenant la représentation de ressource d'un TransferRun.

Notifications par e-mail

Les notifications par e-mail envoient des e-mails lisibles par un humain lorsqu'une exécution de transfert échoue. Ces messages sont envoyés à l'utilisateur qui a configuré le transfert. Les e-mails ne sont pas configurables.

Si d'autres utilisateurs doivent recevoir des notifications d'exécution de transfert par e-mail, configurez des règles de transfert d'e-mails pour diffuser les e-mails. Si vous utilisez Gmail, vous pouvez transférer automatiquement les messages Gmail vers un autre compte.

La notification par e-mail est envoyée par le Service de transfert de données BigQuery et contient des détails sur la configuration du transfert, l'exécution du transfert ainsi qu'un lien vers l'historique de l'exécution ayant échoué. Exemple :

From: [e-mail]
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.

Activer les notifications

Vous pouvez activer les notifications en :

Console

1. Accédez à la page "BigQuery" de la console Google Cloud.

   Accéder à la page "BigQuery"

2. Dans le menu de navigation, cliquez sur Transferts de données.

3. Pour activer les notifications pour un nouveau transfert, cliquez sur Créer un transfert. Pour ajuster les notifications d'un transfert existant, cliquez sur le nom du transfert, puis sur Modifier.

4. Dans la section Options de notification, cliquez sur les boutons d'activation/désactivation à côté des types de notifications à activer.

   • Notifications par e-mail : lorsque vous activez cette option, l'administrateur de transfert reçoit une notification par e-mail en cas d'échec de l'exécution du transfert.
   • Notifications Pub/Sub : lorsque vous activez cette option, choisissez le nom de votre sujet ou cliquez sur Créer un sujet. Cette option configure les notifications d'exécution Pub/Sub pour votre transfert.

Java

Avant d'essayer cet exemple, suivez les instructions de configuration pour Java du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Java.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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

Avant d'essayer cet exemple, suivez les instructions de configuration pour Python du guide de démarrage rapide de BigQuery : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence de l'API BigQuery pour Python.

Pour vous authentifier auprès de BigQuery, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez la page Configurer l'authentification pour les bibliothèques clientes.

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}'")

Tarifs de la notification d'exécution

Si vous configurez les notifications d'exécution Pub/Sub, vous devrez payer des frais Pub/Sub. Pour plus d'informations, consultez la page des Tarifs Pub/Sub.

Étapes suivantes

• En savoir plus sur Pub/Sub
• En savoir plus sur la création de sujets Pub/Sub
• Obtenez plus d'informations sur le Service de transfert de données BigQuery.