Notifikasi operasi BigQuery Data Transfer Service

Halaman ini menyediakan ringkasan notifikasi operasi untuk BigQuery Data Transfer Service.

Ringkasan

Ada dua jenis notifikasi operasi yang dapat Anda konfigurasikan untuk BigQuery Data Transfer Service:

  • Notifikasi Pub/Sub: notifikasi yang dapat dibaca mesin, dikirim saat operasi transfer berhasil atau gagal dijalankan
  • Notifikasi email: notifikasi yang dapat dibaca manusia, dikirim saat operasi transfer gagal dijalankan

Anda dapat mengonfigurasi jenisnya satu demi satu, atau Anda dapat menggunakan notifikasi operasi Pub/Sub dan email sekaligus.

Notifikasi Pub/Sub

Notifikasi Pub/Sub mengirimkan informasi tentang operasi transfer ke topik Pub/Sub. Notifikasi Pub/Sub dipicu oleh operasi transfer yang selesai dalam kondisi berikut:

  • SUCCEEDED
  • FAILED
  • CANCELLED

Anda dapat mengirim notifikasi ke topik Pub/Sub mana pun dalam project apa pun yang izinnya Anda miliki secara memadai. Setelah diterima oleh topik Pub/Sub, pesan yang dihasilkan dapat dikirim ke sejumlah pelanggan topik tersebut.

Sebelum memulai

Sebelum mengonfigurasi notifikasi operasi transfer Pub/Sub, Anda harus:

  1. Mengaktifkan Pub/Sub API untuk project yang akan menerima notifikasi.

    Mengaktifkan API

  2. Memiliki izin yang memadai pada project yang akan menerima notifikasi:

    • Jika Anda memiliki project yang akan menerima notifikasi, kemungkinan besar Anda memiliki izin yang diperlukan.

    • Jika berencana membuat topik untuk menerima notifikasi, Anda harus memiliki izin pubsub.topics.create.

    • Baik rencanda Anda untuk menggunakan topik baru maupun yang lama, Anda harus memiliki izin pubsub.topics.getIamPolicy dan pubsub.topics.setIamPolicy. Jika Anda membuat topik, biasanya Anda sudah memiliki izin untuk itu. Peran IAM yang telah ditetapkan berikut memiliki izin pubsub.topics.getIamPolicy dan pubsub.topics.setIamPolicy: pubsub.admin. Lihat kontrol akses Pub/Sub untuk informasi selengkapnya.

  3. Memiliki topik Pub/Sub yang sudah ada yang ingin Anda kirimi notifikasi.

Format notifikasi

Notifikasi yang dikirim ke topik Pub/Sub terdiri dari dua bagian:

  • Atribut: Kumpulan key:value pair yang mendeskripsikan peristiwa.
  • Payload: String yang berisi metadata objek yang diubah.

Atribut

Atribut adalah key:value pair yang terdapat dalam semua notifikasi yang dikirim oleh BigQuery Data Transfer Service ke topik Pub/Sub Anda. Notifikasi selalu berisi serangkaian key-value pair berikut, terlepas dari payload notifikasi:

Nama atribut Contoh Deskripsi
eventType TRANSFER_RUN_FINISHED Jenis peristiwa yang baru saja terjadi. TRANSFER_RUN_FINISHED adalah satu-satunya nilai yang dapat digunakan.
payloadFormat JSON_API_V1 Format payload objek. JSON_API_V1 adalah satu-satunya nilai yang dapat digunakan.

Payload

Payload adalah string yang berisi metadata operasi transfer. Jenis payload tersebut tidak dapat dikonfigurasi saat ini dan disediakan untuk mengakomodasi perubahan versi API mendatang.

Payload type Deskripsi
JSON_API_V1 Payload akan berupa string yang diserialisasi JSON UTF-8 yang berisi representasi resource TransferRun.

Notifikasi email

Notifikasi email mengirimkan pesan email yang dapat dibaca manusia saat operasi transfer gagal. Pesan tersebut dikirim kepada pengguna yang menyiapkan transfer. Pesan itu tidak dapat dikonfigurasi.

Jika pengguna lain semestinya perlu menerima notifikasi email operasi transfer, siapkan aturan penerusan email untuk mendistribusikan pesan. Jika menggunakan Gmail, Anda dapat Meneruskan pesan Gmail ke akun lain secara otomatis.

Notifikasi email dikirim oleh BigQuery Data Transfer Service dan berisi detail tentang konfigurasi transfer, operasi transfer, dan link ke histori operasi yang gagal. Contoh:

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.

Mengaktifkan notifikasi

Anda dapat mengaktifkan notifikasi dengan:

Konsol

  1. Buka halaman BigQuery di konsol Google Cloud.

    Buka halaman BigQuery

  2. Klik Transfer data di menu navigasi.

  3. Untuk mengaktifkan notifikasi transfer baru, klik Buat transfer. Untuk menyesuaikan notifikasi pada transfer yang ada, klik nama transfer, lalu klik Edit.

  4. Di bagian Opsi Notifikasi, klik tombol di samping jenis notifikasi yang ingin diaktifkan.

    • Notifikasi email: Jika Anda mengaktifkan opsi ini, administrator transfer akan menerima notifikasi email saat operasi transfer gagal.
    • Notifikasi Pub/Sub: Saat Anda mengaktifkan opsi ini, pilih nama topik atau klik Buat topik. Opsi ini mengonfigurasi notifikasi operasi Pub/Sub atas transfer yang dilakukan.

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Java API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien. 

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai BigQuery menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat Dokumentasi referensi BigQuery Python API.

Untuk melakukan autentikasi ke BigQuery, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk library klien. 

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

Harga notifikasi operasi

Jika Anda mengonfigurasi notifikasi operasi Pub/Sub, Anda akan dikenai biaya Pub/Sub. Untuk mengetahui informasi selengkapnya, lihat halaman Harga Pub/Sub.

Langkah selanjutnya