Mengimpor metadata menggunakan pipeline kustom

Dokumen ini menjelaskan cara mengimpor metadata Katalog Dataplex dari sistem pihak ketiga ke Dataplex menggunakan metode API impor metadata dan pipeline Anda sendiri. Metadata Katalog Dataplex terdiri dari entri dan aspeknya.

Jika Anda ingin menggunakan pipeline orkestrasi yang dikelola Google Cloud untuk mengekstrak dan mengimpor metadata, sebaiknya gunakan pipeline konektivitas terkelola. Dengan pipeline konektivitas terkelola, Anda dapat menggunakan konektor Anda sendiri yang mengekstrak metadata dan menghasilkan output dalam format yang dapat digunakan sebagai input oleh metode API impor metadata (file impor metadata). Kemudian, Anda menggunakan Alur Kerja untuk mengatur tugas pipeline.

Langkah-langkah tingkat tinggi

Untuk mengimpor metadata menggunakan API impor metadata, ikuti langkah-langkah tingkat tinggi berikut:

  1. Tentukan cakupan tugas.

    Selain itu, pahami cara 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 di bucket Cloud Storage.

  4. Jalankan tugas impor metadata.

Langkah-langkah di halaman ini mengasumsikan bahwa Anda telah memahami konsep Katalog Dataplex, termasuk grup entri, jenis entri, dan jenis aspek. Untuk mengetahui informasi selengkapnya, lihat Ringkasan Katalog Dataplex.

Sebelum memulai

Sebelum mengimpor metadata, selesaikan tugas-tugas di bagian ini.

Peran yang diperlukan

Untuk memastikan bahwa akun layanan Dataplex memiliki izin yang diperlukan untuk mengakses bucket Cloud Storage, minta administrator Anda untuk memberikan peran IAM Storage Object Viewer (roles/storage.objectViewer) dan izin storage.buckets.get ke akun layanan Dataplex di 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. Buat grup entri untuk entri yang ingin Anda impor.
  2. Buat jenis aspek untuk aspek yang ingin Anda impor.
  3. Buat jenis entri untuk entri yang ingin Anda impor.
  4. Buat bucket Cloud Storage untuk menyimpan file impor metadata Anda.

Komponen tugas metadata

Saat Anda mengimpor metadata, pertimbangkan komponen tugas metadata berikut:

  • Cakupan tugas: grup entri, jenis entri, dan jenis aspek yang akan disertakan dalam tugas.
  • Mode sinkronisasi: apakah akan melakukan update penuh atau update inkremental pada entri dan aspek dalam tugas.
  • File impor metadata: file yang menentukan nilai yang akan ditetapkan untuk entri dan aspek dalam tugas. Anda dapat menyediakan beberapa file impor metadata dalam tugas metadata yang sama. Anda menyimpan file di Cloud Storage.
  • Logika perbandingan: cara Dataplex menentukan entri dan aspek yang akan diubah.

Cakupan tugas

Cakupan tugas menentukan grup entri, jenis entri, dan secara opsional jenis aspek yang ingin Anda sertakan dalam tugas metadata. Saat mengimpor metadata, Anda akan mengubah entri dan aspek yang termasuk dalam resource dalam cakupan tugas.

Untuk menentukan cakupan tugas, ikuti panduan berikut:

  • Grup entri: tentukan satu grup entri yang akan disertakan dalam tugas. Tugas 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 yang akan disertakan dalam tugas. Tugas ini hanya mengubah entri yang termasuk dalam jenis entri ini. Lokasi jenis entri harus cocok dengan lokasi tugas, atau jenis entri harus bersifat global.

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

Anda menentukan cakupan tugas saat membuat tugas metadata.

Mode sinkronisasi

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

  • FULL: didukung untuk entri. Semua entri dalam cakupan tugas akan diubah.

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

    Sinkronisasi penuh tidak didukung untuk aspek.

  • INCREMENTAL: didukung untuk aspek. Aspek hanya diubah jika file impor metadata menyertakan referensi ke aspek di 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 menentukan mode sinkronisasi saat membuat tugas metadata.

File impor metadata

File impor metadata adalah kumpulan entri dan aspek yang ingin Anda ubah. File ini menentukan nilai yang akan ditetapkan untuk semua kolom yang termasuk dalam entri dan aspek ini. Anda menyiapkan file sebelum menjalankan tugas metadata.

Pedoman umum berikut berlaku:

  • Anda dapat memberikan beberapa file impor metadata dalam tugas metadata yang sama.

  • Entri yang Anda berikan dalam file akan sepenuhnya menggantikan semua entri yang ada untuk resource apa pun yang berada dalam cakupan tugas. Artinya, Anda harus menyertakan nilai untuk semua entri dalam tugas, bukan hanya nilai yang ingin Anda tambahkan atau perbarui. Untuk mendapatkan daftar entri saat ini dalam project Anda yang akan digunakan sebagai titik awal, gunakan metode API entries.list.

  • Anda harus menyediakan file impor metadata sebagai bagian dari tugas metadata. Jika Anda ingin menghapus semua data yang ada untuk entri yang berada dalam cakupan tugas, berikan file impor metadata kosong.

  • Semua entri dan aspek yang Anda sertakan dalam file harus termasuk dalam grup entri, jenis entri, dan jenis aspek yang Anda tentukan dalam cakupan tugas.

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

Struktur file

Setiap baris dalam file impor metadata berisi objek JSON yang sesuai dengan satu item impor. Item impor adalah objek yang menjelaskan nilai yang akan diubah untuk entri dan aspek yang terlampir.

Anda dapat memberikan beberapa item impor dalam satu file impor metadata. Namun, jangan berikan 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 item impor terlihat 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 menyertakan kolom berikut (lihat ImportItem). Contoh berikut diformat dengan jeda baris agar mudah dibaca, tetapi saat Anda menyimpan file, sertakan karakter baris baru hanya setelah setiap item impor. Jangan sertakan baris baru di antara kolom dari 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: informasi tentang entri dan aspek yang terlampir:

    • 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 jenis 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 sistem sumber.
      • 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 dibuat di sistem sumber.
      • ENTRY_UPDATE_TIMESTAMP: waktu entri diperbarui di sistem sumber.

    • aspects: aspek yang dilampirkan ke entri. Objek aspect dan datanya disebut peta aspek.

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

        • Jika aspek dilampirkan langsung ke entri, berikan nama resource relatif dari jenis aspeknya, dalam format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.
        • Jika aspek dilampirkan ke jalur entri, berikan jalur jenis aspek, dalam format PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH.

      • KEY dan VALUE: konten aspek, sesuai dengan template metadata jenis aspeknya. Konten harus dienkode sebagai UTF-8. Ukuran maksimum kolom adalah 120 KB. Kamus data diperlukan, meskipun kosong.

      • ASPECT_CREATE_TIMESTAMP: waktu aspek dibuat di sistem sumber.

      • ASPECT_UPDATE_TIMESTAMP: waktu aspek diperbarui di sistem sumber.

    • PARENT_ENTRY: nama resource entri induk.

    • FULLY_QUALIFIED_NAME: nama untuk entri yang dapat direferensikan oleh sistem eksternal. Lihat Nama yang sepenuhnya memenuhi syarat.

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

    Dalam mode sinkronisasi entri FULL, Dataplex menyertakan jalur semua kolom untuk entri yang dapat diubah, termasuk aspek.

    Kolom updateMask diabaikan saat entri dibuat atau dibuat ulang.

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

    • ASPECT_TYPE_REFERENCE: cocok dengan jenis aspek untuk aspek yang dilampirkan langsung ke 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 tersebut akan diperlakukan sebagai menentukan secara tepat aspek yang ada dalam entri yang ditentukan.

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

Persyaratan file

File impor metadata memiliki persyaratan berikut:

  • File harus diformat sebagai file JSON Lines, yang merupakan file JSON yang dibatasi baris baru. 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 setiap file impor metadata harus kurang dari 1 GiB. Ukuran total maksimum untuk semua data dalam tugas metadata adalah 3 GB. Hal ini mencakup semua file dan metadata yang terkait dengan tugas.
  • Entri dan aspek yang Anda tentukan dalam file harus menjadi bagian dari cakupan tugas metadata.
  • File harus diupload ke bucket Cloud Storage. Jangan simpan file di folder bernama CLOUD_STORAGE_URI/deletions/.

Logika perbandingan

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

Pada tingkat tinggi, Dataplex memperbarui nilai dalam project Anda saat setidaknya satu perubahan yang diusulkan dalam file impor metadata akan mengubah status project Anda saat tugas berjalan, tanpa memasukkan data yang sudah tidak berlaku. Perubahan yang diusulkan harus dirujuk di kolom update mask atau kolom kunci aspek dalam file impor metadata.

Untuk setiap entri yang merupakan bagian dari cakupan tugas, Dataplex melakukan salah satu hal berikut:

  • Membuat entri dan aspek yang terlampir. Jika file impor metadata menyertakan entri yang tidak ada dalam project Anda, Dataplex akan membuat entri dan aspek yang terlampir.
  • Menghapus entri dan aspek yang terlampir. Jika entri ada dalam project Anda, tetapi file impor metadata tidak menyertakan entri tersebut, Dataplex akan menghapus entri dan aspek yang terlampir dari project Anda.

  • Memperbarui entri dan aspek yang terlampir. Jika entri ada di file impor metadata dan di project Anda, Dataplex akan mengevaluasi stempel waktu sumber entri dan stempel waktu sumber aspek yang dikaitkan dengan entri untuk menentukan nilai mana yang akan diubah. Kemudian, Dataplex melakukan satu atau beberapa hal berikut:

    • Membuat ulang entri. Jika stempel waktu pembuatan sumber entri dalam file impor metadata lebih baru daripada stempel waktu yang sesuai dalam project Anda, Dataplex akan membuat ulang entri dalam project Anda.
    • Memperbarui entri. Jika stempel waktu pembaruan sumber entri dalam file impor metadata lebih baru daripada stempel waktu yang sesuai dalam project Anda, Dataplex akan memperbarui entri dalam project Anda.
    • Membuat aspek. Jika aspek tidak ada dalam project Anda, dan disertakan dalam objek entri, kolom update mask, dan kolom kunci aspek dalam file impor metadata, Dataplex akan membuat aspek tersebut.
    • Menghapus aspek. Jika aspek ada dalam project Anda, dan disertakan dalam kolom update mask dan kolom kunci aspek dalam file impor metadata, tetapi tidak disertakan dalam objek entri, Dataplex akan menghapus aspek tersebut.

    • Memperbarui aspek. Jika aspek ada dalam project Anda dan disertakan dalam objek entri, kolom update mask, dan kolom kunci aspek dalam file impor metadata, serta stempel waktu update sumber aspek dalam file impor metadata lebih baru daripada stempel waktu yang sesuai dalam project Anda, Dataplex akan memperbarui aspek tersebut.

      Jika stempel waktu pembaruan sumber aspek tidak diberikan dalam file impor metadata, tetapi entri yang sesuai ditandai untuk diperbarui, Dataplex juga akan memperbarui aspek.

      Namun, jika setidaknya satu aspek dalam file impor metadata memiliki stempel waktu yang lebih lama daripada stempel waktu yang sesuai dalam project Anda, Dataplex tidak akan 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 ini:

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

Anda dapat memberikan beberapa file impor metadata dalam tugas metadata yang sama. Untuk menyediakan beberapa file, simpan file di bucket Cloud Storage yang sama. Saat menjalankan tugas, Anda menentukan bucket, bukan file tertentu. Dataplex mengimpor metadata dari semua file yang disimpan di bucket, termasuk file yang ada di subfolder.

Menjalankan tugas impor metadata

Setelah membuat file impor metadata, jalankan tugas impor metadata menggunakan API.

REST

Untuk mengimpor metadata, gunakan metode metadataJobs.create.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_NUMBER: nomor project atau project ID Google Cloud Anda.
  • 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 informasi selengkapnya tentang persyaratan file, lihat File impor metadata.

  • ENTRY_GROUP: nama resource relatif dari grup entri yang berada dalam cakupan untuk tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Berikan hanya satu grup entri. Untuk informasi selengkapnya, lihat Cakupan tugas.

  • ENTRY_TYPE: nama resource relatif dari jenis entri yang berada dalam cakupan untuk tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID. Untuk informasi selengkapnya, lihat Cakupan tugas.

  • ASPECT_TYPE: optional. Nama resource relatif dari jenis aspek yang termasuk dalam cakupan tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID. Untuk informasi selengkapnya, lihat Cakupan tugas.
  • LOG_LEVEL: tingkat log yang akan diambil, seperti INFO atau DEBUG. Untuk mengetahui 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 diubah, gunakan langkah-langkah berikut. Untuk informasi selengkapnya tentang cara memecahkan masalah tugas yang gagal, lihat bagian Melihat log tugas dan memecahkan 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. Tugas lama yang telah mencapai status terminal akan dihapus secara berkala dari sistem.

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 tugas metadata. Untuk mengetahui informasi selengkapnya, lihat Memantau log Dataplex.

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

  • INFO: memberikan log di tingkat tugas secara keseluruhan. Menyertakan log gabungan tentang item impor, tetapi tidak menentukan item impor mana yang mengalami error.

  • DEBUG: memberikan log mendetail untuk setiap item impor. Gunakan logging tingkat debug untuk memecahkan masalah pada item impor tertentu. Misalnya, gunakan logging tingkat debug untuk mengidentifikasi resource yang tidak ada dalam cakupan tugas, entri, atau aspek yang tidak sesuai dengan jenis entri atau jenis aspek terkait, atau kesalahan konfigurasi lainnya dengan file impor metadata.

Error validasi

Dataplex memvalidasi file impor metadata berdasarkan metadata saat ini di project Anda. Jika ada masalah validasi, status tugas mungkin menampilkan 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 mencakup hal berikut:
    • Item dalam file tidak dapat diuraikan menjadi item impor yang valid
    • Entri atau aspek dalam file termasuk dalam grup entri, jenis entri, atau jenis aspek yang bukan bagian dari cakupan tugas
    • Nama entri yang sama ditentukan 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 saat file impor metadata berhasil diurai, tetapi mengimpor item dalam file akan menyebabkan entri dalam project Anda berada dalam status yang tidak konsisten. Dataplex mengabaikan entri tersebut, tetapi mengimpor metadata lainnya dari file.

Gunakan log tugas untuk memecahkan masalah error.

Langkah selanjutnya