Notificações de execução do serviço de transferência de dados do BigQuery

Nesta página, você terá uma visão geral das notificações de execução do serviço de transferência de dados do BigQuery.

Há dois tipos de notificações de execução que podem ser configuradas para o serviço de transferência de dados do BigQuery:

Notificações do Pub/Sub: legíveis por máquina, enviadas quando uma execução de transferência é bem-sucedida ou não.
Notificações por e-mail: legíveis por humanos, enviadas quando uma execução de transferência falha.

É possível configurar cada tipo individualmente ou usar as notificações de execução do Pub/Sub e por e-mail.

Notificações do Pub/Sub

As notificações do Pub/Sub enviam informações sobre execuções de transferência para um tópico do Pub/Sub. As notificações de Pub/Sub são acionadas por execuções de transferência concluídas nos seguintes estados:

SUCCEEDED
FAILED
CANCELLED

É possível enviar notificações para qualquer tópico de Pub/Sub em qualquer projeto que tenha permissões suficientes. Uma vez recebida pelo tópico Pub/Sub, a mensagem resultante pode ser enviada para qualquer número de assinantes do tópico.

Antes de começar

Antes de configurar as notificações de execução de transferência do Pub/Sub, faça o seguinte:

Ative a API Pub/Sub para o projeto que receberá notificações.

Ativar a API
Ter permissões suficientes no projeto que receberá as notificações:
- Se você é proprietário do projeto que vai receber as notificações, é provável que tenha a permissão necessária.
- Se você planeja criar tópicos para receber notificações, é preciso ter as permissões pubsub.topics.create.
- Se você planeja usar tópicos novos ou atuais, é preciso ter as permissões pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy. Se você criar um tópico, normalmente já terá permissão para acessá-lo. O papel predefinido do IAM a seguir tem as permissões pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy: pubsub.admin. Consulte Controle de acesso do Pub/Sub para mais informações.
Tenha um tópico do Pub/Sub para onde as notificações serão enviadas.

Formato da notificação

As notificações enviadas ao tópico do Pub/Sub são compostas de duas partes:

Atributos: um conjunto de pares de chave-valor que descreve o evento.
Payload: uma string de caracteres que contém os metadados do objeto alterado.

Atributos

Os atributos são pares de chave-valor contidos em todas as notificações enviadas pelo serviço de transferência de dados do BigQuery ao seu tópico do Pub/Sub. As notificações sempre contêm o seguinte conjunto de pares de chave-valor, independentemente do payload da notificação:

Nome do atributo	Exemplo	Descrição
eventType	`TRANSFER_RUN_FINISHED`	Tipo de evento que acabou de ocorrer. `TRANSFER_RUN_FINISHED` é o único valor possível.
payloadFormat	`JSON_API_V1`	Formato do payload do objeto. `JSON_API_V1` é o único valor possível.

Payload

O payload é uma string que contém os metadados da execução da transferência. O tipo de payload não é configurável neste momento e é fornecido para acomodar mudanças futuras na versão da API.

Tipo de payload	Descrição
JSON_API_V1	O payload será uma string UTF-8 serializada em JSON contendo a representação do recurso de um `TransferRun`.

Notificações por e-mail

As notificações por e-mail enviam mensagens legíveis por humanos quando uma execução de transferência falha. Essas mensagens são enviadas para o e-mail do administrador da transferência: a conta que configurou a transferência. Não é possível configurar o conteúdo da mensagem nem o destinatário dela.

Se você usou uma conta de serviço para autenticar uma configuração de transferência, pode não ter acesso ao e-mail para receber e-mails de notificação de execução de transferência. Nesses casos, recomendamos que você configure as notificações do Pub/Sub para receber notificações de execução de transferência.

Para enviar notificações por e-mail sobre a execução de transferências para mais usuários, configure um e-mail regras de encaminhamento para distribuir as mensagens. Se você estiver usando o Gmail, poderá encaminhar automaticamente mensagens do Gmail para outra conta.

A notificação por e-mail é enviada pelo serviço de transferência de dados do BigQuery e contém detalhes sobre a configuração da transferência, a execução da transferência e um link para o histórico da execução com falha. Exemplo:

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.

Ativar ou editar notificações

Para ativar as notificações ou editar uma existente, escolha uma das seguintes opções:

Console

Acesse a página do BigQuery no console do Google Cloud.

Acesse a página do BigQuery
Clique em Transferências de dados no menu de navegação.
Para ativar as notificações de uma nova transferência, clique em Criar transferência. Para ajustar as notificações de uma transferência existente, clique no nome da transferência e, em seguida, clique em Editar.
Na seção Opções de notificação, clique nos botões ao lado dos tipos de notificação que serão ativados.
- Notificações por e-mail: quando você ativa essa opção, o administrador de transferência recebe uma notificação por e-mail quando uma execução de transferência falha.
- Notificações do Pub/Sub: ao ativar essa opção, escolha o nome do seu tópico ou clique em Criar um tópico. Essa opção configura notificações de execução do Pub/Sub da sua transferência.

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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 testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de 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}'")

Preços das notificações de execução

Se você configurar notificações de execução do Pub/Sub, haverá cobranças. Para mais informações, consulte a página de Preços do Pub/Sub.

A seguir

Saiba mais sobre o Pub/Sub
Saiba mais sobre como criar tópicos do Pub/Sub.
Saiba mais sobre o serviço de transferência de dados do BigQuery.