Notificaciones de ejecución del Servicio de transferencia de datos de BigQuery

En esta página, se proporciona una descripción general de las notificaciones de ejecución del Servicio de transferencia de datos de BigQuery.

Descripción general

Hay dos tipos de notificaciones de ejecución que puedes configurar para el Servicio de transferencia de datos de BigQuery:

Notificaciones de Pub/Sub: Notificaciones que pueden leer las máquinas que se envían cuando una ejecución de transferencia se realiza de manera correcta o falla
Notificaciones por correo electrónico: Notificaciones que puede leer un ser humano que se envían cuando falla una ejecución de transferencia

Puedes configurar cada tipo de forma individual o usar las notificaciones de ejecución de Pub/Sub y de correo electrónico.

Notificaciones de Pub/Sub

Mediante las notificaciones de Pub/Sub, se envía información sobre ejecuciones de transferencias a un tema de Pub/Sub. Las notificaciones de Pub/Sub se activan mediante ejecuciones de transferencias completas en los siguientes estados:

SUCCEEDED
FAILED
CANCELLED

Puedes enviar notificaciones a cualquier tema de Pub/Sub en cualquier proyecto para el que tengas los permisos requeridos. Una vez que el tema de Pub/Sub recibe una notificación, el mensaje resultante se puede enviar a cualquier cantidad de suscriptores del tema.

Antes de comenzar

Antes de configurar las notificaciones de ejecución de transferencias de Pub/Sub, debes hacer lo siguiente:

Habilitar la API de Pub/Sub para el proyecto que recibirá notificaciones.

Habilitar la API
Obtén los permisos necesarios en el proyecto que recibirá notificaciones:
- Si eres propietario del proyecto que recibirá notificaciones, lo más probable es que tengas el permiso necesario.
- Si planeas crear temas para recibir notificaciones, debes tener los permisos pubsub.topics.create.
- Si planeas usar temas nuevos o existentes, debes tener los permisos pubsub.topics.getIamPolicy y pubsub.topics.setIamPolicy. Si creas un tema, sueles tener permiso para él. El siguiente rol predefinido de IAM tiene los permisos pubsub.topics.getIamPolicy y pubsub.topics.setIamPolicy: pubsub.admin. Consulta la sección Control de acceso con Pub/Sub para obtener más información.
Obtén un tema de Pub/Sub existente al que desees enviar notificaciones.

Formato de las notificaciones

Las notificaciones enviadas al tema de Pub/Sub constan de dos partes:

Atributos: Un conjunto de pares clave-valor que describen el evento
Carga útil: Una string que contiene los metadatos del objeto modificado

Atributos

Los atributos son pares clave-valor incluidos en todas las notificaciones que el Servicio de transferencia de datos de BigQuery envía a tu tema de Pub/Sub. Las notificaciones siempre contienen el siguiente conjunto de pares clave-valor, sin importar la carga útil de la notificación:

Nombre del atributo	Ejemplo	Descripción
eventType	`TRANSFER_RUN_FINISHED`	El tipo de evento que acaba de ocurrir. `TRANSFER_RUN_FINISHED` es el único valor posible.
payloadFormat	`JSON_API_V1`	El formato de la carga útil del objeto. `JSON_API_V1` es el único valor posible.

Carga útil

La carga útil es una string que contiene los metadatos de la ejecución de transferencia. El tipo de carga útil no se puede configurar en este momento y se proporciona para adaptarse a futuros cambios en la versión de la API.

Tipo de carga útil	Descripción
JSON_API_V1	La carga útil será una string UTF-8 JSON serializada que contiene la representación de recursos de una `TransferRun`.

Notificaciones por correo electrónico

Las notificaciones por correo electrónico envían mensajes de correo electrónico legibles cuando falla una ejecución de transferencia. Estos mensajes se envían al usuario que configuró la transferencia. Los mensajes no se pueden configurar.

Si otros usuarios deben recibir notificaciones por correo electrónico sobre la ejecución de transferencias, configura las reglas de reenvío de correo electrónico para distribuir los mensajes. Si usas Gmail, puedes reenviar de manera automática mensajes de Gmail a otras cuentas.

La notificación por correo electrónico se envía mediante el Servicio de transferencia de datos de BigQuery y contiene detalles sobre la configuración de la transferencia, la ejecución de la transferencia y un vínculo que va al historial de ejecuciones para la ejecución con errores. Por ejemplo:

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.

Activar notificaciones

Para activar las notificaciones, haz lo siguiente:

Consola

Ve a la página de BigQuery en la consola de Google Cloud.

Ir a la página de BigQuery
Haz clic en Transferencias de datos en el menú de navegación.
Para activar las notificaciones de una transferencia nueva, haz clic en Crear transferencia. Para ajustar las notificaciones de una transferencia existente, haz clic en el nombre de la transferencia y, luego, en Editar.
En la sección Opciones de notificación, haz clic en los botones de activar o desactivar junto a los tipos de notificaciones que deseas habilitar.
- Notificaciones por correo electrónico: Cuando habilitas esta opción, el administrador de transferencias recibe una notificación por correo electrónico cuando falla una ejecución de transferencia.
- Notificaciones de Pub/Sub: Cuando habilitas esta opción, elige el nombre de tu tema o haz clic en Crear un tema. Esta opción configura las notificaciones de ejecución de Pub/Sub para tu transferencia.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

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

Precios de las notificaciones de ejecución

Si configuras las notificaciones de ejecución de Pub/Sub, se generarán cargos de Pub/Sub. Para obtener más información, consulta la página de Precios de Pub/Sub.

¿Qué sigue?

Obtén más información sobre Pub/Sub.
Obtén más información sobre la creación de temas de Pub/Sub.
Más información acerca del Servicio de transferencia de datos de BigQuery.