Transfer Amazon S3
BigQuery Data Transfer Service untuk Amazon S3 memungkinkan Anda menjadwalkan dan mengelola tugas pemuatan berulang secara otomatis dari Amazon S3 ke BigQuery.
Sebelum memulai
Sebelum membuat transfer Amazon S3:
- Pastikan Anda telah menyelesaikan semua tindakan yang diperlukan untuk mengaktifkan BigQuery Data Transfer Service.
- Buat set data BigQuery untuk menyimpan data Anda.
- Buat tabel tujuan untuk transfer Anda dan tentukan definisi skema. Tabel tujuan harus mengikuti aturan penamaan tabel. Nama tabel tujuan juga mendukung parameter.
- Ambil URI Amazon S3, ID kunci akses, dan kunci akses rahasia Anda. Untuk mendapatkan informasi tentang cara mengelola kunci akses, lihat dokumentasi AWS.
- Jika ingin menyiapkan notifikasi operasi transfer untuk Pub/Sub, Anda
harus memiliki izin
pubsub.topics.setIamPolicy
. Izin Pub/Sub tidak diperlukan jika Anda baru saja menyiapkan notifikasi email. Untuk mengetahui informasi selengkapnya, lihat Notifikasi operasi BigQuery Data Transfer Service.
Batasan
Transfer Amazon S3 tunduk pada batasan-batasan berikut:
- Bagian bucket URI Amazon S3 tidak dapat diparameterisasi.
- Transfer dari Amazon S3 dengan parameter Write disposition yang disetel ke
WRITE_TRUNCATE
akan mentransfer semua file yang cocok ke Google Cloud selama setiap operasi. Hal ini dapat mengakibatkan biaya transfer data keluar Amazon S3 tambahan. Untuk informasi selengkapnya tentang file yang ditransfer selama proses run, lihat Dampak pencocokan awalan dibandingkan pencocokan karakter pengganti. - Transfer dari region AWS GovCloud (
us-gov
) tidak didukung. - Transfer ke lokasi BigQuery Omni tidak didukung.
Bergantung pada format data sumber Amazon S3, mungkin ada batasan-batasan tambahan. Untuk informasi selengkapnya, lihat:
Waktu interval minimum antar-transfer berulang adalah 24 jam. Interval default untuk transfer berulang adalah 24 jam.
Izin yang diperlukan
Sebelum membuat transfer Amazon S3:
Pastikan orang yang melakukan transfer memiliki izin yang diperlukan berikut di BigQuery:
- Izin
bigquery.transfers.update
untuk membuat transfer - Izin
bigquery.datasets.get
danbigquery.datasets.update
pada set data target
Peran IAM
bigquery.admin
yang telah ditetapkan mencakup izinbigquery.transfers.update
,bigquery.datasets.update
, danbigquery.datasets.get
. Untuk mengetahui informasi lebih lanjut tentang peran IAM dalam BigQuery Data Transfer Service, lihat Kontrol akses.- Izin
Lihat dokumentasi untuk Amazon S3 guna memastikan Anda telah mengonfigurasi izin yang diperlukan untuk mengaktifkan transfer. Setidaknya, data sumber Amazon S3 harus menerapkan kebijakan yang dikelola AWS
AmazonS3ReadOnlyAccess
pada data tersebut.
Menyiapkan transfer data Amazon S3
Untuk membuat transfer data Amazon S3:
Konsol
Buka halaman BigQuery di konsol Google Cloud.
Klik Transfers.
Klik Create a Transfer.
Di halaman Create Transfer:
Di bagian Source type, untuk Source, pilih Amazon S3.
Di bagian Transfer config name, untuk Display name, masukkan nama untuk transfer, misalnya
My Transfer
. Nama transfer dapat berupa nilai apa pun yang memungkinkan Anda mengidentifikasi transfer dengan mudah jika perlu mengubahnya nanti.Di bagian Schedule options:
Pilih Repeat frequency. Jika memilih Jam, Hari, Minggu, atau Bulan, Anda juga harus menentukan frekuensinya. Anda juga dapat memilih Custom untuk membuat frekuensi pengulangan yang lebih spesifik. Jika Anda memilih On-demand, transfer ini hanya akan berjalan saat Anda memicu transfer secara manual.
Jika perlu, pilih Start now atau Start at set time dan masukkan tanggal mulai dan waktu proses.
Di bagian Destination settings, untuk Destination dataset, pilih set data yang Anda buat untuk menyimpan data.
Di bagian Data source details:
- Untuk Destination table, masukkan nama tabel yang Anda buat untuk menyimpan data di BigQuery. Nama tabel tujuan mendukung parameter.
- Untuk Amazon S3 URI, masukkan URI dalam format berikut
s3://mybucket/myfolder/...
. URI juga mendukung parameter. - Untuk Access key ID, masukkan ID kunci akses Anda.
- Untuk Secret access key, masukkan kunci akses rahasia Anda.
- Untuk File format, pilih format data Anda: newline delimited JSON, CSV, Avro, Parquet, atau ORC.
Untuk Write Disposition, pilih:
WRITE_APPEND
untuk menambahkan data baru secara bertahap ke tabel tujuan yang ada.WRITE_APPEND
adalah nilai default untuk preferensi Tulis.WRITE_TRUNCATE
untuk menimpa data di tabel tujuan selama setiap operasi transfer.
Untuk mengetahui informasi selengkapnya tentang cara BigQuery Data Transfer Service menyerap data menggunakan
WRITE_APPEND
atauWRITE_TRUNCATE
, lihat Penyerapan data untuk transfer Amazon S3. Untuk mengetahui informasi selengkapnya tentang kolomwriteDisposition
, lihatJobConfigurationLoad
.
Di bagian Transfer options - all format:
- Untuk Number of errors allowed, masukkan nilai bilangan bulat untuk jumlah maksimum data buruk yang dapat diabaikan.
- (Opsional) Untuk Decimal target types, masukkan daftar yang dipisahkan koma
dari kemungkinan jenis data SQL yang dapat dikonversi menjadi nilai desimal sumber. Jenis data SQL yang dipilih untuk konversi
bergantung pada kondisi berikut:
- Jenis data yang dipilih untuk konversi akan menjadi jenis data pertama dalam daftar berikut yang mendukung presisi dan skala data sumber, dalam urutan ini: NUMERIC, BIGNUMERIC, dan STRING.
- Jika tidak satu pun dari jenis data yang tercantum akan mendukung presisi dan skala, jenis data yang mendukung rentang terluas dalam daftar yang ditentukan akan dipilih. Jika nilai melebihi rentang yang didukung saat membaca data sumber, error akan ditampilkan.
- Jenis data STRING mendukung semua nilai presisi dan skala.
- Jika kolom ini dibiarkan kosong, jenis data akan ditetapkan secara default ke "NUMERIC,STRING" untuk ORC, dan "NUMERIC" untuk format file lainnya.
- Kolom ini tidak boleh berisi jenis data duplikat.
- Urutan jenis data yang Anda cantumkan dalam kolom ini akan diabaikan.
Jika Anda memilih CSV atau JSON sebagai format file, di bagian JSON,CSV, centang Abaikan nilai yang tidak diketahui untuk menerima baris yang berisi nilai yang tidak cocok dengan skema. Nilai yang tidak diketahui akan diabaikan. Untuk file CSV, opsi ini mengabaikan nilai tambahan di akhir baris.
Jika Anda memilih CSV sebagai format file, di bagian CSV, masukkan CSV options tambahan untuk memuat data.
Di menu Service Account, pilih service account dari akun layanan yang terkait dengan project Google Cloud Anda. Anda dapat mengaitkan akun layanan dengan transfer Anda, bukan menggunakan kredensial pengguna. Untuk mengetahui informasi selengkapnya tentang cara menggunakan akun layanan dengan transfer data, lihat Menggunakan akun layanan.
- Jika Anda login dengan identitas gabungan, akun layanan diperlukan untuk membuat transfer. Jika Anda login dengan Akun Google, akun layanan untuk transfer bersifat opsional.
- Akun layanan harus memiliki izin yang diperlukan.
(Opsional) Di bagian Notification options:
- Klik tombol untuk mengaktifkan notifikasi email. Saat Anda mengaktifkan opsi ini, administrator transfer akan menerima notifikasi email saat proses transfer gagal.
- Untuk Select a Pub/Sub topic, pilih nama topik atau klik Create a topic untuk membuatnya. Opsi ini mengonfigurasi notifikasi operasi Pub/Sub untuk transfer Anda.
Klik Save.
bq
Masukkan perintah bq mk
dan berikan flag pembuatan transfer —
--transfer_config
.
bq mk \ --transfer_config \ --project_id=project_id \ --data_source=data_source \ --display_name=name \ --target_dataset=dataset \ --service_account_name=service_account \ --params='parameters'
Dengan keterangan:
- project_id: Opsional. Project ID Google Cloud Anda.
Jika
--project_id
tidak diberikan untuk menentukan project tertentu, project default akan digunakan. - data_source: Wajib diisi. Sumber data —
amazon_s3
. - display_name: Wajib diisi. Nama tampilan untuk konfigurasi transfer. Nama transfer dapat berupa nilai apa pun yang memungkinkan Anda mengidentifikasi transfer jika Anda perlu mengubahnya nanti.
- dataset: Wajib diisi. Set data target untuk konfigurasi transfer.
- service_account: Nama akun layanan yang digunakan untuk mengautentikasi transfer Anda. Akun layanan harus
dimiliki oleh
project_id
yang sama dengan yang digunakan untuk membuat transfer dan harus memiliki semua izin yang diperlukan. parameters: Wajib diisi. Parameter untuk konfigurasi transfer yang dibuat dalam format JSON. Sebagai contoh:
--params='{"param":"param_value"}'
. Berikut adalah parameter untuk transfer Amazon S3:- destination_table_name_template: Wajib diisi. Nama tabel tujuan Anda.
data_path: Wajib diisi. Amazon S3 URI, dalam format berikut:
s3://mybucket/myfolder/...
URI juga mendukung parameter.
access_key_id: Wajib diisi. ID kunci akses Anda.
secret_access_key: Wajib diisi. Kunci akses rahasia Anda.
file_format: Opsional. Menunjukkan jenis file yang ingin Anda transfer:
CSV
,JSON
,AVRO
,PARQUET
, atauORC
. Nilai defaultnya adalahCSV
.write_disposition: Opsional.
WRITE_APPEND
hanya akan mentransfer file yang telah diubah sejak eksekusi sebelumnya berhasil.WRITE_TRUNCATE
akan mentransfer semua file yang cocok, termasuk file yang ditransfer pada proses sebelumnya. Defaultnya adalahWRITE_APPEND
.max_bad_records: Opsional. Jumlah catatan buruk yang diizinkan. Defaultnya adalah
0
.decimal_target_types: Opsional. Daftar yang dipisahkan koma dari kemungkinan jenis data SQL yang dapat dikonversi oleh nilai desimal sumber. Jika kolom ini tidak diisi, jenis data akan ditetapkan secara default ke "NUMERIC,STRING" untuk ORC, dan "NUMERIC" untuk format file lainnya.
ignore_unknown_values: Opsional, dan diabaikan jika file_format bukan
JSON
atauCSV
. Apakah Anda akan mengabaikan nilai yang tidak diketahui dalam data Anda.field_delimiter: Opsional, dan hanya berlaku jika
file_format
adalahCSV
. Karakter yang memisahkan kolom. Nilai defaultnya adalah koma.skip_leading_rows: Opsional, dan hanya berlaku jika file_format adalah
CSV
. Menunjukkan jumlah baris header yang tidak ingin Anda impor. Nilai defaultnya adalah0
.allow_quoted_newlines: Opsional, dan hanya berlaku jika file_format adalah
CSV
. Menunjukkan apakah akan mengizinkan baris baru dalam kolom yang dikutip atau tidak.allow_jagged_rows: Opsional, dan hanya berlaku jika file_format adalah
CSV
. Menunjukkan apakah akan menerima baris yang tidak memiliki kolom opsional di akhir. Nilai-nilai yang tidak diisi akan diisi dengan NULL.
Misalnya, perintah berikut akan membuat transfer Amazon S3 bernama
My Transfer
menggunakan nilai data_path
dari
s3://mybucket/myfile/*.csv
, set data target mydataset
, dan file_format
CSV
. Contoh ini mencakup nilai non-default untuk parameter opsional
yang terkait dengan file_format CSV
.
Transfer dibuat di project default:
bq mk --transfer_config \
--target_dataset=mydataset \
--display_name='My Transfer' \
--params='{"data_path":"s3://mybucket/myfile/*.csv",
"destination_table_name_template":"MyTable",
"file_format":"CSV",
"write_disposition":"WRITE_APPEND",
"max_bad_records":"1",
"ignore_unknown_values":"true",
"field_delimiter":"|",
"skip_leading_rows":"1",
"allow_quoted_newlines":"true",
"allow_jagged_rows":"false"}' \
--data_source=amazon_s3
Setelah menjalankan perintah, Anda akan menerima pesan seperti berikut:
[URL omitted] Please copy and paste the above URL into your web browser and
follow the instructions to retrieve an authentication code.
Ikuti petunjuknya, lalu tempel kode autentikasi di command line.
API
Gunakan metode projects.locations.transferConfigs.create
dan berikan instance resource TransferConfig
.
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.
Dampak pencocokan imbuhan versus pencocokan karakter pengganti
Amazon S3 API mendukung pencocokan awalan, tetapi tidak mendukung pencocokan karakter pengganti. Semua file Amazon S3 yang cocok dengan awalan akan ditransfer ke Google Cloud. Namun, hanya URL yang cocok dengan Amazon S3 URI dalam konfigurasi transfer yang akan benar-benar dimuat ke BigQuery. Hal ini dapat mengakibatkan kelebihan biaya transfer data keluar Amazon S3 untuk file yang ditransfer, tetapi tidak dimuat ke BigQuery.
Sebagai contoh, pertimbangkan jalur data ini:
s3://bucket/folder/*/subfolder/*.csv
Bersama dengan file ini di lokasi sumber:
s3://bucket/folder/any/subfolder/file1.csv
s3://bucket/folder/file2.csv
Tindakan ini akan menyebabkan semua file Amazon S3 dengan awalan s3://bucket/folder/
ditransfer ke Google Cloud. Dalam contoh ini, file1.csv
dan
file2.csv
akan ditransfer.
Namun, hanya file yang cocok dengan s3://bucket/folder/*/subfolder/*.csv
yang akan benar-benar dimuat ke BigQuery. Dalam contoh ini, hanya file1.csv
yang akan dimuat ke BigQuery.
Memecahkan masalah penyiapan transfer
Jika Anda mengalami masalah saat menyiapkan transfer, lihat masalah transfer Amazon S3.
Langkah selanjutnya
- Untuk pengantar transfer Amazon S3, lihat Ringkasan transfer Amazon S3
- Untuk ringkasan BigQuery Data Transfer Service, lihat Pengantar BigQuery Data Transfer Service.
- Untuk informasi cara menggunakan transfer, termasuk mendapatkan informasi tentang konfigurasi transfer, membuat listingan konfigurasi transfer, dan melihat histori pelaksanaan transfer, lihat Menangani transfer.
- Pelajari cara memuat data dengan operasi lintas-cloud.