Meminta perubahan metadata batch dengan alur kerja tata kelola

Dokumen ini menjelaskan cara mengirimkan permintaan perubahan metadata batch untuk grup entri di Knowledge Catalog (sebelumnya Dataplex Universal Catalog) menggunakan REST API.

Jika tidak memiliki akses tulis langsung ke grup entri, Anda dapat mengelompokkan hingga 250 operasi pembuatan, pembaruan, dan penghapusan untuk entri dan link entri ke dalam satu permintaan perubahan untuk ditinjau dan disetujui.

Sebelum memulai

Untuk mengirimkan permintaan perubahan metadata batch, pastikan Anda telah mengaktifkan API yang diperlukan dan memiliki peran serta izin Identity and Access Management (IAM) yang diperlukan pada grup entri target.

Aktifkan Dataplex API, jika belum diaktifkan.

Peran yang diperlukan untuk mengaktifkan API

Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

Mengaktifkan API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan guna meminta perubahan metadata batch untuk grup entri, minta administrator untuk memberi Anda peran IAM berikut pada grup entri target:

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

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

Untuk mengetahui informasi selengkapnya tentang peran dan izin, lihat Peran IAM Knowledge Catalog.

Membuat permintaan perubahan metadata batch

Saat Anda mengirimkan permintaan perubahan batch, Knowledge Catalog akan memeriksa sintaksis permintaan dan memverifikasi bahwa jenis entri, jenis aspek, jenis link entri, dan entri induk yang direferensikan ada. Saat permintaan disetujui, Knowledge Catalog akan memeriksa apakah entri target dan link entri ada—misalnya, menampilkan error ALREADY_EXISTS saat membuat resource yang sudah ada atau error NOT_FOUND saat memperbarui atau menghapus resource yang tidak ada.

Saat pemberi persetujuan menyetujui permintaan perubahan batch, Knowledge Catalog akan otomatis menerapkan operasi dalam urutan dependensi berikut:

  1. Menghapus link entri.
  2. Menghapus entri.
  3. Membuat dan memperbarui entri.
  4. Membuat dan memperbarui link entri.

Permintaan perubahan batch tidak memberikan konsistensi transaksional atau rollback otomatis. Setelah disetujui, Knowledge Catalog akan mengevaluasi dan menerapkan setiap operasi satu per satu.

Perhatikan aturan referensi berikut saat membuat batch:

  • Jangan mereferensikan entri yang dihapus dalam batch yang sama: Anda tidak dapat membuat atau memperbarui link entri yang mereferensikan entri yang dihapus dalam batch yang sama, dan Anda tidak dapat menetapkan parentEntry ke entri yang Anda hapus dalam batch yang sama.
  • Cantumkan entri induk sebelum entri turunan: jika entri baru merujuk ke entri lain dalam batch yang sama sebagai parentEntry, cantumkan permintaan yang membuat entri induk sebelum permintaan yang membuat entri turunan. Saat Anda membuat entri atau link entri, kolom grup entri parent bersifat opsional. Jika Anda menghilangkan parent, Knowledge Catalog akan menggunakan grup entri di changePayload.name. Jika Anda menyertakan parent, nilainya harus cocok dengan changePayload.name.

Untuk mengirimkan permintaan perubahan metadata batch dasar, gunakan metode entryGroups.requestBatchMetadataChange:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi grup entri.
  • LOCATION: lokasi grup entri, seperti us-central1.
  • ENTRY_GROUP_ID: ID grup entri target.
  • ENTRY_ID: ID entri baru yang akan dibuat.
  • ENTRY_TYPE_ID: ID jenis entri untuk entri baru.
  • JUSTIFICATION: alasan mengapa permintaan perubahan metadata diperlukan, maksimal 1.024 karakter.

Layanan akan menampilkan respons yang berisi nama resource dari permintaan perubahan yang dibuat:

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

Memverifikasi permintaan perubahan batch yang dibuat

Untuk memeriksa permintaan perubahan yang dibuat, gunakan metode changeRequests.get:

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID"

Ganti kode berikut:

  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: region tempat resource berada, seperti us-central1.
  • CHANGE_REQUEST_ID: ID unik permintaan.

Layanan ini menampilkan resource ChangeRequest yang berisi payload batch:

Contoh respons untuk permintaan perubahan batch yang dikirimkan pengguna

{
  "name": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "uid": "eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32",
  "createTime": "2026-09-14T09:06:40.352156739Z",
  "updateTime": "2026-09-14T09:06:41.714939166Z",
  "justification": "Requesting creation of a new entry",
  "author": "requester@example.com",
  "state": "NEW",
  "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
  "etag": "0YSwO12PxwypRJj6kqM3CTZ9BYk4wk3yasxdiMDE3MU",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataRequest": {
    "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changes": [
      {
        "createEntryRequest": {
          "parent": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
          "entryId": "new-entry-id",
          "entry": {
            "entryType": "projects/my-project/locations/us-central1/entryTypes/my-entry-type"
          }
        }
      }
    ]
  }
}

Jika agen pengayaan membuat permintaan perubahan batch secara otomatis, kolom author akan berisi akun layanan agen pengayaan, dan kolom batchChangeMetadataRequest.description.job.name akan berisi nama resource pengayaan.

Membuat permintaan perubahan batch multi-resource

Untuk mengusulkan perubahan pada beberapa resource dalam satu grup entri, gunakan metode entryGroups.requestBatchMetadataChange. Misalnya, Anda dapat menggunakan metode ini untuk membuat entri pertama, membuat entri kedua dengan aspek terlampir, dan membuat link entri terarah yang menghubungkannya.

Untuk membuat permintaan perubahan batch multi-resource, kirim permintaan POST berikut:

Contoh permintaan untuk membuat permintaan perubahan batch multi-resource

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "changePayload": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "FIRST_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID"
            }
          }
        },
        {
          "createEntryRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryId": "SECOND_ENTRY_ID",
            "entry": {
              "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID",
              "aspects": {
                "PROJECT_ID.LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "ASPECT_FIELD_VALUE"
                  }
                }
              }
            }
          }
        },
        {
          "createEntryLinkRequest": {
            "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
            "entryLinkId": "ENTRY_LINK_ID",
            "entryLink": {
              "entryLinkType": "projects/PROJECT_ID/locations/LOCATION/entryLinkTypes/ENTRY_LINK_TYPE_ID",
              "entryReferences": [
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/FIRST_ENTRY_ID",
                  "type": "SOURCE"
                },
                {
                  "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/SECOND_ENTRY_ID",
                  "type": "TARGET"
                }
              ]
            }
          }
        }
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestBatchMetadataChange"

Ganti kode berikut:

  • PROJECT_ID: IDGoogle Cloud project yang berisi grup entri.
  • LOCATION: lokasi grup entri, seperti us-central1.
  • ENTRY_GROUP_ID: ID grup entri target.
  • FIRST_ENTRY_ID: ID entri kustom pertama, yang digunakan sebagai SOURCE di link entri.
  • SECOND_ENTRY_ID: ID entri kustom kedua dengan aspek terlampir, yang digunakan sebagai TARGET di link entri.
  • ENTRY_TYPE_ID: ID jenis entri untuk entri baru.
  • ASPECT_TYPE_ID: ID jenis aspek yang dilampirkan ke entri kedua.
  • ASPECT_FIELD_NAME: nama kolom di template aspek.
  • ASPECT_FIELD_VALUE: nilai untuk kolom aspek.
  • ENTRY_LINK_ID: ID link entri yang menghubungkan kedua entri.
  • ENTRY_LINK_TYPE_ID: ID jenis link entri, seperti my-entry-link-type.
  • JUSTIFICATION: penjelasan mengapa perubahan metadata ini diperlukan.

Layanan akan menampilkan respons yang berisi nama resource dari permintaan perubahan yang dibuat:

{
  "changeRequest": "projects/123456789012/locations/us-central1/changeRequests/eeb06bad-fc7f-49b9-9fb2-61d1ad4bad32"
}

Langkah berikutnya