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. Demikian pula, Anda dapat mengimpor semua data dari suatu 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 menjelaskan 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 alat 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 Anda. Hanya project Google Cloud dengan penagihan diaktifkan 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

Izin akun layanan default

Setiap project Google Cloud secara otomatis membuat akun layanan default bernama PROJECT_ID@appspot.gserviceaccount.com. Operasi ekspor dan impor menggunakan akun layanan ini untuk mengizinkan operasi Cloud Storage.

Akun layanan default project Anda memerlukan akses ke bucket Cloud Storage yang digunakan dalam operasi ekspor atau impor. Jika bucket Cloud Storage Anda berada dalam project yang sama dengan database Cloud Firestore, secara default akun layanan default memiliki akses ke bucket.

Jika bucket Cloud Storage berada dalam project lain, Anda harus memberi akun layanan default akses ke bucket Cloud Storage.

Akun layanan memerlukan peran Storage Admin untuk bucket Cloud Storage yang akan digunakan untuk operasi ekspor atau impor.

Jika Anda menonaktifkan atau menghapus akun layanan default App Engine, aplikasi App Engine akan kehilangan akses ke database Cloud Firestore Anda. Jika telah menonaktifkan akun layanan App Engine, Anda dapat mengaktifkannya kembali. Lihat mengaktifkan akun layanan. Jika telah menghapus akun layanan App Engine dalam 30 hari terakhir, Anda dapat memulihkan akun layanan. Lihat membatalkan penghapusan akun layanan.

Menyiapkan gcloud untuk project Anda

Anda dapat memulai operasi impor dan ekspor melalui Google Cloud Platform Console atau alat command line gcloud. Untuk menggunakan gcloud, siapkan alat command line dan hubungkan ke project Anda dengan salah satu cara berikut:

Mengekspor data

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

Mengekspor semua dokumen

Google Cloud Console

  1. Buka halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

    Buka halaman Impor/Ekspor

  2. Klik Ekspor.

  3. Klik opsi Ekspor seluruh database.

  4. Di bawah Pilih Tujuan, masukkan nama bucket Cloud Storage atau gunakan tombol Cari untuk memilih bucket.

  5. Klik Ekspor.

Konsol akan kembali ke halaman Impor/Ekspor. Jika operasi berhasil dimulai, halaman akan menambahkan entri ke halaman impor dan ekspor terbaru. Jika gagal, halaman akan menampilkan pesan error.

gcloud

Gunakan perintah firestore export untuk mengekspor semua dokumen dalam database Anda, dan gantilah [BUCKET_NAME] dengan nama bucket Cloud Storage Anda. Tambahkan flag --async agar alat gcloud tidak menunggu operasi selesai.

gcloud 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

Google Cloud Console

  1. Buka halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

    Buka halaman Impor/Ekspor

  2. Klik Ekspor.

  3. Klik opsi Ekspor satu atau beberapa grup koleksi. Gunakan menu drop-down untuk memilih satu atau beberapa grup koleksi.

  4. Di bawah Pilih Tujuan, masukkan nama bucket Cloud Storage atau gunakan tombol Cari untuk memilih bucket.

  5. Klik Ekspor.

Konsol akan kembali ke halaman Impor/Ekspor. Jika operasi berhasil dimulai, halaman akan menambahkan entri ke halaman impor dan ekspor terbaru. Jika gagal, halaman akan menampilkan pesan error.

gcloud

Untuk mengekspor grup koleksi tertentu, gunakan flag --collection-ids. Operasi hanya mengekspor grup koleksi dengan ID koleksi yang diberikan. Grup koleksi mencakup semua koleksi dan subkoleksi (di jalur mana pun) dengan ID koleksi yang ditentukan.

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

Mengimpor data

Setelah memiliki file ekspor 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 akan 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 konflik 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.

  • Operasi impor tidak memicu Cloud Functions. Pemroses snapshot menerima update terkait dengan operasi impor.

Mengimpor semua dokumen dari ekspor

Google Cloud Console

  1. Buka halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

    Buka halaman Impor/Ekspor

  2. Klik Impor.

  3. Di kolom Nama file, masukkan nama file .overall_export_metadata dari operasi ekspor yang sudah selesai. Anda dapat menggunakan tombol Cari untuk membantu memilih file.

  4. Klik Impor.

Konsol akan kembali ke halaman Impor/Ekspor. Jika operasi berhasil dimulai, halaman akan menambahkan entri ke halaman impor dan ekspor terbaru. Jika gagal, halaman akan menampilkan pesan error.

gcloud

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

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

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

gcloud 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

Google Cloud Console

Anda tidak dapat memilih koleksi tertentu di konsol. Sebagai gantinya, gunakan gcloud.

gcloud

Untuk mengimpor grup koleksi tertentu dari kumpulan file ekspor, gunakan tanda --collection-ids. Operasi hanya mengimpor grup koleksi dengan ID koleksi yang diberikan. Grup koleksi mencakup semua koleksi dan subkoleksi (di jalur mana pun) dengan ID koleksi yang ditentukan.

Hanya ekspor grup koleksi tertentu yang mendukung impor grup koleksi tertentu. Anda tidak dapat mengimpor koleksi tertentu jika menggunakan perintah ekspor semua dokumen.

gcloud 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

Google Cloud Console

Anda dapat melihat daftar operasi ekspor dan impor terbaru di halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

Buka halaman Impor/Ekspor

gcloud

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

gcloud firestore operations list

Memeriksa status operasi

Google Cloud Console

Anda dapat melihat status operasi ekspor atau impor terbaru di halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

Buka halaman Impor/Ekspor

gcloud

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

gcloud 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 menampilkan estimasi total jumlah byte dan dokumen yang akan diproses oleh sebuah 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 perkiraan proses kasar. Perkiraan ini mungkin tidak akurat karena tergantung pada koleksi statistik yang tertunda.

Membatalkan operasi

Google Cloud Console

Anda dapat membatalkan operasi ekspor atau impor yang sedang berjalan di halaman Impor/Ekspor Cloud Firestore di Google Cloud Platform Console.

Buka halaman Impor/Ekspor

Di tabel Impor dan ekspor terbaru, operasi yang saat ini sedang berjalan menyertakan tombol Batal di kolom Selesai. Klik tombol Batal untuk menghentikan operasi. Tombol akan berubah menjadi pesan Membatalkan kemudian Dibatalkan saat operasi berhenti sepenuhnya.

gcloud

Gunakan perintah operations cancel untuk menghentikan operasi yang sedang berlangsung:

gcloud 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 gcloud firestore operations delete untuk menghapus operasi dari daftar operasi terbaru. Perintah ini tidak akan menghapus file ekspor dari Cloud Storage.

gcloud firestore operations delete [OPERATION_NAME]

Penagihan dan harga untuk operasi ekspor dan impor

Anda harus mengaktifkan penagihan untuk project Google Cloud 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 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. Operasi ekspor dan impor tidak akan memengaruhi penggunaan yang ditampilkan di bagian penggunaan konsol.

Melihat biaya ekspor dan impor

Operasi ekspor dan impor menerapkan label goog-firestoremanaged:exportimport ke operasi yang ditagih. Di halaman laporan Penagihan Cloud, Anda dapat menggunakan label ini untuk melihat biaya yang terkait dengan operasi impor dan ekspor:

Akses label goog-firestoremanaged dari menu filter.

Mengekspor ke BigQuery

Anda dapat memuat data dari ekspor Cloud Firestore ke BigQuery, tetapi hanya jika Anda menentukan filter collection-ids. Baca bagian Memuat data dari ekspor Cloud Firestore.

Batas kolom BigQuery

BigQuery mengenakan batas 10.000 kolom per tabel. Operasi ekspor Cloud Firestore menghasilkan skema tabel BigQuery untuk setiap grup koleksi. Dalam skema ini, setiap nama kolom unik dalam grup koleksi menjadi kolom skema.

Jika skema BigQuery grup koleksi melebihi 10.000 kolom, operasi ekspor Cloud Firestore berupaya agar tidak melebihi batas kolom dengan memperlakukan kolom peta sebagai byte. Jika konversi ini menghasilkan jumlah kolom kurang dari 10.000, Anda dapat memuat data ke BigQuery, tetapi tidak dapat membuat kueri subkolom dalam bidang peta. Jika jumlah kolom masih melampaui 10.000, operasi ekspor tidak menghasilkan skema BigQuery untuk grup koleksi dan Anda tidak dapat memuat datanya ke BigQuery.

Mengekspor file format dan metadata

Output ekspor yang dikelola menggunakan format log LevelDB.

File metadata

Operasi ekspor akan membuat file metadata untuk setiap grup koleksi yang Anda tentukan. File metadata biasanya bernama ALL_NAMESPACES_KIND_[COLLECTION_GROUP_ID].export_metadata.

File metadata adalah buffering protokol dan Anda dapat mendekodenya dengan compiler protokol protoc. Misalnya, Anda dapat mendekode file metadata untuk menentukan grup koleksi yang ada di file ekspor:

protoc --decode_raw < export0.export_metadata