Ikuti semua informasi yang diumumkan di Firebase Summit, dan pelajari bagaimana Firebase dapat membantu Anda mempercepat pengembangan aplikasi dan menjalankan aplikasi dengan percaya diri. Pelajari Lebih Lanjut

Ekspor dan impor data

Anda dapat menggunakan layanan ekspor dan impor terkelola Cloud Firestore untuk memulihkan dari penghapusan data yang tidak disengaja dan mengekspor data untuk pemrosesan offline. Anda dapat mengekspor semua dokumen atau hanya koleksi tertentu. Demikian pula, Anda dapat mengimpor semua data dari 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 dan Cloud Storage . Layanan ekspor dan impor terkelola Cloud Firestore tersedia melalui alat baris perintah gcloud dan Cloud Firestore API ( REST , RPC ).

Sebelum kamu memulai

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

  1. Aktifkan penagihan untuk project Google Cloud Anda. Hanya project Google Cloud dengan penagihan yang diaktifkan yang dapat menggunakan fungsi ekspor dan impor.
  2. Buat bucket Cloud Storage untuk project Anda di lokasi yang dekat dengan lokasi database Cloud Firestore Anda . Anda tidak dapat menggunakan keranjang Peminta Pembayaran untuk operasi ekspor dan impor.
  3. Pastikan akun Anda memiliki izin yang diperlukan untuk Cloud Firestore dan Cloud Storage. Jika Anda adalah pemilik proyek, akun Anda memiliki izin yang diperlukan. Jika tidak, peran berikut memberikan izin yang diperlukan untuk operasi ekspor dan impor serta akses ke Cloud Storage:

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

Izin akun layanan default

Setiap proyek Google Cloud secara otomatis membuat akun layanan default bernama PROJECT_ID @appspot.gserviceaccount.com . Operasi ekspor dan impor menggunakan akun layanan ini untuk mengotorisasi 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 Anda, maka akun layanan default memiliki akses ke bucket tersebut secara default .

Jika bucket Cloud Storage ada di project lain, Anda harus memberikan akses akun layanan default ke bucket Cloud Storage.

Akun layanan memerlukan peran Storage Admin Penyimpanan agar bucket Cloud Storage dapat digunakan untuk operasi ekspor atau impor.

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

Siapkan gcloud untuk proyek Anda

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

Ekspor data

Operasi ekspor menyalin dokumen di database Anda ke sekumpulan file di bucket Cloud Storage. Perhatikan bahwa ekspor bukanlah snapshot database persis yang diambil pada waktu mulai ekspor. Ekspor mungkin mencakup perubahan yang dilakukan saat operasi sedang berjalan.

Ekspor 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 basis data .

  4. Di bawah Choose Destination , masukkan nama bucket Cloud Storage atau gunakan tombol Telusuri untuk memilih bucket.

  5. Klik Ekspor .

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

gcloud

Gunakan perintah firestore export untuk mengekspor semua dokumen di database Anda, ganti [BUCKET_NAME] dengan nama bucket Cloud Storage Anda. Tambahkan flag --async untuk mencegah alat gcloud menunggu operasi selesai.

gcloud firestore export gs://[BUCKET_NAME]

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

Setelah Anda memulai operasi ekspor, menutup terminal tidak membatalkan operasi, lihat batalkan operasi .

Ekspor 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 tarik-turun untuk memilih satu atau beberapa grup koleksi.

  4. Di bawah Choose Destination , masukkan nama bucket Cloud Storage atau gunakan tombol Telusuri untuk memilih bucket.

  5. Klik Ekspor .

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

gcloud

Untuk mengekspor grup koleksi tertentu, gunakan tanda --collection-ids . Operasi hanya mengekspor grup koleksi dengan ID koleksi yang diberikan. Grup koleksi menyertakan 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],[SUBCOLLECTION_ID_1]

Impor data

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

  • Saat Anda mengimpor data, indeks yang diperlukan diperbarui menggunakan definisi indeks database Anda saat ini. Ekspor tidak mengandung 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 tabrakan ID. Jika dokumen dengan ID yang sama sudah ada, impor akan menimpa dokumen yang sudah ada.

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

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

  • Nama file .overall_export_metadata harus cocok 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 keluaran ekspor, pertahankan nama file PARENT_FOLDER_NAME dan .overall_export_metadata tetap sama.

Impor 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 Filename , masukkan nama file dari file .overall_export_metadata dari operasi ekspor yang telah selesai. Anda dapat menggunakan tombol Telusuri untuk membantu Anda memilih file.

  4. Klik Impor .

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

gcloud

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

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

di mana [BUCKET_NAME] dan [EXPORT_PREFIX] menunjuk ke lokasi file ekspor Anda. Sebagai contoh:

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

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

Buka browser Cloud Storage

Setelah Anda memulai operasi impor, menutup terminal tidak membatalkan operasi, lihat batalkan operasi .

Impor koleksi tertentu

Google Cloud Console

Anda tidak dapat memilih koleksi tertentu di konsol. Gunakan gcloud sebagai gantinya.

gcloud

Untuk mengimpor grup koleksi tertentu dari sekumpulan file ekspor, gunakan tanda --collection-ids . Operasi hanya mengimpor grup koleksi dengan ID koleksi yang diberikan. Grup koleksi menyertakan 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 dari ekspor semua dokumen.

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

Mengelola kegiatan ekspor dan impor

Setelah Anda memulai operasi ekspor atau impor, Cloud Firestore 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/(default)/operations/ , misalnya:

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

Namun, Anda dapat mengabaikan awalan saat describe nama operasi untuk perintahuraikan, cancel , dan delete .

Buat daftar 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

Periksa 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 menunjukkan status operasi ekspor atau impor.

gcloud firestore operations describe [OPERATION_NAME]

Perkirakan waktu penyelesaiannya

Permintaan untuk status operasi yang berjalan lama mengembalikan metrik workEstimated dan workCompleted . Setiap metrik ini dikembalikan dalam jumlah byte dan jumlah entitas:

  • workEstimated menunjukkan perkiraan jumlah total byte dan dokumen yang akan diproses oleh operasi. Cloud Firestore mungkin menghilangkan metrik ini jika tidak dapat membuat perkiraan.

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

Membagi workCompleted dengan workEstimated untuk perkiraan kemajuan kasar. Estimasi ini mungkin tidak akurat, karena bergantung pada pengumpulan 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

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

gcloud

Gunakan perintah operations cancel untuk menghentikan operasi yang sedang berlangsung:

gcloud firestore operations cancel [OPERATION_NAME]

Membatalkan operasi yang sedang berjalan tidak membatalkan operasi. Operasi ekspor yang dibatalkan akan meninggalkan dokumen yang sudah diekspor di Cloud Storage, dan operasi impor yang dibatalkan akan meninggalkan pembaruan yang sudah dibuat ke database Anda. Anda tidak dapat mengimpor ekspor yang selesai sebagian.

Hapus 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 penetapan harga untuk operasi ekspor dan impor

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

Biaya operasi ekspor dan impor tidak diperhitungkan dalam batas pengeluaran Anda. Operasi ekspor atau impor tidak akan memicu peringatan anggaran Google Cloud Anda hingga selesai. Demikian pula, baca dan tulis yang dilakukan selama operasi ekspor atau impor diterapkan ke 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 laman laporan Penagihan Cloud , Anda dapat menggunakan label ini untuk melihat biaya yang terkait dengan operasi impor dan ekspor:

Akses label yang dikelola goog-firestore dari menu filter.

Ekspor ke BigQuery

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

Batas kolom BigQuery

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

Jika skema BigQuery grup koleksi melebihi 10.000 kolom, operasi ekspor Cloud Firestore akan mencoba untuk tetap berada di bawah batas kolom dengan memperlakukan kolom peta sebagai byte. Jika konversi ini menghasilkan jumlah kolom di bawah 10.000, Anda dapat memuat data ke dalam BigQuery, tetapi Anda tidak dapat mengkueri subkolom dalam kolom peta. Jika jumlah kolom masih melebihi 10.000, operasi ekspor tidak akan menghasilkan skema BigQuery untuk grup koleksi dan Anda tidak dapat memuat datanya ke BigQuery.

Ekspor format dan file metadata

Keluaran ekspor terkelola menggunakan format log LevelDB .

File metadata

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

File metadata adalah buffer protokol dan Anda dapat mendekodekannya dengan kompiler protokol protoc . Misalnya, Anda dapat mendekode file metadata untuk menentukan grup koleksi yang berisi file ekspor:

protoc --decode_raw < export0.export_metadata

Migrasi agen layanan

Anda kini dapat menggunakan agen layanan Cloud Firestore untuk mengotorisasi operasi impor dan ekspor, bukan akun layanan App Engine. Agen layanan dan akun layanan menggunakan konvensi penamaan berikut:

Agen layanan Cloud Firestore
service- project_number @gcp-sa-firestore.iam.gserviceaccount.com
Akun layanan App Engine
project_id @appspot.gserviceaccount.com

Agen layanan Cloud Firestore lebih disukai karena khusus untuk Cloud Firestore. Akun layanan App Engine digunakan bersama oleh lebih dari satu layanan.

Lihat akun otorisasi

Anda dapat melihat akun mana yang digunakan operasi impor dan ekspor Anda untuk mengotorisasi permintaan dari halaman Impor/Ekspor di Google Cloud Platform Console. Anda juga dapat melihat apakah database Anda sudah menggunakan agen layanan Cloud Firestore.

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

    Pergi ke Impor/Ekspor

  2. Lihat akun otorisasi di sebelah label Impor/Ekspor yang dijalankan sebagai label.

Jika project Anda tidak menggunakan agen layanan Cloud Firestore, Anda dapat bermigrasi ke agen layanan Cloud Firestore menggunakan salah satu teknik berikut:

Teknik pertama lebih disukai karena melokalkan cakupan efek ke satu project Cloud Firestore. Teknik kedua tidak disukai karena tidak memigrasikan izin bucket Cloud Storage yang ada. Namun, itu menawarkan kepatuhan keamanan di tingkat organisasi.

Lakukan migrasi dengan memeriksa dan memperbarui izin bucket Cloud Storage

Proses migrasi memiliki dua langkah:

  1. Perbarui izin bucket Cloud Storage. Lihat bagian berikut untuk detailnya.
  2. Konfirmasi migrasi ke agen layanan Cloud Firestore.

Izin keranjang agen layanan

Untuk setiap operasi ekspor atau impor yang menggunakan bucket Cloud Storage di project lain , Anda harus memberikan izin kepada agen layanan Cloud Firestore untuk bucket tersebut. Misalnya, operasi yang memindahkan data ke project lain perlu mengakses bucket di project lain tersebut. Jika tidak, operasi ini akan gagal setelah bermigrasi ke agen layanan Cloud Firestore.

Alur kerja impor dan ekspor yang berada dalam proyek yang sama tidak memerlukan perubahan izin. Agen layanan Cloud Firestore dapat mengakses bucket di project yang sama secara default.

Perbarui izin untuk bucket Cloud Storage dari project lain untuk memberikan akses ke agen layanan service- project_number @gcp-sa-firestore.iam.gserviceaccount.com . Beri agen layanan peran Firestore Service Agent .

Peran Firestore Service Agent memberikan izin baca dan tulis untuk bucket Cloud Storage. Jika Anda hanya perlu memberikan izin baca atau tulis saja, gunakan peran khusus .

Proses migrasi yang dijelaskan di bagian berikut membantu Anda mengidentifikasi bucket Cloud Storage yang mungkin memerlukan pembaruan izin.

Migrasikan proyek ke Agen Layanan Firestore

Selesaikan langkah-langkah berikut untuk bermigrasi dari akun layanan App Engine ke agen layanan Cloud Firestore. Setelah selesai, migrasi tidak dapat dibatalkan.

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

    Pergi ke Impor/Ekspor

  2. Jika project Anda belum dimigrasikan ke agen layanan Cloud Firestore, Anda akan melihat banner yang menjelaskan migrasi dan tombol Periksa Status Bucket . Langkah selanjutnya membantu Anda mengidentifikasi dan memperbaiki potensi kesalahan izin.

    Klik Periksa Status Bucket .

    Sebuah menu akan muncul dengan opsi untuk menyelesaikan migrasi Anda dan daftar bucket Cloud Storage. Mungkin diperlukan waktu beberapa menit hingga daftar selesai dimuat.

    Daftar ini menyertakan bucket yang baru-baru ini digunakan dalam operasi impor dan ekspor, tetapi saat ini tidak memberikan izin baca dan tulis ke agen layanan Cloud Firestore.

  3. Catat nama utama agen layanan Cloud Firestore project Anda. Nama agen layanan muncul di bawah Agen layanan untuk memberikan akses ke label.
  4. Untuk semua keranjang dalam daftar yang akan Anda gunakan untuk operasi impor atau ekspor di masa mendatang, selesaikan langkah-langkah berikut:

    1. Di baris tabel keranjang ini, klik Perbaiki . Ini membuka halaman izin keranjang itu di tab baru.

    2. Klik Tambahkan .
    3. Di kolom Prinsipal baru , masukkan nama agen layanan Cloud Firestore Anda.
    4. Di bidang Pilih peran , pilih Agen Layanan > Agen Layanan Firestore .
    5. Klik Simpan .
    6. Kembali ke tab dengan halaman Impor/Ekspor Cloud Firestore.
    7. Ulangi langkah ini untuk keranjang lain dalam daftar. Pastikan untuk melihat semua halaman daftar.
  5. Klik Migrasi ke Agen Layanan Firestore . Jika Anda masih memiliki keranjang dengan pemeriksaan izin yang gagal, Anda perlu mengonfirmasi migrasi dengan mengeklik Migrasi .

    Lansiran memberi tahu Anda saat migrasi Anda selesai. Migrasi tidak dapat diurungkan.

Lihat status migrasi

  1. Untuk memverifikasi status migrasi proyek Anda, buka halaman Impor/Ekspor di Google Cloud Platform Console:

    Pergi ke Impor/Ekspor

  2. Cari kepala sekolah di sebelah label Impor/Ekspor yang dijalankan sebagai label.

    Jika prinsipal adalah service- project_number @gcp-sa-firestore.iam.gserviceaccount.com , maka project Anda telah dimigrasikan ke agen layanan Cloud Firestore. Migrasi tidak dapat dibatalkan.

    Jika proyek belum dimigrasikan, spanduk akan muncul di bagian atas halaman dengan tombol Periksa Status Bucket . Lihat Bermigrasi ke agen layanan Firestore untuk menyelesaikan migrasi.

Tambahkan batasan kebijakan di seluruh organisasi

  • Tetapkan batasan berikut dalam kebijakan organisasi Anda:

    Wajibkan Agen Layanan Firestore untuk impor/ekspor ( firestore.requireP4SAforImportExport ).

    Batasan ini memerlukan operasi impor dan ekspor untuk menggunakan agen layanan Cloud Firestore guna mengotorisasi permintaan. Untuk menyetel batasan ini, lihat Membuat dan mengelola kebijakan organisasi .

Menerapkan batasan kebijakan organisasi ini tidak secara otomatis memberikan izin bucket Cloud Storage yang sesuai untuk agen layanan Cloud Firestore.

Jika batasan membuat kesalahan izin untuk alur kerja impor atau ekspor apa pun, Anda dapat menonaktifkannya untuk kembali menggunakan akun layanan default. Setelah Anda memeriksa dan mengupdate izin bucket Cloud Storage , Anda dapat mengaktifkan kembali batasan tersebut.