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

Esta página apresenta uma vista geral das notificações de execução do Serviço de transferência de dados do BigQuery.

Existem dois tipos de notificações de execução que pode configurar para o Serviço de transferência de dados do BigQuery:

  • Notificações do Pub/Sub: notificações legíveis por máquina enviadas quando uma execução de transferência é bem-sucedida ou falha
  • Notificações por email: notificações legíveis enviadas quando uma execução de transferência falha

Pode configurar cada tipo individualmente ou usar notificações de execução do Pub/Sub e por email.

Notificações do Pub/Sub

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

  • SUCCEEDED
  • FAILED
  • CANCELLED

Pode enviar notificações para qualquer tópico do Pub/Sub em qualquer projeto para o qual tenha autorizações suficientes. Depois de recebida pelo tópico do Pub/Sub, a mensagem resultante pode ser enviada a qualquer número de subscritores do tópico.

Antes de começar

Antes de configurar as notificações de execução de transferências do Pub/Sub, deve:

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

    Ative a API

  2. Ter autorizações suficientes no projeto que vai receber notificações:

    • Se for proprietário do projeto que vai receber notificações, é muito provável que tenha a autorização necessária.

    • Se planeia criar tópicos para receber notificações, deve ter autorizações pubsub.topics.create.

    • Quer planeie usar tópicos novos ou existentes, deve ter as autorizações pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy. Se criar um tópico, normalmente, já tem autorização para o mesmo. A seguinte função do IAM predefinida tem as autorizações pubsub.topics.getIamPolicy e pubsub.topics.setIamPolicy: pubsub.admin. Consulte o artigo Controlo de acesso do Pub/Sub para mais informações.

  3. Ter um tópico Pub/Sub existente para o qual quer enviar notificações.

Formato de notificação

As notificações enviadas para o tópico Pub/Sub são compostas por duas partes:

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

Atributos

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

Nome do atributo Exemplo Descrição
eventType TRANSFER_RUN_FINISHED O tipo de evento que acabou de ocorrer. TRANSFER_RUN_FINISHED é o único valor possível.
payloadFormat JSON_API_V1 O formato da payload do objeto. JSON_API_V1 é o único valor possível.

Payload

A carga útil é uma string que contém os metadados da execução da transferência. De momento, o tipo de payload não é configurável e é fornecido para acomodar futuras alterações à versão da API.

Tipo de carga útil Descrição
JSON_API_V1 O payload é uma string serializada em JSON UTF-8 que contém a representação de recursos de um TransferRun.

Notificações por email

As notificações por email enviam mensagens de email legíveis por humanos quando uma execução de transferência falha. Estas mensagens são enviadas para o email do administrador de transferência, ou seja, a conta que configurou a transferência. Não pode configurar o conteúdo da mensagem nem o destinatário da mesma.

Se usou uma conta de serviço para autenticar uma configuração de transferência, pode não ter acesso ao email para receber emails de notificação de execução da transferência. Nestes casos, recomendamos que configure as notificações do Pub/Sub para receber notificações de execução de transferências.

Para enviar notificações por email de execuções de transferências a mais utilizadores, configure regras de encaminhamento de email para distribuir as mensagens. Se estiver a usar o Gmail, pode encaminhar automaticamente mensagens do Gmail para outra conta.

A notificação por email é 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 de execuções da execução com falha. Por 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.

Ative ou edite as notificações

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

Consola

  1. Aceda à página do BigQuery na Google Cloud consola.

    Aceda à página do BigQuery

  2. No menu de navegação, clique em Transferências de dados.

  3. 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, de seguida, clique em Editar.

  4. Na secção Opções de notificação, clique nos botões junto aos tipos de notificação que quer ativar.

    • Notificações por email: quando ativa esta opção, o administrador da transferência recebe uma notificação por email quando uma execução da transferência falha.
    • Notificações do Pub/Sub: quando ativa esta opção, escolha o nome do tópico ou clique em Criar um tópico. Esta opção configura notificações executadas pelo Pub/Sub para a transferência.

Java

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 de notificações de execução

Se configurar notificações executadas pelo Pub/Sub, incorre em custos do Pub/Sub. Para mais informações, consulte a página de preços do Pub/Sub.

O que se segue?