Mengimpor dan mengekspor data

Anda dapat menggunakan layanan ekspor dan impor terkelola untuk memulihkan data yang tidak sengaja terhapus dan mengekspor data untuk pemrosesan offline. Anda dapat mengekspor semua dokumen atau hanya koleksi tertentu. Demikian pula, Anda dapat mengimpor semua data atau hanya koleksi tertentu dari suatu ekspor. Data yang diekspor dari satu database Cloud Firestore dengan kompatibilitas MongoDB dapat diimpor ke database Cloud Firestore dengan kompatibilitas MongoDB lainnya. Anda juga dapat memuat ekspor Cloud Firestore dengan kompatibilitas MongoDB ke BigQuery.

Halaman ini menjelaskan cara mengekspor dan mengimpor dokumen Cloud Firestore dengan kompatibilitas MongoDB menggunakan layanan ekspor dan impor terkelola serta Cloud Storage. Layanan ekspor dan impor terkelola Cloud Firestore dengan kompatibilitas MongoDB tersedia melalui alat command-line gcloud dan API Cloud Firestore dengan kompatibilitas MongoDB (REST, RPC).

Sebelum memulai

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

1. Aktifkan penagihan untuk project Google Cloud. Hanya project Google Cloud dengan penagihan aktif yang dapat menggunakan fungsi ekspor dan impor.
2. Buat bucket Cloud Storage untuk project Anda di lokasi yang dekat dengan lokasi database Cloud Firestore dengan kompatibilitas MongoDB Anda. Anda tidak dapat menggunakan bucket Requester Pays untuk operasi ekspor dan impor.

3. Pastikan akun Anda memiliki izin yang diperlukan untuk Cloud Firestore dengan kompatibilitas MongoDB dan Cloud Storage. Jika Anda adalah pemilik project, berarti akun Anda memiliki izin yang diperlukan. Jika tidak, peran berikut memberikan izin yang diperlukan untuk operasi ekspor dan impor, serta untuk mengakses Cloud Storage:

   • Peran Cloud Firestore dengan kompatibilitas MongoDB: Owner, Cloud Datastore Owner, atau Cloud Datastore Import Export Admin

   • Peran Cloud Storage: Owner atau Storage Admin

Izin agen layanan

Operasi ekspor dan impor menggunakan agen layanan Cloud Firestore untuk mengizinkan operasi Cloud Storage. Agen layanan Cloud Firestore menggunakan konvensi penamaan berikut:

Agen layanan Cloud Firestore

service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Untuk mempelajari lebih lanjut agen layanan, lihat Agen layanan.

Agen layanan Cloud Firestore 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, agen layanan Cloud Firestore akan dapat mengakses bucket secara default.

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

Menetapkan peran ke agen layanan

Anda dapat menggunakan alat command line gsutil untuk menetapkan salah satu peran di bawah ini. Misalnya, untuk menetapkan peran Storage Admin ke agen layanan Cloud Firestore, lakukan hal berikut:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Ganti PROJECT_NUMBER dengan nomor project yang digunakan untuk memberi nama agen layanan Cloud Firestore. Untuk melihat nama agen layanan, lihat Melihat nama agen layanan.

Atau, Anda dapat menetapkan peran ini menggunakan konsol Google Cloud.

Melihat nama agen layanan

Anda dapat melihat akun yang digunakan operasi impor dan ekspor untuk mengizinkan permintaan dari halaman Import/Export di konsol Google Cloud. Anda juga dapat melihat apakah database menggunakan agen layanan Cloud Firestore atau akun layanan App Engine lama.

1. Lihat akun otorisasi di samping label Import/Export jobs run as.

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

Menyiapkan gcloud untuk project Anda

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

• Akses gcloud dari konsol Google Cloud menggunakan Cloud Shell.

  Memulai Cloud Shell

  Pastikan gcloud dikonfigurasi untuk project yang tepat:

  gcloud config set project [PROJECT_ID]
  

• Instal dan inisialisasi Google Cloud SDK.

Mengimpor data

Setelah memiliki file ekspor di Cloud Storage, Anda dapat mengimpor kembali 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.

• Nama file .overall_export_metadata harus sama dengan nama folder induknya:

  gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

  Jika Anda memindahkan atau menyalin file output ekspor, pastikan nama file PARENT_FOLDER_NAME dan .overall_export_metadata sama.

• Impor ke database Cloud Firestore dengan kompatibilitas MongoDB dari ekspor dengan subkoleksi gagal karena subkoleksi tidak didukung di Cloud Firestore dengan kompatibilitas MongoDB.

• Impor ke database edisi Cloud Firestore Standard dari ekspor dengan jenis BSON gagal karena jenis BSON tidak didukung di edisi Cloud Firestore Standard.

• Impor ke database Cloud Firestore dengan kompatibilitas MongoDB tidak dapat mengimpor data dari namespace non-default (Datastore API).

  Impor ke database Cloud Firestore dengan kompatibilitas MongoDB dari file data yang berisi namespace non-default hanya diizinkan jika operasi ekspor menyertakan filter --namespace-ids dengan namespace default. Hanya data dari namespace default yang diimpor.

Mengimpor semua dokumen dari ekspor

gcloud firestore import gs://[BUCKET_NAME]/[EXPORT_PREFIX]/ --database=[DATABASE]

gcloud firestore import gs://my-bucket/2017-05-25T23:54:39_76544/ --database='cymbal'

Mengimpor koleksi tertentu

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

Mengimpor dari ekspor dengan data PITR

Gunakan langkah-langkah yang sama seperti di bagian Mengimpor semua dokumen atau Mengimpor koleksi tertentu untuk mengimpor data PITR. Jika ada dokumen yang sudah ada dalam database Anda, dokumen tersebut akan ditimpa.

Ekspor 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

  gcloud firestore export gs://[BUCKET_NAME] \
  --database=[DATABASE]

Mengekspor koleksi tertentu

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

gcloud firestore export gs://[BUCKET_NAME] \
--collection-ids=restaurants,reviews \
--database='cymbal'

Mengekspor dari stempel waktu PITR

Anda dapat mengekspor database ke Cloud Storage dari data PITR. Anda dapat mengekspor data PITR dengan stempel waktu satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime. Jika data tidak lagi ada di stempel waktu yang ditentukan, operasi ekspor akan gagal.

Operasi ekspor PITR mendukung semua filter, termasuk mengekspor semua dokumen dan mengekspor koleksi tertentu.

Perhatikan hal-hal berikut sebelum mengekspor data PITR:

• Tentukan stempel waktu dalam format RFC 3339. Contoh, 2020-09-01T23:59:30.234233Z.
• Pastikan stempel waktu yang Anda tentukan adalah stempel waktu satu menit terakhir dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime. Jika data sudah tidak ada di stempel waktu yang ditentukan, akan terjadi error.
• Anda tidak akan ditagih untuk ekspor PITR yang gagal.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
    --snapshot-time=[PITR_TIMESTAMP]

Mengelola operasi ekspor dan impor

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

Nama operasi diawali dengan projects/[PROJECT_ID]/databases/[DATABASE_ID]/operations/, misalnya:

projects/my-project/databases/my-database/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

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

Mencantumkan semua operasi ekspor dan impor

gcloud firestore operations list

Memeriksa status operasi

gcloud firestore operations describe [OPERATION_NAME]

Memperkirakan waktu penyelesaian

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

• workEstimated menampilkan estimasi total jumlah byte dan dokumen yang akan diproses oleh sebuah operasi. Cloud Firestore dengan kompatibilitas MongoDB mungkin menghilangkan metrik ini jika tidak dapat membuat perkiraan.

• 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 kasar dari progresnya. Perkiraan ini mungkin tidak akurat karena tergantung pada koleksi statistik yang tertunda.

Membatalkan operasi

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 pembaruan 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 unit baca dan unit tulis sesuai tarif yang tercantum dalam harga Cloud Firestore dengan kompatibilitas MongoDB.

File output yang disimpan di Cloud Storage memengaruhi biaya penyimpanan data Cloud Storage Anda.

Operasi ekspor atau impor tidak akan memicu notifikasi anggaran Google Cloud hingga 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 Cloud Billing reports, Anda dapat menggunakan label ini untuk melihat biaya yang terkait dengan operasi impor dan ekspor:

Mengekspor ke BigQuery

Anda dapat memuat data dari ekspor Cloud Firestore dengan kompatibilitas MongoDB ke BigQuery, tetapi hanya jika Anda menentukan filter collection-ids. Lihat Memuat data dari ekspor Cloud Firestore dengan kompatibilitas MongoDB.

Saat memuat data Cloud Firestore dengan kompatibilitas MongoDB ke BigQuery, jenis data BSON direpresentasikan dengan jenis data STRING.

Batas kolom BigQuery

BigQuery menetapkan batas 10.000 kolom per tabel. Operasi ekspor Cloud Firestore dengan kompatibilitas MongoDB menghasilkan skema tabel BigQuery untuk setiap koleksi. Dalam skema ini, setiap nama kolom unik dalam koleksi menjadi kolom skema.

Jika skema BigQuery koleksi melebihi 10.000 kolom, operasi ekspor Cloud Firestore dengan kompatibilitas MongoDB 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 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 membuat file metadata untuk setiap 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 koleksi yang berada di dalam file ekspor:

protoc --decode_raw < export0.export_metadata