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 atau hanya koleksi tertentu dari suatu ekspor. 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).

Perhatian: Pengeksporan data dari Cloud Firestore akan menimbulkan satu operasi baca per dokumen yang diekspor. Namun, operasi baca ini tidak akan muncul di bagian penggunaan pada konsol. Pastikan Anda memahami hal ini sebelum menyiapkan ekspor berulang untuk menghindari tagihan yang tidak diharapkan.

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 aktif yang dapat menggunakan fungsi ekspor dan impor.
   Catatan: Project Firebase harus berlangganan paket Blaze
2. Membuat bucket Cloud Storage untuk project Anda di lokasi yang dekat dengan lokasi database Cloud Firestore Anda. Anda tidak dapat menggunakan bucket Requester Pays 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 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
     Catatan: Peran Datastore ini juga memberikan izin di Cloud Firestore.

   • 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

[e-mail]

Untuk mempelajari agen layanan lebih lanjut, lihat Agen layanan.

Catatan: Cloud Firestore sebelumnya menggunakan akun layanan default App Engine, bukan agen layanan Cloud Firestore. Jika database masih menggunakan akun layanan App Engine untuk mengimpor atau mengekspor data, sebaiknya Anda bermigrasi ke agen layanan Cloud Firestore khusus layanan. Anda dapat melihat akun yang digunakan operasi impor dan ekspor di Konsol Google Cloud Platform.

Jika menggunakan Kontrol Layanan VPC, Anda harus menggunakan agen layanan Cloud Firestore khusus layanan untuk melindungi operasi impor dan ekspor sepenuhnya. Kontrol Layanan VPC tidak kompatibel dengan akun layanan App Engine.

Agen layanan Cloud Firestore memerlukan akses ke bucket Cloud Storage yang digunakan dalam operasi ekspor atau impor. Jika bucket Cloud Storage berada dalam project yang sama dengan database Cloud Firestore, agen layanan Cloud Firestore 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 Admin Storage ke agen layanan Cloud Firestore, jalankan perintah berikut:

gsutil iam ch serviceAccount:[e-mail]: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 GCP.

Lihat nama agen layanan

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

1. Lihat akun otorisasi di samping label Impor/Ekspor 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 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:

• Akses gcloud dari Google Cloud Platform Console menggunakan Cloud Shell.

  Mulai Cloud Shell

  Pastikan gcloud dikonfigurasi untuk project yang tepat:

  gcloud config set project [PROJECT_ID]
  

• Instal dan lakukan inisialisasi Google Cloud SDK.

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.

Catatan: Anda harus mengekspor koleksi tertentu jika berencana untuk:

• Mengimpor koleksi tertentu saja
• Memuat data Cloud Firestore ke BigQuery

Mengekspor semua dokumen

Google Cloud Console

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

4. Klik Export.

5. Klik opsi Export entire database.

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

7. Klik Export.

Konsol akan kembali ke halaman Import/Export. 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] \
  --database=[DATABASE]

Ganti kode berikut:

• BUCKET_NAME: atur ekspor Anda 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.

• DATABASE: nama database tempat Anda ingin mengekspor dokumen. Untuk database default, gunakan --database='(default)'.

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

Mengekspor koleksi tertentu

Google Cloud Console

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

4. Klik Export.

5. Klik opsi Export one or more collection groups. Gunakan menu drop-down untuk memilih satu atau beberapa grup koleksi.

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

7. Klik Export.

Konsol akan kembali ke halaman Import/Export. 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.

Catatan: Pengeksporan koleksi tidak akan otomatis mengekspor subkoleksinya. Anda juga harus menentukan subkoleksi yang akan diekspor.

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

Misalnya, Anda dapat mendesain koleksi restaurants di database foo untuk menyertakan beberapa subkoleksi, seperti ratings, reviews, atau outlets. Untuk mengekspor koleksi tertentu restaurants dan reviews, perintah Anda akan terlihat seperti berikut:

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 menggunakan perintah gcloud firestore export. 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.

1. Ekspor database, dengan menentukan parameter snapshot-time ke stempel waktu pemulihan yang diinginkan.

   gcloud

   Jalankan perintah berikut untuk mengekspor database ke bucket Anda.

   gcloud firestore export gs://[BUCKET_NAME_PATH] \
       --snapshot-time=[PITR_TIMESTAMP] \
       --collection-ids=[COLLECTION_IDS] \
       --namespace-ids=[NAMESPACE_IDS]
   

   Dengan,

   • PITR_TIMESTAMP - stempel waktu PITR pada tingkat perincian menit, misalnya, 2023-05-26T10:20:00.00Z.

   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.

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.

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

• 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 tetap sama.

Mengimpor semua dokumen dari ekspor

Google Cloud Console

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

4. Klik Import.

5. Di kolom Filename, masukkan nama file .overall_export_metadata dari operasi ekspor yang sudah selesai. Anda dapat menggunakan tombol Browse untuk membantu memilih file.

6. Klik Import.

Konsol akan kembali ke halaman Import/Export. 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]/ --database=[DATABASE]

Ganti kode berikut:

• BUCKET_NAME/EXPORT_PREFIX: lokasi file ekspor.

• DATABASE: nama database. Untuk database default, gunakan --database='(default)'.

Contoh:

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

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

Catatan: Untuk mengimpor koleksi tertentu, Anda harus menggunakan output operasi ekspor tempat Anda mengekspor 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 flag --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. Tentukan nama database menggunakan tanda --database. Untuk database default, gunakan --database='(default)'.

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],[SUBCOLLECTION_ID_1] \
  --database=[DATABASE]

Mengimpor ekspor PITR

Gunakan langkah-langkah di bagian Mengimpor semua dokumen untuk mengimpor database yang telah diekspor. Jika ada dokumen yang sudah ada dalam database Anda, dokumen tersebut akan ditimpa.

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 Import/Export di Google Cloud Platform Console.

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

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 Import/Export di Google Cloud Platform Console.

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

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. 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 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

Google Cloud Console

Anda dapat membatalkan operasi ekspor atau impor yang sedang berjalan di halaman Import/Export di Google Cloud Platform Console.

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

Di tabel Recent imports and exports, operasi yang saat ini sedang berjalan menyertakan tombol Cancel di kolom Completed. Klik tombol Cancel untuk menghentikan operasi. Tombol akan berubah menjadi pesan Cancelling kemudian Cancelled 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. Operasi ekspor menimbulkan satu operasi baca per dokumen yang diekspor. Operasi impor menimbulkan satu operasi tulis per dokumen yang diimpor.

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

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 Cloud Billing reports, Anda dapat menggunakan label ini untuk melihat biaya yang terkait dengan operasi impor dan ekspor:

Catatan: Operasi ekspor dan impor yang dijalankan sebelum 8 September 2020 tidak menerapkan label goog-firestoremanaged.

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 menetapkan 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

Migrasi agen layanan

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

Agen layanan Cloud Firestore

[e-mail]

Cloud Firestore sebelumnya menggunakan akun layanan default App Engine, bukan agen layanan Cloud Firestore. Jika database masih menggunakan akun layanan App Engine untuk mengimpor atau mengekspor data, sebaiknya ikuti petunjuk di bagian ini untuk bermigrasi menggunakan agen layanan Cloud Firestore.

Akun layanan App Engine

[e-mail]

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

Catatan: Jika menggunakan Kontrol Layanan VPC, Anda harus menggunakan agen layanan Cloud Firestore untuk sepenuhnya melindungi operasi impor dan ekspor. Kontrol Layanan VPC tidak kompatibel dengan akun layanan App Engine.

Melihat akun otorisasi

Anda dapat melihat akun yang digunakan oleh operasi impor dan ekspor untuk mengizinkan permintaan dari halaman Import/Export di Google Cloud Platform Console. Anda juga dapat melihat apakah database sudah menggunakan agen layanan Cloud Firestore.

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

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

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

• Memigrasi project dengan memeriksa dan memperbarui izin bucket Cloud Storage (direkomendasikan).
• Menambahkan batasan kebijakan seluruh organisasi yang memengaruhi semua project dalam organisasi.

Teknik pertama lebih disukai karena melokalkan cakupan efek ke satu project Cloud Firestore. Teknik kedua tidak direkomendasikan karena tidak memigrasi izin bucket Cloud Storage yang sudah ada. Namun, teknik ini menyediakan kepatuhan keamanan di tingkat organisasi.

Memigrasi dengan memeriksa dan memperbarui izin bucket Cloud Storage

Proses migrasi ini terdiri dari dua langkah:

1. Memperbarui izin bucket Cloud Storage. Lihat bagian berikut untuk mengetahui detailnya.
2. Mengonfirmasi migrasi ke agen layanan Cloud Firestore.

Izin bucket agen layanan

Untuk operasi ekspor atau impor apa pun 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 harus mengakses bucket dalam project lain tersebut. Jika tidak, operasi tersebut akan gagal setelah bermigrasi ke agen layanan Cloud Firestore.

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

Perbarui izin bucket Cloud Storage dari project lain untuk memberikan akses ke agen layanan [e-mail]. Berikan peran Firestore Service Agent kepada agen layanan.

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

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

Memigrasi project 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. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

4. Jika project Anda belum dimigrasikan ke agen layanan Cloud Firestore, Anda akan melihat banner yang menjelaskan migrasi dan tombol Check Bucket Status. Langkah berikutnya membantu Anda mengidentifikasi dan memperbaiki kemungkinan kesalahan izin.

   Klik Check Bucket Status.

   Menu akan muncul dengan opsi untuk menyelesaikan migrasi Anda dan daftar bucket Cloud Storage. Proses pemuatan daftar mungkin akan memerlukan waktu beberapa saat.

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

5. Catat nama utama agen layanan Cloud Firestore project Anda. Nama agen layanan muncul di bawah label Service agent to give access to.

6. Untuk bucket dalam daftar yang akan Anda gunakan untuk operasi impor atau ekspor mendatang, selesaikan langkah-langkah berikut:

   1. Di baris tabel bucket ini, klik Fix. Halaman izin bucket akan terbuka di tab baru.

   2. Klik Add.
   3. Di kolom New principals, masukkan nama agen layanan Cloud Firestore Anda.
   4. Pada kolom Select a role, pilih Service Agents > Firestore Service Agent.
   5. Klik Save.
   6. Kembali ke tab pada halaman Cloud Firestore Import/Export.
   7. Ulangi langkah ini untuk bucket lain dalam daftar. Pastikan Anda melihat semua halaman pada daftar.

7. Klik Migrate to Firestore Service Agent. Jika masih memiliki bucket dengan pemeriksaan izin yang gagal, Anda harus mengonfirmasi migrasi dengan mengklik Migrate.

   Pemberitahuan akan memberi tahu Anda saat migrasi selesai. Migrasi tidak dapat diurungkan.

Melihat status migrasi

Untuk memverifikasi status migrasi project Anda:

1. Di Google Cloud Platform Console, buka halaman Databases.

   Buka Databases

2. Pilih database yang diperlukan dari daftar database.

3. Di menu navigasi, klik Import/Export.

4. Cari akun utama di samping label Import/Export jobs run as.

   Jika akun utamanya adalah [e-mail], berarti project Anda telah dimigrasikan ke agen layanan Cloud Firestore. Migrasi tidak dapat diurungkan.

   Jika project belum dimigrasikan, banner akan muncul di bagian atas halaman dengan tombol Check Bucket Status. Lihat Memigrasi ke agen layanan Firestore untuk menyelesaikan migrasi.

Menambahkan batasan kebijakan di seluruh organisasi

• Tetapkan batasan berikut dalam kebijakan organisasi Anda:

  Require Firestore Service Agent for import/export (firestore.requireP4SAforImportExport).

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

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

Jika batasan ini menimbulkan error izin untuk alur kerja impor atau ekspor, Anda dapat menonaktifkannya untuk kembali menggunakan akun layanan default. Setelah memeriksa dan memperbarui izin bucket Cloud Storage, Anda dapat mengaktifkan kembali batasan tersebut.