Mengelola permintaan perubahan dengan alur kerja tata kelola

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Catatan: Meminta perubahan metadata tunggal pada glosarium bisnis dan entri tersedia dalam pratinjau pribadi. Untuk meminta akses ke fitur ini, isi formulir akses.

Dokumen ini menjelaskan cara pemohon, pemberi persetujuan, dan administrator alur kerja mengelola permintaan tata kelola di Knowledge Catalog (sebelumnya Dataplex Universal Catalog).

Sebelum memulai

Untuk menggunakan alur kerja tata kelola, pastikan Anda telah mengaktifkan API yang diperlukan dan bahwa pemberi persetujuan dan administrator memiliki peran dan izin Identity and Access Management (IAM) yang diperlukan.

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 untuk mengelola permintaan tata kelola, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

• Menyetujui atau menolak permintaan akses produk data:
  • Dataplex Data Products Editor (roles/dataplex.dataProductsEditor)
  • Dataplex Data Products Admin (roles/dataplex.dataProductsAdmin)
• Meninjau dan menyetujui permintaan perubahan metadata:
  • Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
  • Dataplex Workflow Approver (roles/dataplex.workflowApprover)
• Melihat dan mengedit permintaan yang dibuat: Dataplex Change Request Owner (roles/dataplex.changeRequestOwner)
• Melihat dan mengedit permintaan yang dibuat oleh agen pengayaan: Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
• Melihat semua permintaan dan menghapus permintaan dalam status apa pun:
  • Dataplex Workflow Admin (roles/dataplex.workflowAdmin)
  • Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
• Konfigurasi notifikasi email pemberi persetujuan:
  • Dataplex Catalog Admin (roles/dataplex.catalogAdmin)
  • Dataplex Catalog Editor (roles/dataplex.catalogEditor)
  • Dataplex Glossary Owner (roles/dataplex.glossaryOwner)

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.

Catatan: Jika pemberi persetujuan menggunakan peran Dataplex Workflow Approver untuk menyetujui permintaan perubahan metadata, mereka juga harus memiliki akses tulis pada resource entri atau glosarium target, seperti Dataplex Catalog Editor atau Dataplex Entry Owner.

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

Mengelola permintaan sebagai pemohon

Sebagai pemohon, Anda memulai permintaan perubahan, seperti meminta akses ke produk data atau mengusulkan perubahan metadata. Setelah mengirimkan permintaan, Anda dapat memantau progresnya, melihat detail permintaan, mengedit detail untuk permintaan yang tertunda, atau menghapus permintaan dalam status NEW sebelum pemberi persetujuan menindaklanjutinya.

Melihat permintaan yang dibuat

Untuk melihat permintaan yang Anda buat atau memeriksa permintaan tertentu, lakukan hal berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab My Requests untuk melihat daftar permintaan Anda yang lalu dan yang tertunda.

REST

Untuk mencantumkan permintaan yang Anda buat, gunakan metode changeRequests.list:

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

Untuk melihat permintaan tertentu, 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.
• USER_EMAIL: alamat email Anda.
• CHANGE_REQUEST_ID: ID unik permintaan.

Untuk permintaan perubahan metadata batch, periksa kolom respons untuk mengidentifikasi cara permintaan dibuat:

• Permintaan yang dikirimkan pengguna: author adalah alamat email pemohon, dan batchChangeMetadataRequest.description.job tidak ditetapkan.
• Permintaan yang dibuat agen pengayaan: author adalah akun layanan agen pengayaan, dan batchChangeMetadataRequest.description.job.name ditetapkan ke ID operasi pengayaan.

Mengedit permintaan

Anda dapat memperbarui permintaan yang tertunda menggunakan REST API saat permintaan tersebut dalam status NEW atau FAILED. Memperbarui permintaan dalam status FAILED akan mereset statusnya ke NEW sehingga pemberi persetujuan dapat meninjaunya lagi. Siapa yang dapat mengedit permintaan perubahan metadata bergantung pada cara permintaan tersebut dibuat:

• Permintaan yang dikirimkan oleh pengguna: hanya penulis asli yang dapat mengirimkan permintaan PATCH untuk memperbarui justifikasi atau payload permintaan.
• Permintaan yang dihasilkan oleh agen pengayaan: selain penulis, peninjau dan pemberi persetujuan dapat mengirim permintaan PATCH saat permintaan berada dalam status NEW atau FAILED untuk mengumpulkan batch—misalnya, untuk mengubah nilai aspek yang diusulkan atau menghapus item dari array changes. Kolom author tetap menjadi akun layanan agen pengayaan.

Untuk memperbarui permintaan perubahan dalam proses, gunakan metode changeRequests.patch.

Untuk memperbarui hanya justifikasi permintaan, kirim permintaan PATCH berikut:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=justification"

Untuk memperbarui payload permintaan perubahan metadata batch, kirim permintaan PATCH berikut:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "justification": "NEW_JUSTIFICATION",
    "batchChangeMetadataRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "changes": [
        {
          "updateEntryRequest": {
            "entry": {
              "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/EXISTING_ENTRY_ID",
              "aspects": {
                "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID": {
                  "data": {
                    "ASPECT_FIELD_NAME": "UPDATED_ASPECT_FIELD_VALUE"
                  }
                }
              }
            },
            "updateMask": "aspects",
            "aspectKeys": [
              "ASPECT_PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID"
            ]
          }
        }
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID?updateMask=batchChangeMetadataRequest.changes,justification"

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: region tempat permintaan perubahan berada, seperti us-central1.
• CHANGE_REQUEST_ID: ID unik permintaan perubahan.
• NEW_JUSTIFICATION: justifikasi yang diperbarui untuk permintaan perubahan.
• ENTRY_GROUP_ID: ID grup entri target.
• EXISTING_ENTRY_ID: ID entri dalam payload batch yang diperbarui.
• ASPECT_PROJECT_ID: ID project yang berisi jenis aspek.
• ASPECT_LOCATION: lokasi jenis aspek, seperti us-central1 atau global.
• ASPECT_TYPE_ID: ID jenis aspek yang sedang diperbarui.
• ASPECT_FIELD_NAME: nama kolom aspek yang akan diperbarui.
• UPDATED_ASPECT_FIELD_VALUE: nilai yang diperbarui untuk kolom aspek.

Menghapus permintaan

Sebagai pemohon, Anda hanya dapat menghapus permintaan yang berada dalam status NEW. Untuk menghapus permintaan, lakukan hal berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab Permintaan Saya.

3. Cari baris yang berisi permintaan yang ingin Anda hapus. Jika perlu, terapkan filter untuk mengisolasi entri.

4. Klik Tindakan, lalu klik Hapus.

REST

Untuk menghapus permintaan, gunakan metode changeRequests.delete.

Misalnya, kirim permintaan DELETE berikut:

curl -X DELETE \
  -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 yang ingin Anda hapus.

Mengelola permintaan sebagai pemberi persetujuan

Sebagai pemberi persetujuan, Anda mengevaluasi dan menindaklanjuti permintaan tertunda yang dikirimkan untuk resource data Anda.

Notifikasi

Saat Anda menyetujui atau menolak permintaan, Knowledge Catalog akan memproses keputusan dan mengirimkan notifikasi email kepada pemohon beserta komentar ulasan Anda. Untuk permintaan batch, Knowledge Catalog mengirimkan notifikasi email setelah proses update selesai. Jika penulisnya adalah akun layanan, Knowledge Catalog tidak akan mengirimkan notifikasi.

Pertimbangan persetujuan

Anda tidak dapat menyetujui permintaan Anda sendiri. Pemberi persetujuan harus merupakan akun utama yang berbeda dan memiliki semua izin tulis dan penggunaan jenis yang diperlukan oleh perubahan yang diusulkan. Namun, agen pengayaan dapat menyetujui otomatis permintaannya sendiri berdasarkan keyakinan atau mengirimkannya ke pemberi persetujuan untuk ditinjau. Untuk permintaan perubahan metadata batch yang dihasilkan oleh agen pengayaan, Anda dapat mengedit payload permintaan saat permintaan berada dalam status NEW atau FAILED sebelum menyetujuinya.

Lihat permintaan yang tertunda

Untuk melihat permintaan yang menunggu peninjauan, lakukan tindakan berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab Persetujuan Tertunda untuk melihat permintaan yang menunggu peninjauan. Anda dapat memfilter permintaan menurut jenis resource, jenis permintaan, atau tanggal.

REST

Untuk mencantumkan permintaan yang menunggu peninjauan dalam project dan lokasi tertentu, gunakan metode changeRequests.list.

Misalnya, kirim permintaan GET berikut:

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

Ganti kode berikut:

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

Dalam daftar yang ditampilkan, permintaan perubahan metadata batch memiliki kolom changeType yang ditetapkan ke BATCH_CHANGE_METADATA. Permintaan yang dibuat oleh operasi agen pengayaan menyertakan ID operasi pengayaan di batchChangeMetadataRequest.description.job.name.

Contoh respons untuk permintaan perubahan batch yang tertunda

{
"changeRequests": [
  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Enrichment Agent Proposal: Batch Metadata Change",
    "author": "[e-mail]",
    "state": "NEW",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "changeType": "BATCH_CHANGE_METADATA",
    "batchChangeMetadataRequest": {
      "name": "projects/my-project/locations/us-central1/entryGroups/my-entry-group",
      "description": {
        "job": {
          "name": "projects/123456789012/locations/us-central1/enrichmentTasks/my-enrichment-task/runs/55199e83-1a1e-4837-bb8c-c402c6bee641"
        }
      },
      "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"
            }
          }
        }
      ]
    }
  }
]
}

Menyetujui permintaan

Untuk menyetujui permintaan, lakukan tindakan berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab Persetujuan Tertunda.

3. Temukan baris yang berisi permintaan yang ingin Anda setujui.

4. Klik Tindakan, lalu klik Setujui.

REST

Untuk menyetujui permintaan, gunakan metode changeRequests.approve.

Misalnya, kirim permintaan POST berikut:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:approve"

Ganti kode berikut:

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

Saat Anda menyetujui permintaan perubahan metadata batch yang dikirimkan oleh pengguna atau agen pengayaan, Knowledge Catalog akan memvalidasi izin IAM dan aturan payload Anda secara sinkron:

• Jika validasi berhasil, metode ini akan menampilkan ChangeRequest dalam status APPLYING saat Knowledge Catalog menjalankan batch di latar belakang:

  {
    "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
    "uid": "b326114f-472b-457d-81e8-98b8ad89c608",
    "justification": "Proposing new entry using RequestBatchMetadataChange",
    "author": "[e-mail]",
    "state": "APPLYING",
    "resource": "//dataplex.googleapis.com/projects/my-project/locations/us-central1/entryGroups/my-entry-group",
    "approver": "[e-mail]",
    "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"
            }
          }
        }
      ]
    }
  }
  ```

* If synchronous payload validation fails (for example, with an
`INVALID_ARGUMENT` or `NOT_FOUND` error), the request immediately
transitions to the `FAILED` state instead of `APPLYING`.
* If permission validation fails with a `PERMISSION_DENIED` error, the request
remains in the `NEW` state.

After background execution finishes, poll `changeRequests.get` to check the
final state (`APPROVED` or `FAILED`). If any changes in the batch fail,
`batchChangeMetadataResponse.failedRequests` lists each failed change by its
position in `changes` (starting at `0`) along with the error details:

```json
{
  "name": "projects/my-project/locations/us-central1/changeRequests/b326114f-472b-457d-81e8-98b8ad89c608",
  "state": "APPROVED",
  "changeType": "BATCH_CHANGE_METADATA",
  "batchChangeMetadataResponse": {
    "failedRequests": {
      "1": {
        "code": 5,
        "message": "Entry not found."
      }
    }
  }
}

Untuk mengetahui informasi selengkapnya tentang status permintaan, lihat Jalur pemrosesan alur kerja tata kelola.

Menolak permintaan

Untuk menolak permintaan, lakukan hal berikut:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab Persetujuan Tertunda.

3. Temukan baris yang berisi permintaan yang ingin Anda tolak.

4. Klik Tindakan, lalu klik Tolak.

5. Dalam dialog, masukkan alasan penolakan.

6. Klik Tolak untuk mengonfirmasi.

REST

Untuk menolak permintaan, gunakan metode changeRequests.reject.

Misalnya, kirim permintaan POST berikut:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "REJECTION_REASON"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/changeRequests/CHANGE_REQUEST_ID:reject"

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: region tempat resource berada, seperti us-central1.
• CHANGE_REQUEST_ID: ID unik permintaan perubahan yang ingin Anda tolak.
• REJECTION_REASON: justifikasi penolakan.

Memberikan komentar penolakan yang jelas akan membantu pemohon memahami keputusan dan menyempurnakan justifikasi mereka sebelum mengirim ulang permintaan.

Mengelola permintaan sebagai administrator alur kerja

Sebagai administrator alur kerja, Anda mengawasi permintaan tata kelola di seluruh organisasi, mengonfigurasi notifikasi email pemberi persetujuan, mengaudit histori persetujuan, dan menghapus permintaan dalam status apa pun.

Mengonfigurasi notifikasi email pemberi persetujuan

Anda dapat mengonfigurasi notifikasi email pemberi persetujuan di grup entri atau glosarium bisnis untuk menentukan hingga 10 alamat email yang akan otomatis diberi tahu setiap kali permintaan perubahan metadata tunggal atau batch dibuat untuk resource tersebut.

Untuk mengonfigurasi notifikasi pada grup entri, gunakan metode entryGroups.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID?updateMask=changeRequestConfig"

Untuk mengonfigurasi notifikasi di glosarium bisnis, gunakan metode glossaries.patch:

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "changeRequestConfig": {
      "approverEmails": [
        "APPROVER_EMAIL_1",
        "APPROVER_EMAIL_2"
      ]
    }
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID?updateMask=changeRequestConfig"

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: lokasi grup entri, seperti us-central1 atau global.
• ENTRY_GROUP_ID: ID grup entri.
• GLOSSARY_ID: ID glosarium bisnis.
• APPROVER_EMAIL_1, APPROVER_EMAIL_2: alamat email calon pemberi persetujuan yang akan diberi tahu saat permintaan perubahan dibuat. Anda dapat menentukan hingga 10 alamat email.

Melihat semua permintaan dan melacak histori persetujuan

Anda dapat melihat semua permintaan aktif dan historis di seluruh status untuk memantau alur kerja serta mengaudit akses produk data dan perubahan metadata:

Konsol

1. Di konsol Google Cloud , buka halaman Governance Workflows Knowledge Catalog.

   Buka Governance Workflows

2. Klik tab Approval Log untuk melihat persetujuan, penolakan, dan jejak audit historis yang telah selesai.

REST

Untuk mencantumkan semua permintaan aktif dan historis dalam project dan lokasi tertentu, gunakan metode changeRequests.list.

Misalnya, kirim permintaan GET berikut:

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

Ganti kode berikut:

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

Menghapus permintaan dalam status apa pun

Tidak seperti pemohon, yang hanya dapat menghapus permintaan dalam status NEW, administrator alur kerja dapat menghapus permintaan dalam status apa pun menggunakan konsol Google Cloud atau metode changeRequests.delete. Untuk mengetahui petunjuknya, lihat Menghapus permintaan.

Langkah berikutnya

• Pelajari lebih lanjut alur kerja tata kelola.
• Pelajari cara meminta perubahan metadata resource tunggal.
• Pelajari cara meminta perubahan metadata batch.