Mengekspor dan Mengimpor Entity

Halaman ini menjelaskan cara mengekspor dan mengimpor entity Firestore dalam mode Datastore menggunakan layanan ekspor dan impor terkelola. Layanan ekspor dan impor terkelola tersedia melalui konsol Google Cloud, Google Cloud CLI, dan Datastore Admin API (REST, RPC).

Dengan layanan ekspor dan impor terkelola, Anda dapat memulihkan data yang tidak sengaja terhapus dan mengekspor data untuk pemrosesan offline. Anda dapat mengekspor semua entity atau hanya jenis entity tertentu. Demikian pula, Anda dapat mengimpor semua data dari ekspor atau hanya jenis tertentu. Saat Anda menggunakan layanan ekspor dan impor terkelola, pertimbangkan hal-hal berikut:

  • Layanan ekspor menggunakan pembacaan yang akhirnya konsisten. Anda tidak dapat mengasumsikan bahwa ekspor terjadi pada satu titik waktu. Ekspor mungkin menyertakan entity yang ditulis setelah ekspor dimulai dan mengecualikan entity yang ditulis sebelum ekspor dimulai.

  • Ekspor tidak berisi indeks apa pun. Saat Anda mengimpor data, indeks yang diperlukan akan otomatis dibuat ulang menggunakan definisi indeks database Anda saat ini. Setelan indeks nilai properti per entity diekspor dan dipatuhi selama impor.

  • Impor tidak menetapkan ID baru ke entity. Impor menggunakan ID yang ada pada saat ekspor dan menimpa entitas yang ada dengan ID yang sama. Selama impor, ID dicadangkan selama entity sedang diimpor. Fitur ini mencegah konflik ID dengan entity baru jika penulisan diaktifkan saat impor berjalan.

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

  • Data yang diekspor dari satu database mode Datastore dapat diimpor ke database mode Datastore lainnya, bahkan database di project lain.

  • Layanan ekspor dan impor terkelola membatasi jumlah ekspor dan impor serentak hingga 50 dan mengizinkan maksimum 20 permintaan ekspor dan impor per menit untuk sebuah project. Untuk setiap permintaan, layanan membatasi jumlah kombinasi filter entity hingga 100.

  • Output ekspor yang dikelola menggunakan format log LevelDB.

  • Untuk hanya mengimpor sebagian entity atau mengimpor data ke BigQuery, Anda harus menentukan filter entity dalam ekspor.

  • 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 PARENT_FOLDER_NAME, isi subfolder, dan nama file .overall_export_metadata tetap sama.

Sebelum memulai

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

  1. Aktifkan penagihan untuk project Google Cloud Anda. Hanya project Google Cloud dengan penagihan aktif yang dapat menggunakan fitur ekspor dan impor.

  2. Buat bucket Cloud Storage di lokasi yang sama dengan database Firestore dalam mode Datastore. Anda tidak dapat menggunakan bucket Requester Pays untuk operasi ekspor dan impor.

  3. Tetapkan peran IAM ke akun pengguna Anda yang memberikan izin datastore.databases.export, jika Anda mengekspor data, atau izin datastore.databases.import, jika Anda mengimpor data. Misalnya, peran Datastore Import Export Admin memberikan kedua izin tersebut.

  4. Jika bucket Cloud Storage berada dalam project lain, berikan akses ke bucket kepada agen layanan Firestore.

Menyiapkan gcloud untuk project Anda

Jika Anda berencana menggunakan gcloud untuk memulai operasi impor dan ekspor, siapkan gcloud dan hubungkan ke project Anda dengan salah satu cara berikut:

Izin

Untuk menjalankan operasi ekspor dan impor, akun pengguna dan agen layanan mode Datastore project Anda memerlukan izin berikut Pengelolaan Akses dan Identitas.

Izin akun pengguna

Akun pengguna atau akun layanan yang memulai operasi memerlukan izin IAM datastore.databases.export dan datastore.databases.import. Jika Anda adalah pemilik project, akun Anda memiliki izin yang diperlukan. Jika tidak, peran IAM berikut akan memberikan izin yang diperlukan:

  • Pemilik Datastore
  • Datastore Import Export Admin

Anda juga dapat menetapkan izin ini dengan peran khusus.

Pemilik project dapat memberikan salah satu peran tersebut dengan mengikuti langkah-langkah di bagian Berikan akses.

Izin agen layanan

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

Agen layanan Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Untuk mempelajari lebih lanjut agen layanan, lihat Agen layanan.

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

Jika bucket Cloud Storage berada dalam project lain, Anda harus memberi agen layanan 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 Firestore, jalankan perintah 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 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 Firestore atau akun layanan App Engine lama.

  1. Di konsol Google Cloud, 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.

Operasi ekspor

Untuk operasi ekspor yang melibatkan bucket di project lain, ubah izin bucket untuk menetapkan salah satu peran Identity and Access Management berikut ke agen layanan mode Datastore project yang berisi database mode Datastore Anda:

  • Storage Admin
  • Pemilik (peran dasar)

Anda juga dapat membuat peran khusus IAM dengan izin yang sedikit berbeda dari yang terdapat dalam peran yang tercantum sebelumnya:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.list

Operasi impor

Untuk operasi impor yang melibatkan bucket Cloud Storage di project lain, ubah izin bucket untuk menetapkan salah satu peran Cloud Storage berikut ke agen layanan mode Datastore project yang berisi database mode Datastore Anda:

  • Storage Admin
  • Storage Object Viewer dan Storage Legacy Bucket Reader

Anda juga dapat membuat peran khusus IAM dengan izin berikut:

  • storage.buckets.get
  • storage.objects.get

Memulai operasi ekspor dan impor terkelola

Bagian ini menjelaskan cara memulai operasi ekspor atau impor terkelola.

Mengekspor semua entity

Konsol

  1. Di konsol Google Cloud, buka halaman Databases.

    Buka Databases

  2. Pilih database yang diperlukan dari daftar database.

  1. Di menu navigasi, klik Import/Export.
  2. Klik Ekspor.
  3. Tetapkan kolom Namespace ke All Namespaces, dan tetapkan kolom Kind ke All Kinds.
  4. Di bawah Destination, masukkan nama bucket Cloud Storage Anda.
  5. Klik Ekspor.

Konsol akan kembali ke halaman Import/Export. Notifikasi melaporkan keberhasilan atau kegagalan permintaan ekspor terkelola Anda.

gcloud

Gunakan perintah gcloud firestore export untuk mengekspor semua entity dalam database Anda.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

dengan bucket-name adalah nama bucket Cloud Storage Anda dan awalan opsional, misalnya, bucket-name/datastore-exports/export-name. Anda tidak dapat menggunakan kembali awalan yang sama untuk operasi ekspor lain. Jika Anda tidak memberikan awalan file, layanan ekspor terkelola akan membuat awalan file berdasarkan waktu saat ini.

Gunakan flag [--async][async-flag] untuk mencegah gcloud menunggu operasi selesai. Jika Anda menghilangkan flag --async, Anda dapat mengetik Ctrl+c untuk berhenti menunggu operasi. Tindakan ini tidak akan membatalkan operasi.

Tetapkan tanda --database ke nama database tempat Anda ingin mengekspor entity. Untuk database default, gunakan --database='(default)'.

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda
  • bucket-name: nama bucket Cloud Storage Anda

Metode HTTP dan URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Meminta isi JSON: 

{
  "outputUrlPrefix": "gs://bucket-name",
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}
Responsnya adalah operasi yang berjalan lama, yang dapat Anda periksa untuk mengetahui penyelesaiannya.

Mengekspor jenis atau namespace tertentu

Untuk mengekspor subset jenis dan/atau namespace tertentu, berikan filter entity dengan nilai untuk jenis dan ID namespace. Setiap permintaan dibatasi hingga 100 kombinasi filter entity, dengan setiap kombinasi jenis dan namespace yang difilter dihitung sebagai filter terpisah terhadap batas ini.

Konsol

Di konsol, Anda dapat memilih semua jenis atau satu jenis tertentu. Demikian pula, Anda dapat memilih semua namespace atau satu namespace tertentu.

Untuk menentukan daftar namespace dan jenis yang akan diekspor, gunakan gcloud.

  1. Di konsol Google Cloud, buka halaman Databases.

    Buka Databases

  2. Pilih database yang diperlukan dari daftar database.

  3. Di menu navigasi, klik Import/Export.

  4. Klik Ekspor.

  5. Tetapkan kolom Namespace ke All Namespaces atau ke nama salah satu namespace Anda.

  6. Tetapkan kolom Kind ke All Kinds atau ke nama jenis.

  7. Di bagian Destination, masukkan nama bucket Cloud Storage Anda.

  8. Klik Ekspor.

Konsol akan kembali ke halaman Import/Export. Notifikasi melaporkan keberhasilan atau kegagalan permintaan ekspor terkelola Anda.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

dengan bucket-name adalah nama bucket Cloud Storage Anda dan awalan opsional, misalnya, bucket-name/datastore-exports/export-name. Anda tidak dapat menggunakan kembali awalan yang sama untuk operasi ekspor lain. Jika Anda tidak memberikan awalan file, layanan ekspor terkelola akan membuat awalan file berdasarkan waktu saat ini.

Gunakan flag [--async][async-flag] untuk mencegah gcloud menunggu operasi selesai. Jika Anda menghilangkan flag --async, Anda dapat mengetik Ctrl+c untuk berhenti menunggu operasi. Tindakan ini tidak akan membatalkan operasi.

Tetapkan tanda --database ke nama database tempat Anda ingin mengekspor jenis atau namespace tertentu. Untuk database default, gunakan --database='(default)'.

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda
  • bucket-name: nama bucket Cloud Storage Anda
  • kind: jenis entity
  • namespace: ID namespace (gunakan "" untuk ID namespace default)

Metode HTTP dan URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Meminta isi JSON: 

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}
Responsnya adalah operasi yang berjalan lama, yang dapat Anda periksa untuk mengetahui penyelesaiannya.

File metadata

Operasi ekspor akan membuat file metadata untuk setiap pasangan jenis namespace yang ditentukan. File metadata biasanya bernama NAMESPACE_NAME_KIND_NAME.export_metadata. Namun, jika namespace atau jenis akan membuat nama objek Cloud Storage yang tidak valid, file akan diberi nama export[NUM].export_metadata.

File metadata adalah buffering protokol dan dapat didekode dengan compiler protokol protoc. Misalnya, Anda dapat mendekode file metadata untuk menentukan namespace dan jenis yang ada di file ekspor:

protoc --decode_raw < export0.export_metadata

Mengimpor semua entity

Konsol

  1. Di konsol Google Cloud, 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 File, klik Browse dan pilih file .overall_export_metadata.

    Pastikan file .overall_export_metadata tidak dipindahkan dari lokasi default.

  6. Tetapkan kolom Namespace ke All Namespaces, dan tetapkan kolom Kind ke All Kinds.

  7. Klik Import.

Konsol akan kembali ke halaman Import/Export. Notifikasi melaporkan keberhasilan atau kegagalan permintaan impor terkelola Anda.

gcloud

Gunakan perintah gcloud firestore import untuk mengimpor semua entity yang sebelumnya diekspor dengan layanan ekspor terkelola.

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

dengan bucket-name/file-path/file-name adalah jalur ke file overall_export_metadata dalam bucket Cloud Storage Anda.

Gunakan flag [--async][async-flag] untuk mencegah gcloud menunggu operasi selesai. Jika Anda menghilangkan flag --async, Anda dapat mengetik Ctrl+c untuk berhenti menunggu operasi. Tindakan ini tidak akan membatalkan operasi.

Tetapkan tanda --database ke nama database tempat Anda ingin mengimpor semua entity. Untuk database default, gunakan --database='(default)'.

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda
  • bucket-name: nama bucket Cloud Storage Anda
  • object-name: nama objek Cloud Storage Anda (contoh: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

Metode HTTP dan URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Meminta isi JSON: 

{
  "inputUrl": "gs://bucket-name/object-name",
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}
Responsnya adalah operasi yang berjalan lama, yang dapat Anda periksa untuk mengetahui penyelesaiannya.

Menemukan file overall_export_metadata

Anda dapat menentukan nilai yang akan digunakan untuk lokasi impor menggunakan browser Cloud Storage di konsol Google Cloud:

Buka Browser Cloud Storage

Anda juga dapat mencantumkan dan mendeskripsikan operasi yang telah selesai. Kolom outputURL menampilkan nama file overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Mengimpor jenis atau namespace tertentu

Untuk mengimpor subset jenis dan/atau namespace tertentu, berikan filter entity dengan nilai untuk jenis dan ID namespace.

Anda hanya dapat menentukan jenis dan namespace jika file ekspor dibuat dengan filter entity. Anda tidak dapat mengimpor subkumpulan jenis dan namespace dari ekspor semua entity.

Konsol

Di konsol, Anda dapat memilih semua jenis atau satu jenis tertentu. Demikian pula, Anda dapat memilih semua namespace atau satu namespace tertentu.

Untuk menentukan daftar namespace dan jenis yang akan diimpor, gunakan gcloud.

  1. Di konsol Google Cloud, 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 File, klik Browse dan pilih file .overall_export_metadata.

    Pastikan Anda mengimpor file .overall_export_metadata, bukan file .export_metadata.

  6. Tetapkan kolom Namespace ke All Namespaces atau ke namespace tertentu.

  7. Tetapkan kolom Jenis ke All Kinds atau ke jenis tertentu.

  8. Klik Import.

Konsol akan kembali ke halaman Import/Export. Notifikasi melaporkan keberhasilan atau kegagalan permintaan impor terkelola Anda.

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

dengan bucket-name/file-path/file-name adalah jalur ke file overall_export_metadata dalam bucket Cloud Storage Anda.

Gunakan flag [--async][async-flag] untuk mencegah gcloud menunggu operasi selesai. Jika Anda menghilangkan flag --async, Anda dapat mengetik Ctrl+c untuk berhenti menunggu operasi. Tindakan ini tidak akan membatalkan operasi.

Tetapkan tanda --database ke nama database tempat Anda ingin mengimpor jenis atau namespace tertentu. Untuk database default, gunakan --database='(default)'.

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda
  • bucket-name: nama bucket Cloud Storage Anda
  • object-name: nama objek Cloud Storage Anda (contoh: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata
  • kind: jenis entity
  • namespace: ID namespace (gunakan "" untuk ID namespace default)

Metode HTTP dan URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Meminta isi JSON: 

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}
Responsnya adalah operasi yang berjalan lama, yang dapat Anda periksa untuk mengetahui penyelesaiannya.

Mengekspor dan mengimpor dari data 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 entity dan mengekspor jenis atau namespace tertentu.

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

    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.

    [Mengekspor subkumpulan jenis dan/atau namespace tertentu dengan filter entity][export-kind] juga didukung.

    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 keseluruhan satu menit dalam tujuh hari terakhir, tetapi tidak lebih awal dari earliestVersionTime. Jika data tidak lagi ada pada stempel waktu yang ditentukan, Anda akan menerima pesan error.
    • Anda tidak akan ditagih untuk ekspor PITR yang gagal.

  2. Mengimpor ke database.

    Gunakan langkah-langkah di bagian Mengimpor semua entitas untuk mengimpor database yang telah diekspor. Jika ada entity yang sudah ada dalam database Anda, entity tersebut akan ditimpa. [Mengimpor subkumpulan jenis dan/atau namespace tertentu dengan filter entity][import-kind] juga didukung.

Mengimpor transformasi

Saat mengimpor entity dari project lain, perlu diingat bahwa kunci entity menyertakan project ID. Operasi impor memperbarui kunci entity dan properti referensi kunci dalam data impor dengan project ID project tujuan. Jika update ini meningkatkan ukuran entity, hal ini dapat menyebabkan error "entity terlalu besar" atau "entri indeks terlalu besar" untuk operasi impor.

Untuk menghindari salah satu error tersebut, impor ke project tujuan dengan project ID yang lebih singkat. Hal ini tidak memengaruhi operasi impor dengan data dari project yang sama.

Mengelola operasi yang berjalan lama

Operasi impor dan ekspor terkelola adalah operasi yang berjalan lama. Panggilan metode ini dapat memerlukan waktu yang cukup lama untuk diselesaikan.

Setelah Anda memulai operasi ekspor atau impor, mode Datastore akan menetapkan nama 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/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

Anda dapat tidak menyertakan awalan saat menentukan nama operasi untuk perintah gcloud.

Mencantumkan semua operasi yang berjalan lama

Anda dapat melihat operasi yang sedang berlangsung dan yang baru saja selesai dengan cara berikut. Operasi tercantum selama beberapa hari setelah selesai:

Konsol

Anda dapat melihat daftar operasi yang berjalan lama di halaman Import/Export di konsol Google Cloud.

  1. Di konsol Google Cloud, buka halaman Databases.

    Buka Databases

  2. Pilih database yang diperlukan dari daftar database.

  3. Di menu navigasi, klik Import/Export.

gcloud

Untuk mencantumkan operasi yang berjalan lama, gunakan perintah gcloud datastore operations list. 

gcloud datastore operations list

Misalnya, operasi ekspor yang baru saja selesai menampilkan informasi berikut:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda

Metode HTTP dan URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Untuk mengirim permintaan, perluas salah satu opsi berikut:

Lihat informasi tentang respons di bawah.

Misalnya, operasi ekspor yang baru saja selesai menampilkan informasi berikut:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Memeriksa status operasi

Untuk melihat status operasi yang berjalan lama:

Konsol

Anda dapat melihat daftar operasi ekspor dan impor terbaru di halaman Import/Export di konsol Google Cloud.

  1. Di konsol Google Cloud, 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 yang berjalan lama.

gcloud datastore operations describe operation-name

istirahat

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • project-id: project ID Anda
  • operation-name: nama operasi

Metode HTTP dan URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

Untuk mengirim permintaan, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

Memperkirakan waktu penyelesaian

Saat operasi berjalan, lihat nilai kolom state untuk mengetahui status operasi secara keseluruhan.

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. Mode Datastore 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 bergantung pada koleksi statistik yang tertunda.

Misalnya, berikut adalah status progres operasi ekspor:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

Saat operasi selesai, deskripsi operasi akan berisi "done": true. Lihat nilai kolom state untuk menemukan hasil operasi. Jika kolom done tidak ditetapkan dalam respons, maka nilainya adalah false. Jangan bergantung pada keberadaan nilai done untuk operasi yang sedang berlangsung.

Membatalkan operasi

Konsol

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

  1. Di konsol Google Cloud, 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 datastore 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

gcloud

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

gcloud datastore operations delete operation-name

Penagihan dan harga untuk ekspor dan impor terkelola

Anda harus mengaktifkan penagihan untuk project Google Cloud sebelum menggunakan layanan ekspor dan impor terkelola. Operasi ekspor dan impor berkontribusi pada biaya Google Cloud Anda dengan cara berikut:

  • Operasi baca dan tulis entity yang dilakukan oleh operasi ekspor dan impor diperhitungkan dalam biaya Firestore dalam mode Datastore. Operasi ekspor menimbulkan satu operasi baca per entity yang diekspor. Operasi impor menimbulkan satu operasi tulis per entity yang diimpor.
  • File output yang disimpan di Cloud Storage memengaruhi biaya penyimpanan data Cloud Storage Anda.

Operasi ekspor atau impor tidak akan memicu pemberitahuan anggaran Google Cloud hingga operasi selesai. Demikian pula, operasi baca dan tulis yang dilakukan selama operasi ekspor atau impor akan diterapkan pada kuota harian Anda setelah operasi selesai.

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:

Akses label goog-firestoremanaged dari menu filter.

Perbedaan dengan cadangan Admin Datastore

Jika sebelumnya Anda menggunakan konsol Admin Datastore untuk pencadangan, Anda harus memperhatikan perbedaan berikut:

  • Ekspor yang dibuat oleh ekspor terkelola tidak muncul di konsol Admin Datastore. Ekspor dan impor terkelola adalah layanan baru yang tidak berbagi data dengan fitur pencadangan dan pemulihan App Engine, yang dikelola melalui konsol Google Cloud.

  • Layanan ekspor dan impor terkelola tidak mendukung metadata yang sama dengan pencadangan Datastore Admin dan tidak menyimpan status progres di database Anda. Untuk informasi tentang cara memeriksa progres operasi ekspor dan impor, lihat Mengelola operasi yang berjalan lama

  • Anda tidak dapat melihat log layanan operasi ekspor dan impor terkelola.

  • Layanan impor terkelola kompatibel dengan file cadangan Admin Datastore versi lama. Anda dapat mengimpor file cadangan Datastore Admin menggunakan layanan impor terkelola, tetapi tidak dapat mengimpor output ekspor terkelola menggunakan konsol Datastore Admin.

Mengimpor ke BigQuery

Untuk mengimpor data dari ekspor terkelola ke BigQuery, lihat Memuat data layanan ekspor Datastore.

Data yang diekspor tanpa menentukan filter entity tidak dapat dimuat ke BigQuery. Jika Anda ingin mengimpor data ke BigQuery, permintaan ekspor Anda harus menyertakan satu atau beberapa nama jenis dalam filter entity.

Batas kolom BigQuery

BigQuery menetapkan batas 10.000 kolom per tabel. Operasi ekspor menghasilkan skema tabel BigQuery untuk setiap jenis. Dalam skema ini, setiap properti unik dalam entity jenis menjadi kolom skema.

Jika skema BigQuery jenis melebihi 10.000 kolom, operasi ekspor akan berupaya agar tidak melebihi batas kolom dengan memperlakukan entity tersemat sebagai blob. Jika konversi ini menghasilkan jumlah kolom dalam skema kurang dari 10.000, Anda dapat memuat data ke BigQuery, tetapi tidak dapat membuat kueri properti dalam entity tersemat. Jika jumlah kolom masih melampaui 10.000, operasi ekspor tidak menghasilkan skema BigQuery untuk jenis tersebut dan Anda tidak dapat memuat datanya ke BigQuery.

Migrasi agen layanan

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

Agen layanan Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

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

Akun layanan App Engine
PROJECT_ID@appspot.gserviceaccount.com

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

Melihat akun otorisasi

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

  1. Di konsol Google Cloud, 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 Firestore, Anda dapat bermigrasi ke agen layanan Firestore menggunakan salah satu teknik berikut:

Teknik pertama lebih disukai karena melokalkan cakupan efek ke satu project mode Datastore. 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. Konfirmasi migrasi ke agen layanan 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 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 Firestore.

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

Perbarui izin bucket Cloud Storage dari project lain untuk memberikan akses ke agen layanan service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com. 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 Firestore. Setelah selesai, migrasi tidak dapat dibatalkan.

  1. Di konsol Google Cloud, 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 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 mode Datastore.

  5. Catat nama utama agen layanan mode Datastore 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 Tambahkan.
    3. Di kolom New principals, masukkan nama agen layanan Firestore Anda.
    4. Pada kolom Select a role, pilih Service Agents > Firestore Service Agent.
    5. Klik Simpan.
    6. Kembali ke tab pada halaman Import/Export mode Datastore.
    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 konsol Google Cloud, 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 service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, berarti project Anda telah dimigrasikan ke agen layanan 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 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 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.