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 dan bigquery.datasets.update pada set data target
Peran IAM bigquery.admin yang telah ditetapkan mencakup izin bigquery.transfers.update, bigquery.datasets.update, dan bigquery.datasets.get. Untuk mengetahui informasi lebih lanjut tentang peran IAM dalam BigQuery Data Transfer Service, lihat Kontrol akses.
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.

Buka halaman BigQuery
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 atau WRITE_TRUNCATE, lihat Penyerapan data untuk transfer Amazon S3. Untuk mengetahui informasi selengkapnya tentang kolom writeDisposition, lihat JobConfigurationLoad.
- 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, atau ORC. Nilai defaultnya adalah CSV.
- 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 adalah WRITE_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 atau CSV. Apakah Anda akan mengabaikan nilai yang tidak diketahui dalam data Anda.
- field_delimiter: Opsional, dan hanya berlaku jika file_format adalah CSV. 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 adalah 0.
- 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.

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 create amazon s3 transfer config.
public class CreateAmazonS3Transfer {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    final String projectId = "MY_PROJECT_ID";
    String datasetId = "MY_DATASET_ID";
    String tableId = "MY_TABLE_ID";
    // Amazon S3 Bucket Uri with read role permission
    String sourceUri = "s3://your-bucket-name/*";
    String awsAccessKeyId = "MY_AWS_ACCESS_KEY_ID";
    String awsSecretAccessId = "AWS_SECRET_ACCESS_ID";
    String sourceFormat = "CSV";
    String fieldDelimiter = ",";
    String skipLeadingRows = "1";
    Map<String, Value> params = new HashMap<>();
    params.put(
        "destination_table_name_template", Value.newBuilder().setStringValue(tableId).build());
    params.put("data_path", Value.newBuilder().setStringValue(sourceUri).build());
    params.put("access_key_id", Value.newBuilder().setStringValue(awsAccessKeyId).build());
    params.put("secret_access_key", Value.newBuilder().setStringValue(awsSecretAccessId).build());
    params.put("source_format", Value.newBuilder().setStringValue(sourceFormat).build());
    params.put("field_delimiter", Value.newBuilder().setStringValue(fieldDelimiter).build());
    params.put("skip_leading_rows", Value.newBuilder().setStringValue(skipLeadingRows).build());
    TransferConfig transferConfig =
        TransferConfig.newBuilder()
            .setDestinationDatasetId(datasetId)
            .setDisplayName("Your Aws S3 Config Name")
            .setDataSourceId("amazon_s3")
            .setParams(Struct.newBuilder().putAllFields(params).build())
            .setSchedule("every 24 hours")
            .build();
    createAmazonS3Transfer(projectId, transferConfig);
  }

  public static void createAmazonS3Transfer(String projectId, TransferConfig transferConfig)
      throws IOException {
    try (DataTransferServiceClient client = DataTransferServiceClient.create()) {
      ProjectName parent = ProjectName.of(projectId);
      CreateTransferConfigRequest request =
          CreateTransferConfigRequest.newBuilder()
              .setParent(parent.toString())
              .setTransferConfig(transferConfig)
              .build();
      TransferConfig config = client.createTransferConfig(request);
      System.out.println("Amazon s3 transfer created successfully :" + config.getName());
    } catch (ApiException ex) {
      System.out.print("Amazon s3 transfer was not created." + ex.toString());
    }
  }
}

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.