Mengimpor metadata

Anda dapat mengimpor metadata Dataplex Catalog—yang entri dan aspeknya—dari sistem pihak ketiga ke Dataplex.

Untuk mengimpor metadata, ikuti langkah-langkah tingkat tinggi berikut:

  1. Menentukan ruang lingkup pekerjaan.

    Juga, pahami bagaimana Dataplex menerapkan logika perbandingan dan mode sinkronisasi untuk entri dan aspek.

  2. Buat satu atau beberapa file impor metadata yang menentukan data yang akan diimpor.

  3. Simpan file impor metadata dalam bucket Cloud Storage.

  4. Menjalankan tugas impor metadata.

Langkah-langkah pada halaman ini mengasumsikan bahwa Anda sudah akrab dengan Konsep Dataplex Catalog, termasuk grup entri, jenis entri, serta jenis aspek. Untuk informasi selengkapnya, lihat Ringkasan Dataplex Catalog.

Sebelum memulai

Sebelum mengimpor metadata, selesaikan tugas di bagian ini.

Peran yang diperlukan

Untuk memastikan bahwa Akun layanan Dataplex memiliki izin yang diperlukan untuk mengakses bucket Cloud Storage, minta administrator untuk memberi akun layanan Dataplex Peran IAM Storage Object Viewer (roles/storage.objectViewer) dan izin storage.buckets.get pada bucket.

Untuk mendapatkan izin yang Anda perlukan untuk mengelola tugas metadata, minta administrator untuk memberi Anda peran IAM berikut:

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Membuat resource Google Cloud

Siapkan resource Google Cloud berikut:

  1. Membuat grup entri untuk entri yang ingin diimpor.
  2. Membuat jenis aspek untuk aspek yang ingin Anda impor.
  3. Membuat jenis entri untuk entri yang ingin diimpor.
  4. Membuat bucket Cloud Storage untuk menyimpan file impor metadata.

Komponen tugas metadata

Saat Anda mengimpor metadata, pertimbangkan komponen tugas metadata berikut:

  • Cakupan pekerjaan: grup entri, jenis entri, dan jenis aspek yang akan disertakan dalam atau Preemptible untuk menjalankan tugas tersebut.
  • Mode sinkronisasi: apakah akan menjalankan update penuh atau inkremental info terbaru tentang entri dan aspek-aspek dalam pekerjaan.
  • File impor metadata: file yang menentukan nilai yang akan ditetapkan untuk entri dan aspek di pekerjaan itu. Anda dapat menyediakan beberapa file impor metadata dalam tugas {i>metadata<i} yang sama. Anda menyimpan file di Cloud Storage.
  • Logika perbandingan: cara Dataplex menentukan entri dan aspek yang dapat dimodifikasi.

Cakupan tugas

Cakupan tugas mendefinisikan grup entri, jenis entri, dan secara opsional jenis aspek yang ingin Anda sertakan dalam tugas {i>metadata<i}. Saat Anda mengimpor metadata, Anda dapat memodifikasi entri dan aspek yang ada dalam resource dalam lingkup pekerjaan Anda.

Untuk mendefinisikan cakupan pekerjaan, ikuti panduan berikut:

  • Grup entri: menentukan satu grup entri yang akan disertakan dalam tugas. Tugas ini hanya mengubah entri yang termasuk dalam grup entri ini. Grup entri dan tugas harus berada di region yang sama.

  • Jenis entri: tentukan satu atau beberapa jenis entri untuk disertakan dalam tugas. Pekerjaan hanya mengubah entri yang termasuk dalam tipe entri ini. Lokasi jenis entri harus sama dengan lokasi pekerjaan, atau jenis entri harus bersifat global.

  • Jenis aspek: opsional. Tentukan satu atau beberapa jenis aspek yang akan disertakan untuk bekerja. Jika Anda menentukan cakupan untuk jenis aspek, tugas tersebut memodifikasi hanya aspek yang termasuk dalam jenis aspek ini. Lokasi jenis aspek harus cocok dengan lokasi tugas, atau jenis aspek harus bersifat global.

Anda menentukan cakupan tugas saat membuat tugas metadata.

Mode sinkronisasi

Mode sinkronisasi menentukan apakah akan melakukan pembaruan penuh atau pembaruan inkremental pada entri dan aspek dalam tugas metadata.

  • FULL: didukung untuk entri. Semua entri dalam cakupan pekerjaan diubah.

    Jika entri ada di Dataplex tetapi tidak disertakan dalam file impor metadata, entri akan dihapus saat Anda menjalankan tugas metadata.

    Sinkronisasi penuh tidak didukung untuk aspek.

  • INCREMENTAL: didukung untuk aspek. Aspek hanya dimodifikasi jika file impor metadata menyertakan referensi ke aspek dalam Kolom updateMask dan kolom aspectKeys. Untuk mengetahui informasi selengkapnya tentang kolom ini dalam file impor metadata, lihat Bagian Struktur item impor dalam dokumen ini.

    Sinkronisasi inkremental tidak didukung untuk entri.

Anda menetapkan mode sinkronisasi saat membuat tugas metadata.

File impor metadata

File impor metadata adalah kumpulan entri dan aspek yang Anda ingin dimodifikasi. Mendefinisikan nilai yang akan ditetapkan untuk semua {i>field<i} yang dimiliki terhadap entri dan aspek ini. Anda menyiapkan file sebelum menjalankan tugas metadata.

Anda dapat menyediakan beberapa file impor metadata dalam tugas metadata yang sama.

Entri yang Anda berikan dalam file sepenuhnya menggantikan semua entri yang ada entri untuk sumber daya apa pun yang berada dalam ruang lingkup pekerjaan. Ini berarti bahwa Anda harus menyertakan nilai untuk semua entri dalam tugas, bukan hanya nilai yang yang ingin Anda tambahkan atau perbarui. Untuk mendapatkan daftar entri saat ini dalam project Anda untuk digunakan sebagai titik awal, gunakan Metode API entries.list.

Semua entri dan aspek yang Anda sertakan dalam file harus berasal dari grup entri, tipe entri, dan tipe aspek yang Anda tentukan dalam cakupan tugas.

Gunakan panduan di bagian berikut ini untuk membuat file impor metadata.

Struktur file

Setiap baris dalam file impor metadata berisi objek JSON yang sesuai ke satu item impor. Item impor adalah objek yang mendeskripsikan nilai yang memodifikasi suatu entri dan aspek-aspek yang terkait.

Anda dapat menyediakan beberapa item impor dalam satu file impor metadata. Namun, jangan menyediakan item impor yang sama lebih dari sekali dalam tugas metadata. Gunakan karakter baris baru (0x0a) untuk memisahkan setiap item impor.

File impor metadata dengan karakter baris baru di antara setiap tampilan item impor seperti contoh berikut:

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

Struktur item impor

Setiap item impor dalam file impor metadata mencakup kolom berikut. Contoh berikut diformat dengan baris baru agar mudah dibaca, tetapi ketika Anda menyimpan file, sertakan sebuah karakter baris baru hanya setelah tiap impor yang bermanfaat. Jangan sertakan jeda baris di antara kolom satu item impor.

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    }
    "aspects": {
      "ASPECT": {
        "data": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

Ganti kode berikut:

  • ENTRY_NAME: nama resource relatif entri, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID.
  • ENTRY_TYPE: nama resource relatif dari tipe entri yang digunakan untuk membuat entri ini, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.
  • entrySource: informasi dari sistem sumber tentang resource data yang diwakili oleh entri:
    • RESOURCE: nama resource dalam sumber sistem file.
    • SYSTEM: nama sistem sumber.
    • PLATFORM: platform yang berisi sistem sumber.
    • DISPLAY_NAME: nama tampilan yang mudah digunakan.
    • DESCRIPTION: deskripsi entri.
    • ENTRY_CREATE_TIMESTAMP: waktu entri yang dibuat di sistem sumber.
    • ENTRY_UPDATE_TIMESTAMP: waktu entri diperbarui di sistem sumber.
  • aspects: aspek yang dilampirkan pada entri. Objek aspect dan datanya disebut peta aspek.

    • ASPECT: aspek yang dilampirkan pada entri. Bergantung pada cara aspek dilampirkan ke entri, gunakan salah satu hal berikut format:

      • Jika aspek dilampirkan langsung ke entri, sediakan resource relatif nama jenis aspeknya, dalam format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.
      • Jika aspek dilampirkan ke jalur entri, berikan atribut path (jalur), dalam format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH.
    • KEY dan VALUE: konten aspek, sesuai dengan skema jenis aspeknya. Konten harus dienkode sebagai UTF-8. Ukuran maksimum kolom adalah 120 KB.

    • ASPECT_CREATE_TIMESTAMP: waktu saat aspek dibuat ke sistem sumber.

    • ASPECT_UPDATE_TIMESTAMP: saat aspek diperbarui ke sistem sumber.

    • PARENT_ENTRY: nama resource entri induk.

    • FULLY_QUALIFIED_NAME: nama entri yang dapat oleh sistem eksternal.

  • UPDATE_MASK_FIELDS: kolom yang akan diperbarui, di jalur yang relatif terhadap resource Entry. Pisahkan setiap kolom dengan koma.

    Dalam mode sinkronisasi entri FULL, Dataplex menyertakan jalur dari semua untuk entri yang dapat dimodifikasi, termasuk aspeknya.

    Kolom update_mask diabaikan saat entri dibuat atau dibuat ulang.

  • ASPECT_KEY: aspek yang akan diubah. Mendukung sintaks berikut:

    • ASPECT_TYPE_REFERENCE: cocok dengan jenis aspek untuk aspek yang melekat secara langsung pada entri.
    • ASPECT_TYPE_REFERENCE@PATH: cocok dengan jenis aspek dan jalur yang ditentukan.
    • ASPECT_TYPE_REFERENCE@*: cocok dengan jenis aspek untuk semua jalur.

    Ganti ASPECT_TYPE_REFERENCE dengan referensi ke jenis aspek, dalam format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.

    Jika Anda mengosongkan kolom ini, kolom akan dianggap menentukan aspek yang ada dalam entri yang ditentukan.

    Dalam mode sinkronisasi entri FULL, Dataplex secara implisit menambahkan kunci untuk semua aspek yang diperlukan dari sebuah entri.

Persyaratan file

File impor metadata memiliki persyaratan berikut:

  • File harus diformat sebagai Baris JSON , yang merupakan file JSON newline delimited. Gunakan karakter baris baru (0x0a) untuk memisahkan setiap item impor.
  • File harus menggunakan encoding karakter UTF-8.
  • Ekstensi file yang didukung adalah .jsonl dan .json.
  • Ukuran file harus kurang dari 1 GiB.
  • Entri dan aspek yang Anda tetapkan dalam file harus menjadi bagian dari mengimpor cakupan tugas.
  • File harus diupload ke bucket Cloud Storage. Jangan simpan file dalam folder bernama CLOUD_STORAGE_URI/deletions/.

Logika perbandingan

Dataplex menentukan entri dan aspek mana yang akan dimodifikasi dengan membandingkan dan stempel waktu yang Anda berikan dalam file impor metadata dengan nilai dan stempel waktu yang ada di project Anda.

Pada level yang tinggi, Dataplex memperbarui nilai dalam project Anda saat setidaknya satu perubahan yang diusulkan dalam file impor metadata akan berubah status proyek Anda saat pekerjaan berjalan, tanpa memperkenalkan {i>out-of-date<i} layanan otomatis dan data skalabel. Perubahan yang diusulkan harus dirujuk dalam bidang mask pembaruan atau aspek kolom kunci dalam file impor metadata.

Untuk setiap entri yang merupakan bagian dari ruang lingkup pekerjaan, Dataplex melakukan satu dari hal-hal berikut:

  • Membuat entri dan melampirkan aspek. Jika file impor metadata menyertakan entri yang tidak ada di proyek Anda, Dataplex membuat aspek entri dan aspek yang dilampirkan.
  • Menghapus entri dan aspek yang dilampirkan. Jika ada entri di tetapi file impor metadata tidak menyertakan entri, Dataplex menghapus entri dan aspek yang terkait dari proyek.
  • Memperbarui entri dan aspek yang dilampirkan. Jika ada entri di kedua dari file impor metadata dan di project Anda, Dataplex mengevaluasi stempel waktu sumber entri dan stempel waktu sumber aspek yang dikaitkan dengan entri untuk menentukan nilai mana yang akan diubah. Lalu: Dataplex melakukan satu atau beberapa hal berikut:

    • Membuat ulang entri. Jika sumber entri membuat stempel waktu di file impor metadata lebih baru daripada stempel waktu yang sesuai di project Anda, Dataplex akan membuat ulang entri di project Anda.
    • Memperbarui entri. Jika stempel waktu pembaruan sumber entri dalam metadata yang lebih baru daripada stempel waktu yang terkait dalam project Anda, Dataplex memperbarui entri dalam project Anda.
    • Membuat aspek. Jika aspek disertakan dalam objek entri di file impor metadata, tetapi tidak disertakan dalam kolom {i>update mask<i}, Dataplex membuat aspek.
    • Menghapus aspek. Jika aspek tidak disertakan dalam objek entri dalam file impor metadata, tetapi disertakan dalam kolom mask update, Dataplex menghapus aspek tersebut.
    • Memperbarui aspek. Jika stempel waktu update sumber aspek dalam metadata yang lebih baru daripada stempel waktu yang terkait dalam project Anda, Dataplex memperbarui aspek dalam project Anda. Dataplex juga memperbarui aspek jika entri terlampir tidak ada stempel waktu pembaruan sumber entri, atau jika stempel waktu sumber entri dalam file impor metadata lebih baru daripada stempel waktu yang terkait dalam project Anda.

      Namun, jika setidaknya satu aspek dalam file impor metadata memiliki stempel waktu daripada stempel waktu yang sesuai dalam project Anda, Dataplex tidak melakukan pembaruan apa pun untuk entri yang dilampirkan.

Membuat file impor metadata

Sebelum mengimpor metadata, buat file impor metadata untuk tugas Anda. Ikuti langkah-langkah berikut:

  1. Menyiapkan file impor metadata dengan mengikuti pedoman yang dijelaskan sebelumnya dalam dokumen ini.
  2. Upload file ke bucket Cloud Storage.

Anda dapat menyediakan beberapa file impor metadata dalam tugas metadata yang sama. Kepada menyediakan beberapa file, menyimpan file tersebut di Cloud Storage yang sama direktori VM dengan bucket. Saat menjalankan tugas, Anda menetapkan bucket, bukan file tertentu. Dataplex menyerap metadata dari semua file yang disimpan di {i>bucket<i}, termasuk file yang ada di dalam {i>subfolder<i}.

Menjalankan tugas impor metadata

Setelah Anda membuat file impor metadata, jalankan tugas impor metadata dengan menggunakan Compute Engine API.

REST

Untuk mengimpor metadata, gunakan Metode metadataJobs.create.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_NUMBER: nomor project Google Cloud Anda atau project ID.
  • LOCATION_ID: lokasi Google Cloud, seperti us-central1.
  • METADATA_JOB_ID: optional. ID tugas metadata.
  • CLOUD_STORAGE_URI: URI Bucket atau folder Cloud Storage yang berisi file impor metadata. Untuk selengkapnya informasi tentang persyaratan file, lihat File impor metadata.

  • ENTRY_GROUP: nama resource relatif dari grup entri yang dalam cakupan pekerjaan, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Berikan satu grup entri saja. Untuk informasi selengkapnya, lihat Cakupan pekerjaan.
  • ENTRY_TYPE: nama resource relatif dari jenis entri yang dalam cakupan pekerjaan, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID. Untuk informasi selengkapnya, lihat Cakupan pekerjaan.

  • ASPECT_TYPE: optional. Nama resource relatif suatu aspek yang termasuk dalam cakupan pekerjaan, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID. Untuk informasi selengkapnya, lihat Cakupan pekerjaan.
  • LOG_LEVEL: tingkat log yang akan diambil, seperti INFO atau DEBUG. Untuk informasi selengkapnya, lihat Melihat log tugas dan memecahkan masalah.

Metode HTTP dan URL:

POST https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

Meminta isi JSON:

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama.

Mendapatkan detail tentang tugas metadata

Untuk mendapatkan informasi tentang tugas metadata, seperti status tugas dan jumlah entri yang dimodifikasi, gunakan langkah-langkah berikut. Untuk informasi selengkapnya tentang cara memecahkan masalah tugas yang gagal, lihat Bagian Lihat log tugas dan pemecahan masalah dalam dokumen ini.

REST

Untuk mendapatkan informasi tentang tugas metadata, gunakan Metode metadataJobs.get.

Mendapatkan daftar tugas metadata

Anda bisa mendapatkan daftar tugas metadata terbaru. Pekerjaan yang lebih lama yang mencapai status terminal akan dihapus dari sistem secara berkala.

REST

Untuk mendapatkan daftar tugas metadata terbaru, gunakan Metode metadataJobs.list.

Membatalkan tugas metadata

Anda dapat membatalkan tugas metadata yang tidak ingin dijalankan.

REST

Untuk membatalkan tugas metadata, gunakan Metode metadataJobs.cancel.

Melihat log tugas dan memecahkan masalah

Gunakan Cloud Logging untuk melihat log suatu tugas metadata. Untuk informasi selengkapnya, lihat Pantau log Dataplex.

Anda mengonfigurasi level log saat membuat tugas metadata. Log berikut level tersedia:

  • INFO: menyediakan log di level tugas keseluruhan. Termasuk log gabungan tentang mengimpor item, tetapi tidak menentukan item impor yang mengalami error.
  • DEBUG: memberikan log mendetail untuk setiap item impor. Gunakan logging tingkat debug untuk memecahkan masalah dengan item impor tertentu. Misalnya, gunakan logging tingkat debug untuk mengidentifikasi resource yang hilang dari tugas ruang lingkup, entri, atau aspek yang tidak sesuai dengan tipe entri terkait atau jenis aspek, atau kesalahan konfigurasi lainnya pada file impor metadata.

Error validasi

Dataplex memvalidasi file impor metadata terhadap metadata dalam project Anda. Jika ada masalah validasi, status pekerjaan mungkin mengembalikan salah satu status berikut:

  • FAILED: terjadi saat file impor metadata mengalami error. Dataplex tidak mengimpor metadata apa pun dan tugas akan gagal. Contoh error dalam file impor metadata meliputi hal berikut:
    • Item dalam file tidak dapat diurai menjadi item impor yang valid
    • Entri atau aspek dalam file adalah milik grup entri, jenis entri, atau jenis aspek yang bukan bagian dari cakupan pekerjaan
    • Nama entri yang sama disebutkan lebih dari sekali dalam tugas
    • Jenis aspek yang ditentukan dalam peta aspek atau kunci aspek tidak menggunakan format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH
  • SUCCEEDED_WITH_ERRORS: terjadi jika file impor metadata dapat berhasil diurai, namun mengimpor item dalam file akan menyebabkan entri di proyek Anda berada dalam keadaan tidak konsisten. Dataplex mengabaikan entri tersebut, tetapi mengimpor sisa metadata dari file.

Gunakan log tugas untuk memecahkan masalah error.

Langkah selanjutnya