Mengimpor file Avro Spanner

Halaman ini menjelaskan cara mengimpor database Spanner ke Spanner menggunakan the Google Cloud konsol. Untuk mengimpor file Avro dari sumber lain, lihat Mengimpor data dari database non-Spanner.

Proses ini menggunakan Dataflow; proses ini mengimpor data dari folder bucket Cloud Storage yang berisi kumpulan file Avro dan file manifes JSON. Proses impor hanya mendukung file Avro yang diekspor dari Spanner.

Untuk mengimpor database Spanner menggunakan REST API atau gcloud CLI, selesaikan langkah-langkah di bagian Sebelum memulai di halaman ini, lalu lihat petunjuk mendetail di Cloud Storage Avro ke Spanner.

Sebelum memulai

Untuk mengimpor database Spanner, Anda harus mengaktifkan Spanner, Cloud Storage, Compute Engine, dan Dataflow API terlebih dahulu:

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

Aktifkan API

Anda juga memerlukan kuota yang cukup dan izin IAM yang diperlukan.

Persyaratan kuota

Persyaratan kuota untuk tugas impor adalah sebagai berikut:

• Spanner: Anda harus memiliki kapasitas komputasi yang cukup untuk mendukung jumlah data yang Anda impor. Tidak ada kapasitas komputasi tambahan yang diperlukan untuk mengimpor database, meskipun Anda mungkin perlu menambahkan lebih banyak kapasitas komputasi agar tugas Anda selesai dalam waktu yang wajar. Lihat Mengoptimalkan tugas untuk mengetahui detail selengkapnya.
• Cloud Storage: Untuk mengimpor, Anda harus memiliki bucket yang berisi file yang sebelumnya diekspor. Anda tidak perlu menetapkan ukuran untuk bucket.
• Dataflow: Tugas impor tunduk pada kuota Compute Engine yang sama untuk CPU, penggunaan disk, dan alamat IP seperti tugas Dataflow lainnya.

• Compute Engine: Sebelum menjalankan tugas impor, Anda harus menyiapkan kuota awal untuk Compute Engine, yang digunakan Dataflow. Kuota ini mewakili jumlah maksimum resource yang Anda izinkan untuk digunakan Dataflow bagi tugas Anda. Nilai awal yang direkomendasikan adalah:

  • CPU: 200
  • Alamat IP yang digunakan: 200
  • Persistent disk standar: 50 TB

  Umumnya, Anda tidak perlu melakukan penyesuaian lainnya. Dataflow menyediakan penskalaan otomatis sehingga Anda hanya membayar resource aktual yang digunakan selama impor. Jika tugas Anda dapat menggunakan lebih banyak resource, UI Dataflow akan menampilkan ikon peringatan. Tugas akan selesai meskipun ada ikon peringatan.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengekspor database, minta administrator untuk memberi Anda peran IAM berikut di akun layanan worker Dataflow Anda:

• Cloud Spanner Viewer (roles/spanner.viewer)
• Dataflow Worker (roles/dataflow.worker)
• Storage Admin (roles/storage.admin)
• Spanner Database Reader (roles/spanner.databaseReader)
• Database Admin (roles/spanner.databaseAdmin)

Catatan: Peran Spanner Database Admin hanya diperlukan untuk tugas impor.

Opsional: Temukan folder database Anda di Cloud Storage

Untuk menemukan folder yang berisi database yang diekspor di Google Cloud konsol, buka browser Cloud Storage dan klik bucket yang berisi folder yang diekspor.

Buka browser Cloud Storage

Nama folder yang berisi data yang diekspor dimulai dengan ID instance, nama database, dan stempel waktu tugas ekspor Anda. Folder ini berisi:

• File spanner-export.json.
• File TableName-manifest.json untuk setiap tabel di database yang Anda ekspor.

• Satu atau beberapa TableName.avro-#####-of-##### file. Angka pertama dalam ekstensi .avro-#####-of-##### mewakili indeks file Avro, dimulai dari nol, dan angka kedua mewakili jumlah file Avro yang dibuat untuk setiap tabel.

  Misalnya, Songs.avro-00001-of-00002 adalah file kedua dari dua file yang berisi data untuk tabel Songs.

• File ChangeStreamName-manifest.json untuk setiap aliran perubahan di database yang Anda ekspor.

• File untuk setiap aliran perubahan.ChangeStreamName.avro-00000-of-00001 File ini berisi data kosong dengan hanya skema Avro dari aliran perubahan.

Mengimpor database

Untuk mengimpor database Spanner dari Cloud Storage ke instance Anda, ikuti langkah-langkah berikut.

1. Buka halaman Instances Spanner.

   Buka halaman instance

2. Klik nama instance yang akan berisi database yang diimpor.

3. Klik item menu Import/Export di panel kiri, lalu klik tombol Import.

4. Di bagian Choose a source folder, klik Browse.

5. Temukan bucket yang berisi ekspor Anda dalam daftar awal, atau klik Search untuk memfilter daftar dan menemukan bucket. Klik dua kali bucket untuk melihat folder yang ada di dalamnya.

6. Temukan folder dengan file yang diekspor, lalu klik untuk memilihnya.

   Catatan: Pastikan untuk memilih folder yang dibuat oleh tugas ekspor, bukan folder tingkat yang lebih tinggi yang berisi folder yang diekspor.

7. Klik Select.

8. Masukkan nama untuk database baru, yang dibuat Spanner selama proses impor. Nama database tidak boleh sudah ada di instance Anda.

9. Pilih dialek untuk database baru (GoogleSQL atau PostgreSQL).

10. (Opsional) Untuk melindungi database baru dengan kunci enkripsi yang dikelola pelanggan, klik Show encryption options , lalu pilih Use a customer-managed encryption key (CMEK). Kemudian, pilih kunci dari menu drop-down.

11. Pilih region di menu drop-down Choose a region for the import job.

    Catatan: Untuk menghindari biaya transfer data keluar, pilih region yang tumpang-tindih dengan lokasi bucket Cloud Storage Anda. Lihat Memilih region di bawah untuk mengetahui informasi selengkapnya.

12. (Opsional) Untuk mengenkripsi status pipeline Dataflow dengan kunci enkripsi yang dikelola pelanggan, klik Show encryption options , lalu pilih Use a customer-managed encryption key (CMEK). Kemudian, pilih kunci dari menu drop-down.

13. Centang kotak di bagian Confirm charges untuk mengonfirmasi bahwa ada biaya selain biaya yang ditagih oleh instance Spanner Anda yang ada.

14. Klik Import.

    Konsol menampilkan halaman Database details, yang kini menampilkan kotak yang menjelaskan tugas impor Anda, termasuk waktu yang berlalu untuk tugas tersebut: Google Cloud

    

Saat tugas selesai atau dihentikan, Google Cloud konsol akan menampilkan pesan di halaman Database details. Jika tugas berhasil, pesan keberhasilan akan muncul:

Catatan: Setelah tugas impor Dataflow berhasil diselesaikan, Spanner akan membuat indeks dan kunci asing untuk database yang diimpor. Saat pembuatan indeks sedang berlangsung, konsol akan menampilkan ikon sedang berlangsung untuk menunjukkan bahwa operasi yang berjalan lama sedang terjadi. Google Cloud Ikon ini berada di samping nama indeks, dalam hierarki database di sebelah kiri halaman Database details. Saat ikon sedang berlangsung berubah menjadi ikon indeks , pembuatan indeks tersebut akan selesai. Anda dapat membuat kueri SPANNER_STATE di tampilan INFORMATION_SCHEMA.REFERENTIAL_CONSTRAINTS untuk melihat progres pembuatan kunci asing.

Jika tugas tidak berhasil, pesan kegagalan akan muncul:

Jika tugas Anda gagal, periksa log Dataflow tugas untuk mengetahui detail error dan lihat Memecahkan masalah tugas impor yang gagal.

Catatan tentang mengimpor kolom yang dihasilkan dan aliran perubahan

Spanner menggunakan definisi setiap kolom yang dihasilkan dalam skema Avro untuk membuat ulang kolom tersebut. Spanner menghitung nilai kolom yang dihasilkan secara otomatis selama impor.

Demikian pula, Spanner menggunakan definisi setiap aliran perubahan dalam skema Avro untuk membuatnya ulang selama impor. Data aliran perubahan tidak diekspor maupun diimpor melalui Avro, sehingga semua aliran perubahan yang terkait dengan database yang baru diimpor tidak akan memiliki data perubahan.

Catatan tentang mengimpor urutan

Setiap urutan (GoogleSQL, PostgreSQL) yang diekspor Spanner menggunakan fungsi GET_INTERNAL_SEQUENCE_STATE() (GoogleSQL, PostgreSQL) untuk mengambil statusnya saat ini. Spanner menambahkan buffer 1000 ke penghitung, dan menulis nilai penghitung baru ke properti kolom rekaman. Perhatikan bahwa ini hanyalah pendekatan upaya terbaik untuk menghindari error nilai duplikat yang mungkin terjadi setelah impor. Sesuaikan penghitung urutan sebenarnya jika ada lebih banyak penulisan ke database sumber selama ekspor data.

Saat impor, urutan dimulai dari penghitung baru ini, bukan penghitung yang ditemukan dalam skema. Jika perlu, Anda dapat menggunakan pernyataan ALTER SEQUENCE (GoogleSQL, PostgreSQL) untuk mengupdate ke penghitung baru.

Catatan tentang mengimpor tabel yang disisipkan dan kunci asing

Tugas Dataflow dapat mengimpor tabel yang disisipkan, sehingga Anda dapat mempertahankan hubungan induk-turunan dari file sumber. Namun, batasan kunci asing tidak diterapkan selama pemuatan data. Tugas Dataflow membuat semua kunci asing yang diperlukan setelah pemuatan data selesai.

Jika Anda memiliki batasan kunci asing pada database Spanner sebelum impor dimulai, Anda mungkin mengalami error tulis karena pelanggaran integritas referensial. Untuk menghindari error tulis, sebaiknya hapus kunci asing yang ada sebelum memulai proses impor.

Memilih region untuk tugas impor

Anda mungkin ingin memilih region yang berbeda berdasarkan lokasi bucket Cloud Storage. Untuk menghindari biaya transfer data keluar, pilih region yang cocok dengan lokasi bucket Cloud Storage Anda.

• Jika lokasi bucket Cloud Storage Anda adalah region, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih region yang sama untuk tugas impor, dengan asumsi region tersebut tersedia.

• Jika lokasi bucket Cloud Storage Anda adalah region ganda, Anda dapat memanfaatkan penggunaan jaringan gratis dengan memilih salah satu dari dua region yang membentuk region ganda untuk tugas impor, dengan asumsi salah satu region tersedia.

• Jika region yang sama tidak tersedia untuk tugas impor Anda, atau jika lokasi bucket Cloud Storage Anda adalah multi-region, biaya transfer data keluar akan berlaku. Lihat Harga transfer data Cloud Storage untuk memilih region yang dikenakan biaya transfer data terendah.

Melihat atau memecahkan masalah tugas di UI Dataflow

Setelah memulai tugas impor, Anda dapat melihat detail tugas, termasuk log, di bagian Dataflow Google Cloud konsol.

Melihat detail tugas Dataflow

Untuk melihat detail tugas impor atau ekspor yang Anda jalankan dalam seminggu terakhir, termasuk tugas yang sedang berjalan:

1. Buka halaman Database overview untuk database.
2. Klik item menu panel kiri Import/Export. Halaman Import/Export database menampilkan daftar tugas terbaru.

3. Di halaman Import/Export database, klik nama tugas di kolom Dataflow job name:

   

   Konsol menampilkan detail tugas Dataflow . Google Cloud

Untuk melihat tugas yang Anda jalankan lebih dari seminggu yang lalu:

1. Buka halaman tugas Dataflow di Google Cloud konsol.

   Buka Tugas

2. Temukan tugas Anda dalam daftar, lalu klik namanya.

   Konsol menampilkan detail tugas Dataflow . Google Cloud

Catatan: Tugas dengan jenis yang sama untuk database yang sama memiliki nama yang sama. Anda dapat membedakan tugas berdasarkan nilai di kolom Start time atau End time.

Melihat log Dataflow untuk tugas Anda

Untuk melihat log tugas Dataflow, buka halaman detail tugas, lalu klik Logs di sebelah kanan nama tugas.

Jika tugas gagal, cari error dalam log. Jika ada error, jumlah error akan ditampilkan di samping Logs:

Untuk melihat error tugas:

1. Klik jumlah error di samping Logs.

   Konsol menampilkan log tugas. Google Cloud Anda mungkin perlu men-scroll untuk melihat error.

2. Temukan entri dengan ikon error .

3. Klik setiap entri log untuk meluaskan kontennya.

Untuk mengetahui informasi selengkapnya tentang pemecahan masalah tugas Dataflow, lihat Memecahkan masalah pipeline.

Memecahkan masalah tugas impor yang gagal

Jika Anda melihat error berikut di log tugas:

com.google.cloud.spanner.SpannerException: NOT_FOUND: Session not found

--or--

com.google.cloud.spanner.SpannerException: DEADLINE_EXCEEDED: Deadline expired before operation could complete.

Periksa Latensi tulis 99% di tab Monitoring database Spanner Anda di Google Cloud konsol. Jika menampilkan nilai tinggi (beberapa detik), maka ini menunjukkan bahwa instance kelebihan beban, menyebabkan penulisan mengalami waktu tunggu dan gagal.

Salah satu penyebab latensi tinggi adalah tugas Dataflow berjalan menggunakan terlalu banyak worker, sehingga memberikan terlalu banyak beban pada instance Spanner.

Untuk menentukan batas jumlah worker Dataflow, bukan menggunakan tab Import/Export di halaman detail instance database Spanner Anda di Google Cloud konsol, Anda harus memulai impor menggunakan template Dataflow Cloud Storage Avro ke Spanner dan menentukan jumlah maksimum worker seperti yang dijelaskan:

Konsol

Jika Anda menggunakan konsol Dataflow, parameter Max workers terletak di bagian Optional parameters halaman Create job from template.

Buka Dataflow

gcloud

Jalankan perintah gcloud dataflow jobs run, dan tentukan argumen max-workers. Contoh:

  gcloud dataflow jobs run my-import-job \
    --gcs-location='gs://dataflow-templates/latest/GCS_Avro_to_Cloud_Spanner' \
    --region=us-central1 \
    --parameters='instanceId=test-instance,databaseId=example-db,inputDir=gs://my-gcs-bucket' \
    --max-workers=10 \
    --network=network-123

Memecahkan masalah error jaringan

Error berikut mungkin terjadi saat Anda mengekspor database Spanner:

Workflow failed. Causes: Error: Message: Invalid value for field
'resource.properties.networkInterfaces[0].subnetwork': ''. Network interface
must specify a subnet if the network resource is in custom subnet mode.
HTTP Code: 400

Error ini terjadi karena Spanner mengasumsikan bahwa Anda ingin menggunakan jaringan VPC mode otomatis bernama default di project yang sama dengan tugas Dataflow. Jika Anda tidak memiliki jaringan VPC default di project, atau jika jaringan VPC Anda berada di jaringan VPC mode kustom, Anda harus membuat tugas Dataflow dan menentukan jaringan atau subnetwork alternatif.

Mengoptimalkan tugas impor yang berjalan lambat

Jika Anda telah mengikuti saran di setelan awal, umumnya Anda tidak perlu melakukan penyesuaian lainnya. Jika tugas Anda berjalan lambat, ada beberapa pengoptimalan lain yang dapat Anda coba:

• Mengoptimalkan lokasi tugas dan data: Jalankan tugas Dataflow di region yang sama dengan lokasi instance Spanner dan bucket Cloud Storage Anda.

• Memastikan resource Dataflow yang cukup: Jika kuota Compute Engine yang relevan membatasi resource tugas Dataflow Anda, halaman Dataflow tugas di Google Cloud konsol akan menampilkan ikon peringatan dan pesan log:

  

  Dalam situasi ini, meningkatkan kuota untuk CPU, alamat IP yang digunakan, dan persistent disk standar dapat mempersingkat waktu proses tugas, tetapi Anda mungkin dikenai lebih banyak biaya Compute Engine.

• Memeriksa pemakaian CPU Spanner: Jika Anda melihat bahwa pemakaian CPU untuk instance lebih dari 65%, Anda dapat meningkatkan kapasitas komputasi di instance tersebut. Kapasitas ini akan menambahkan lebih banyak resource Spanner dan tugas akan dipercepat, tetapi Anda akan dikenai lebih banyak biaya Spanner.

Faktor yang memengaruhi performa tugas impor

Beberapa faktor memengaruhi waktu yang diperlukan untuk menyelesaikan tugas impor.

• Ukuran database Spanner: Memproses lebih banyak data memerlukan lebih banyak waktu dan resource.

• Skema database Spanner, termasuk:

  • Jumlah tabel
  • Ukuran baris
  • Jumlah indeks sekunder
  • Jumlah kunci asing
  • Jumlah aliran perubahan

Perhatikan bahwa pembuatan indeks dan kunci asing akan berlanjut setelah tugas impor Dataflow selesai. Aliran perubahan dibuat sebelum tugas impor selesai, tetapi setelah semua data diimpor.

• Lokasi data: Data ditransfer antara Spanner dan Cloud Storage menggunakan Dataflow. Idealnya, ketiga komponen tersebut berada di region yang sama. Jika komponen tidak berada di region yang sama, memindahkan data antar-region akan memperlambat tugas.

• Jumlah worker Dataflow: Worker Dataflow yang optimal diperlukan untuk performa yang baik. Dengan menggunakan penskalaan otomatis, Dataflow akan memilih jumlah worker untuk tugas tersebut, bergantung pada jumlah pekerjaan yang perlu dilakukan. Namun, jumlah worker akan dibatasi oleh kuota untuk CPU, alamat IP yang digunakan, dan persistent disk standar. UI Dataflow akan menampilkan ikon peringatan jika menemukan batas kuota. Dalam situasi ini, progres akan lebih lambat, tetapi tugas akan tetap selesai. Penskalaan otomatis dapat membebani Spanner secara berlebihan sehingga menyebabkan error jika ada banyak data yang akan diimpor.

• Beban yang ada di Spanner: Tugas impor menambahkan beban CPU yang signifikan pada instance Spanner. Jika instance sudah memiliki beban yang cukup besar, tugas akan berjalan lebih lambat.

• Jumlah kapasitas komputasi Spanner: Jika pemakaian CPU untuk instance lebih dari 65%, tugas akan berjalan lebih lambat.

Menyesuaikan worker untuk performa impor yang baik

Saat memulai tugas impor Spanner, worker Dataflow harus ditetapkan ke nilai yang optimal untuk performa yang baik. Terlalu banyak worker akan membebani Spanner secara berlebihan dan terlalu sedikit worker akan menghasilkan performa impor yang kurang memuaskan.

Jumlah maksimum worker sangat bergantung pada ukuran data, tetapi idealnya, total pemakaian CPU Spanner harus antara 70% hingga 90%. Hal ini memberikan keseimbangan yang baik antara efisiensi Spanner dan penyelesaian tugas tanpa error.

Untuk mencapai target pemakaian tersebut di sebagian besar skema dan skenario, sebaiknya gunakan jumlah maksimum vCPU worker antara 4-6x jumlah node Spanner.

Misalnya, untuk instance Spanner 10 node, menggunakan worker n1-standard-2, Anda akan menetapkan worker maksimum ke 25, sehingga memberikan 50 vCPU.