Mengekspor metadata

Anda dapat mengekspor metadata dari Katalog Universal Dataplex untuk digunakan dalam sistem eksternal dengan menjalankan tugas ekspor metadata.

Anda mungkin ingin mengekspor metadata dalam skenario berikut:

  • Membuat kueri dan menganalisis metadata dengan BigQuery atau alat analisis data lainnya
  • Memproses metadata dalam jumlah besar secara terprogram, yang nantinya dapat Anda impor kembali ke Dataplex Universal Catalog
  • Mengintegrasikan metadata ke dalam aplikasi kustom atau alat pihak ketiga

Tugas ekspor metadata mengekspor snapshot metadata Dataplex Universal Catalog Anda. Metadata Dataplex Universal Catalog terdiri dari entri dan aspeknya. Langkah-langkah di halaman ini mengasumsikan bahwa Anda sudah memahami konsep metadata Dataplex Universal Catalog, termasuk grup entri, jenis entri, dan jenis aspek.

Cakupan tugas

Cakupan tugas menentukan metadata yang akan diekspor. Anda harus memberikan salah satu cakupan tugas berikut untuk setiap tugas ekspor metadata:

  • Organisasi: mengekspor metadata yang dimiliki organisasi Anda.
  • Project: mengekspor metadata yang termasuk dalam project tertentu.
  • Grup entri: mengekspor metadata yang termasuk dalam grup entri yang ditentukan.

Anda dapat membatasi lebih lanjut cakupan dengan menentukan jenis entri atau jenis aspek yang akan disertakan dalam tugas. Tugas ini hanya mengekspor entri dan aspek yang termasuk dalam jenis entri dan jenis aspek ini.

Kontrol Layanan VPC

Dataplex Universal Catalog menggunakan VPC Service Controls untuk memberikan keamanan tambahan bagi tugas ekspor metadata. Project tempat tugas berada menentukan perimeter Kontrol Layanan VPC, sebagai berikut:

  • Jika Anda menyetel cakupan tugas ke tingkat organisasi, hal berikut akan terjadi:
    • Cakupan ekspor adalah organisasi tempat tugas berada.
    • Hanya entri yang berada dalam perimeter Kontrol Layanan VPC yang diekspor.
    • Project apa pun yang berada dalam organisasi tugas, tetapi di luar perimeter Kontrol Layanan VPC akan dikecualikan.
  • Jika Anda menyetel cakupan tugas ke project atau grup entri, project atau grup entri harus berada dalam perimeter Kontrol Layanan VPC yang sama dengan tugas. Jika ada project atau grup entri yang melanggar aturan Kontrol Layanan VPC, tugas akan gagal.

Sebelum memulai

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

Peran yang diperlukan untuk pengguna akhir

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

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

Peran bawaan ini berisi izin yang diperlukan untuk mengelola tugas ekspor metadata. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengelola tugas ekspor metadata:

  • Mengekspor metadata:
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • Akses hasil yang diekspor: storage.objects.get

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Peran yang diperlukan untuk akun layanan Dataplex Universal Catalog

Untuk memastikan bahwa akun layanan Dataplex Universal Catalog memiliki izin yang diperlukan untuk mengakses bucket Cloud Storage, minta administrator Anda untuk memberikan izin berikut kepada akun layanan Dataplex Universal Catalog di bucket: storage.buckets.get, storage.objects.get, dan storage.objects.create.

Mengonfigurasi Google Cloud resource

  1. After installing the Google Cloud CLI, initialize it by running the following command:

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Buat bucket Cloud Storage untuk menyimpan hasil yang diekspor.

    Bucket harus berada di lokasi yang sama dan perimeter Kontrol Layanan VPC yang sama dengan tugas metadata.

Menjalankan tugas ekspor metadata

Bagian berikut menunjukkan cara mengekspor metadata dengan cakupan tugas yang berbeda.

Mengekspor metadata dari organisasi Anda

Untuk mengekspor metadata dari organisasi Anda, gunakan metode metadataJobs.create dan tetapkan boolean organizationLevel ke true.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • JOB_PROJECT: project Google Cloud tempat Anda menjalankan tugas metadata. Berikan nomor project atau ID project.
  • LOCATION_ID: lokasi Google Cloud , seperti us-central1.
  • METADATA_JOB_ID: optional. ID tugas metadata.
  • BUCKET: bucket Cloud Storage tujuan untuk mengekspor metadata.

    Secara opsional, Anda dapat menyertakan awalan kustom setelah nama bucket, dalam format gs://BUCKET/PREFIX/. Panjang maksimum awalan kustom adalah 128 karakter.

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama. Metadata yang diekspor disimpan ke bucket Cloud Storage.

Mengekspor metadata dari project tertentu

Untuk mengekspor metadata dari satu atau beberapa project, gunakan metode metadataJobs.create dan berikan daftar project.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • JOB_PROJECT: project Google Cloud tempat Anda menjalankan tugas metadata. Berikan nomor project atau ID project.
  • LOCATION_ID: lokasi Google Cloud , seperti us-central1.
  • METADATA_JOB_ID: optional. ID tugas metadata.
  • BUCKET: bucket Cloud Storage tujuan untuk mengekspor metadata.

    Secara opsional, Anda dapat menyertakan awalan kustom setelah nama bucket, dalam format gs://BUCKET/PREFIX/. Panjang maksimum awalan kustom adalah 128 karakter.

  • METADATA_SOURCE_PROJECT: project yang metadata-nya ingin Anda ekspor. Berikan nomor project atau ID project. Project harus berada di organisasi dan perimeter Kontrol Layanan VPC yang sama dengan tugas metadata.

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama. Metadata yang diekspor disimpan ke bucket Cloud Storage.

Mengekspor metadata dari grup entri tertentu

Untuk mengekspor metadata dari grup entri tertentu, gunakan metode metadataJobs.create dan berikan daftar grup entri.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • JOB_PROJECT: project Google Cloud tempat Anda menjalankan tugas metadata. Berikan nomor project atau ID project.
  • LOCATION_ID: lokasi Google Cloud , seperti us-central1.
  • METADATA_JOB_ID: optional. ID tugas metadata.
  • BUCKET: bucket Cloud Storage tujuan untuk mengekspor metadata.

    Secara opsional, Anda dapat menyertakan awalan kustom setelah nama bucket, dalam format gs://BUCKET/PREFIX/. Panjang maksimum awalan kustom adalah 128 karakter.

  • ENTRY_GROUP: nama resource relatif grup entri yang berada dalam cakupan tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Grup entri harus berada dalam project yang sama dengan tugas metadata.

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama. Metadata yang diekspor disimpan ke bucket Cloud Storage.

Mengekspor metadata dari jenis entri atau jenis aspek tertentu

Untuk mengekspor metadata dari jenis entri atau jenis aspek tertentu, tetapkan cakupan tugas utama, seperti di tingkat organisasi, seperti yang ditunjukkan dalam contoh berikut. Kemudian, berikan daftar jenis entri, jenis aspek, atau keduanya.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • ENTRY_TYPE: optional. Nama resource relatif dari jenis entri yang berada dalam cakupan tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ASPECT_TYPE: optional. Nama resource relatif dari jenis aspek yang berada dalam cakupan tugas, dalam format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.

Metode HTTP dan URL:

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

Meminta isi JSON:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
      "entry_types": [
        "ENTRY_TYPE",
        # Additional entry types
      ],
      "aspect_types": [
        "ASPECT_TYPE",
        # Additional aspect types
      ]
    },
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Respons mengidentifikasi operasi yang berjalan lama. Metadata yang diekspor disimpan ke bucket Cloud Storage.

Mendapatkan detail tentang tugas metadata

Untuk mendapatkan informasi tentang tugas metadata, seperti status tugas dan jumlah entri yang diekspor, gunakan metode metadataJobs.get.

Hasil ekspor metadata

Tugas ekspor metadata mengekspor snapshot metadata Katalog Universal Dataplex Anda pada saat tugas metadata dibuat.

Mengekspor konten file

Isi file output mengikuti format yang sama dengan file impor metadata yang digunakan untuk tugas impor metadata. Anda dapat menggunakan file output secara langsung sebagai input untuk tugas impor metadata.

Lokasi file ekspor

Dataplex Universal Catalog menyimpan file hasil ekspor ke bucket Cloud Storage sebagai objek.

Jalur objek untuk setiap file output dibuat menggunakan nama bucket dan awalan kustom yang Anda tentukan dalam tugas ekspor, diikuti dengan jalur yang dibuat sistem. Jalur yang dibuat sistem dirancang untuk integrasi dengan BigQuery. Jalur objek menggunakan format berikut:

gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl

Perhatikan hal berikut:

  • Jalur yang dibuat sistem dimulai dengan format partisi Hive standar untuk tanggal pembuatan tugas ekspor. Format ini didukung oleh BigQuery. Untuk informasi selengkapnya, lihat Memuat data yang dipartisi secara eksternal.
  • Parameter consumer_project adalah project tempat Anda menjalankan tugas ekspor metadata. Parameter project adalah project yang berisi metadata yang Anda ekspor.
  • Anda dapat menggunakan kembali ID tugas metadata jika tugas sebelumnya dihapus. Namun, saat Anda menghapus tugas, tindakan tersebut tidak menghapus file yang diekspor oleh tugas tersebut. Artinya, jika Anda menggunakan kembali ID tugas yang dihapus, Anda mungkin melihat ID tugas duplikat di jalur file output.
  • Setiap file output diberi nama dengan nomor file, yang merupakan bilangan bulat yang dimulai dari 1.

    Jika tugas ekspor metadata berisi banyak entri, tugas tersebut akan membagi hasil menjadi beberapa file untuk membatasi ukuran setiap file output. Jumlah maksimum entri di setiap file output adalah 1.000.000.

Contoh file output

Berikut adalah contoh file output untuk tugas ekspor metadata yang menyertakan beberapa project:

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl

Berikut adalah contoh file output untuk tugas ekspor metadata yang berisi grup entri besar. Hasil untuk grup entri dibagi menjadi beberapa file.

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl

Menganalisis metadata yang diekspor di BigQuery

Jika ingin menganalisis metadata yang diekspor di BigQuery, Anda dapat membuat tabel eksternal untuk metadata yang diekspor. Membuat tabel eksternal memungkinkan Anda membuat kueri data yang diekspor tanpa pemuatan atau transformasi data tambahan. Misalnya, Anda dapat menghitung jumlah entri menurut grup entri, menemukan entri yang memiliki aspek tertentu, atau melakukan analisis tambahan di BigQuery.

Lakukan tindakan berikut:

  • Buat tabel eksternal untuk data yang dipartisi Hive. Berikan informasi berikut:

    • Select file from Cloud Storage bucket: berikan jalur ke folder Cloud Storage yang berisi file metadata yang diekspor. Untuk menyertakan semua file dalam bucket, gunakan karakter pengganti tanda bintang (*). Contohnya, gs://export-bucket/example-folder/*.
    • File format: pilih JSONL (Newline delimited JSON).
    • Centang kotak Source data partitioning, lalu untuk Select Source URI Prefix, berikan awalan URI Cloud Storage untuk tabel BigQuery guna menentukan partisi. Contohnya, gs://export-bucket/example-folder/.
    • Mode inferensi partisi: pilih opsi Otomatis menyimpulkan jenis.
    • Jenis tabel: pilih opsi Tabel eksternal.
    • Schema: klik tombol Edit as text, lalu masukkan definisi skema berikut untuk file ekspor:

      [
        {
          "name": "entry",
          "type": "RECORD",
          "mode": "NULLABLE",
          "fields": [
            {
              "mode": "NULLABLE",
              "name": "name",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "entryType",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "createTime",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "updateTime",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "aspects",
              "type": "JSON"
            },
            {
              "mode": "NULLABLE",
              "name": "parentEntry",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "fullyQualifiedName",
              "type": "STRING"
            },
            {
              "mode": "NULLABLE",
              "name": "entrySource",
              "type": "RECORD",
              "fields": [
                {
                  "mode": "NULLABLE",
                  "name": "resource",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "system",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "platform",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "displayName",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "description",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "labels",
                  "type": "JSON"
                },
                {
                  "mode": "REPEATED",
                  "name": "ancestors",
                  "type": "RECORD",
                  "fields": [
                    {
                      "mode": "NULLABLE",
                      "name": "name",
                      "type": "STRING"
                    },
                    {
                      "mode": "NULLABLE",
                      "name": "type",
                      "type": "STRING"
                    }
                  ]
                },
                {
                  "mode": "NULLABLE",
                  "name": "createTime",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "updateTime",
                  "type": "STRING"
                },
                {
                  "mode": "NULLABLE",
                  "name": "location",
                  "type": "STRING"
                }
              ]
            }
          ]
        }
      ]
      

BigQuery membuat tabel eksternal yang berisi metadata yang diekspor. Skema tabel mencakup kolom skema entry, dengan setiap baris mewakili satu entri. Untuk mengetahui informasi selengkapnya tentang kolom untuk entri, lihat ImportItem. Skema tabel juga berisi partisi file ekspor, seperti yang dijelaskan di bagian Lokasi file ekspor dalam dokumen ini.

Setelah membuat tabel eksternal, Anda dapat membuat kueri tabel menggunakan sintaksis GoogleSQL. Misalnya, untuk membuat kueri jenis entri yang diekspor, gunakan pernyataan berikut:

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

Langkah berikutnya