Buka konsol

Mengekspor dan mengimpor data

Anda dapat menggunakan layanan ekspor dan impor terkelola Cloud Firestore untuk melakukan pemulihan dari penghapusan data yang tidak disengaja, serta mengekspor data untuk pemrosesan offline. Anda dapat mengekspor semua dokumen atau hanya koleksi tertentu. Sebaliknya, Anda juga dapat mengimpor semua data dari bagian ekspor atau hanya koleksi tertentu. Data yang diekspor dari satu database Cloud Firestore dapat diimpor ke database Cloud Firestore lainnya. Anda juga dapat memuat ekspor Cloud Firestore ke BigQuery.

Halaman ini berisi penjelasan mengenai cara mengekspor dan mengimpor dokumen Cloud Firestore menggunakan layanan ekspor dan impor terkelola serta Cloud Storage. Layanan ekspor dan impor terkelola Cloud Firestore tersedia melalui fitur command-line gcloud dan Cloud Firestore API (REST, RPC).

Sebelum memulai

Sebelum dapat menggunakan layanan ekspor dan impor terkelola, Anda harus menyelesaikan tugas-tugas berikut:

  1. Mengaktifkan penagihan untuk project Google Cloud Platform Anda. Hanya project GCP dengan penagihan aktif yang dapat menggunakan fungsi ekspor dan impor.
  2. Membuat bucket Cloud Storage untuk project Anda di lokasi yang dekat dengan lokasi database Cloud Firestore Anda. Anda tidak dapat menggunakan bucket Pemohon Membayar untuk operasi ekspor dan impor.
  3. Memastikan akun Anda memiliki izin yang diperlukan untuk Cloud Firestore dan Cloud Storage. Jika Anda adalah pemilik project, berarti akun Anda memiliki izin yang diperlukan. Jika tidak, peran berikut ini dapat memberikan izin yang diperlukan untuk operasi ekspor dan impor, serta untuk mengakses Cloud Storage:

    • Peran Cloud Firestore: Owner, Cloud Datastore Owner, atau Cloud Datastore Import Export Admin
    • Peran Cloud Storage: Owner atau Storage Admin

Menyiapkan gcloud untuk project Anda

Siapkan fitur command-line gcloud lalu hubungkan ke project Anda dengan salah satu cara berikut:

Jika belum diinstal, tambahkan komponen gcloud beta yang berisi perintah ekspor dan impor Cloud Firestore:

  gcloud components install beta

Ekspor data

Operasi ekspor akan menyalin dokumen dalam database Anda ke sekumpulan file dalam bucket Cloud Storage. Perlu diperhatikan bahwa ekspor bukan snapshot database yang tepat yang diambil pada waktu mulai ekspor. Ekspor dapat mencakup perubahan yang dilakukan saat operasi berjalan.

Mengekspor semua dokumen

Gunakan perintah firestore export untuk mengekspor semua dokumen dalam database Anda, yang akan mengganti [BUCKET_NAME] dengan nama bucket Cloud Storage Anda. Tambahkan tanda --async untuk mencegah fitur gcloud menunggu operasi selesai.

gcloud beta firestore export gs://[BUCKET_NAME]

Anda dapat mengatur ekspor dengan menambahkan awalan file setelah nama bucket, misalnya, BUCKET_NAME/my-exports-folder/export-name. Jika Anda tidak memberikan awalan file, layanan ekspor terkelola akan membuat awalan file berdasarkan stempel waktu saat ini.

Setelah Anda memulai operasi ekspor, penutupan terminal tidak akan membatalkan operasi. Baca bagian membatalkan operasi.

Mengekspor koleksi tertentu

Untuk mengekspor koleksi tertentu, gunakan tanda --collection-ids:

gcloud beta firestore export gs://[BUCKET_NAME] --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

Mengimpor data

Setelah mengekspor file di Cloud Storage, Anda dapat kembali mengimpor dokumen dalam file tersebut ke project Anda atau ke project lain. Perhatikan hal-hal berikut terkait operasi impor:

  • Ketika Anda mengimpor data, indeks yang diperlukan akajn diupdate menggunakan definisi indeks database Anda saat ini. Ekspor tidak berisi definisi indeks.

  • Impor tidak menetapkan ID dokumen baru. Impor menggunakan ID yang diambil pada saat ekspor. Saat dokumen sedang diimpor, ID-nya dicadangkan untuk mencegah bentrokan ID. Jika terdapat dokumen dengan ID yang sama, operasi impor akan menimpa dokumen yang ada.

  • Jika dokumen dalam database Anda tidak terpengaruh oleh impor, dokumen tersebut akan tetap berada di database setelah impor selesai.

Mengimpor semua dokumen dari ekspor

Gunakan perintah firestore import untuk mengimpor dokumen dari operasi ekspor sebelumnya.

gcloud beta firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/

dengan [BUCKET_NAME] dan [EXPORT_PREFIX] menunjuk ke lokasi file ekspor Anda. Contoh:

gcloud beta firestore import gs://exports-bucket/2017-05-25T23:54:39_76544/

Anda dapat mengonfirmasi lokasi file ekspor di browser Cloud Storage di Google Cloud Platform Console:

Buka browser Cloud Storage

Setelah Anda memulai operasi impor, penutupan terminal tidak akan membatalkan operasi. Baca bagian membatalkan operasi.

Mengimpor koleksi tertentu

Untuk mengimpor koleksi tertentu dari serangkaian file ekspor, gunakan tanda --collection-ids. Anda dapat mengimpor koleksi tertentu saja jika menggunakan perintah ekspor koleksi tertentu. Anda tidak dapat mengimpor koleksi tertentu jika menggunakan perintah ekspor semua dokumen.

gcloud beta firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --collection-ids=[COLLECTION_ID_1],[COLLECTION_ID_2]

Mengelola operasi ekspor dan impor

Setelah Anda memulai operasi ekspor atau impor, Cloud Firestore akan menetapkan nama yang unik pada operasi tersebut. Anda dapat menggunakan nama operasi untuk menghapus, membatalkan, atau memeriksa status operasi.

Nama operasi diawali dengan projects/[PROJECT_ID]/databases/(default)/operations/, misalnya:

projects/my-project/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Namun, Anda dapat tidak menyertakan awalan saat menentukan nama operasi untuk perintah describe, cancel, dan delete.

Mencantumkan semua operasi ekspor dan impor

Gunakan perintah operations list untuk melihat semua operasi ekspor dan impor yang sedang berjalan dan baru selesai:

gcloud beta firestore operations list

Memeriksa status operasi

Gunakan perintah operations describe untuk menunjukkan status operasi ekspor atau impor.

gcloud beta firestore operations describe [OPERATION_NAME]

Memperkirakan waktu penyelesaian

Permintaan untuk status operasi yang berjalan lama akan menampilkan metrik workEstimated dan workCompleted. Masing-masing metrik tersebut ditampilkan baik dalam jumlah byte dan jumlah entity:

  • workEstimated menunjukkan perkiraan jumlah byte dan dokumen yang akan diproses oleh suatu operasi.

  • workCompleted menunjukkan jumlah byte dan dokumen yang diproses sejauh ini. Setelah operasi selesai, nilai akan menunjukkan jumlah total byte dan dokumen yang benar-benar diproses, dan mungkin lebih besar dari nilai workEstimated.

Bagilah workCompleted dengan workEstimated untuk mengetahui perkiraan proses kasar. Perkiraan ini mungkin tidak akurat karena bergantung pada koleksi statistik yang tertunda.

Membatalkan operasi

Gunakan perintah operations cancel untuk menghentikan operasi yang sedang berlangsung:

gcloud beta firestore operations cancel [OPERATION_NAME]

Jika operasi yang sedang berjalan dibatalkan, operasi tersebut tidak akan diurungkan. Operasi ekspor yang dibatalkan akan membiarkan dokumen yang telah diekspor di dalam Cloud Storage, sedangkan operasi impor yang dibatalkan akan membiarkan update yang sudah dilakukan pada database Anda. Anda tidak dapat mengimpor ekspor yang selesai sebagian.

Menghapus operasi

Gunakan perintah operations delete untuk menghapus operasi dari output operations list. Perintah ini tidak akan menghapus file ekspor dari Cloud Storage.

gcloud beta firestore operations delete [OPERATION_NAME]

Penagihan dan harga untuk operasi ekspor dan impor

Anda harus mengaktifkan penagihan untuk project Google Cloud Platform sebelum menggunakan layanan ekspor dan impor terkelola. Operasi ekspor dan impor dikenai biaya untuk pembacaan dan penulisan dokumen sebesar tarif yang tercantum dalam harga Cloud Firestore.

Biaya operasi ekspor dan impor tidak dihitung dalam batas pengeluaran Anda. Operasi ekspor atau impor tidak akan memicu notifikasi anggaran Google Cloud Platform Anda sampai operasi selesai. Demikian pula, operasi baca dan tulis yang dilakukan selama operasi ekspor atau impor akan diterapkan pada kuota harian Anda setelah operasi selesai.

Ekspor ke BigQuery

Untuk memuat data dari ekspor Cloud Firestore ke BigQuery, baca bagian Memuat data dari ekspor Cloud Firestore.