Mengelola resource menggunakan Knowledge Catalog

Dokumen ini menjelaskan cara menelusuri dan mengelola resource Spanner menggunakan Knowledge Catalog.

Knowledge Catalog membuat katalog metadata tentang instance, database, tabel, kolom, dan tampilan Spanner di seluruh Google Cloud, sehingga memungkinkan agen AI dan alat analisis mengambil konteks yang relevan dan di-grounding.

Tentang Knowledge Catalog dan Spanner

Knowledge Catalog mengacu pada resource di Spanner dan di layanan Google Cloud lainnya sebagai aset. Di Knowledge Catalog, setiap aset Spanner, seperti instance, database, tabel, atau tampilan, direpresentasikan oleh entri katalog yang menyimpan metadata teknis dan bisnis (aspek) tentang resource.

Anda dapat menggunakan Knowledge Catalog dalam alur kerja berikut untuk menemukan dan memahami aset Spanner Anda:

  • Analisis: memahami dependensi antara aset data dan mengevaluasi kesesuaian aset untuk kasus penggunaan tertentu.
  • Pengelolaan perubahan: melacak modifikasi struktural di seluruh database.
  • Pergerakan data: melacak asal dan tujuan pipeline.
  • Evolusi skema: memantau definisi tabel dan kolom dari waktu ke waktu.
  • Grounding AI kontekstual: memberikan skema dan konteks bisnis kepada agen AI.

Knowledge Catalog otomatis membuat katalog metadata berikut untuk resource Spanner:

  • Nama resource dan nama yang sepenuhnya memenuhi syarat (FQN)
  • Lokasi (wilayah)
  • Stempel waktu pembuatan dan modifikasi terakhir
  • Definisi skema (untuk tabel dan tabel virtual)
  • Jenis data kolom, nullability, dan indikator kunci utama
  • Deskripsi dan label pengguna

Penemuan metadata Knowledge Catalog adalah proses otomatis yang memindai sumber data yang terhubung, seperti Spanner, untuk mengidentifikasi aset data seperti tabel, tampilan, dan database. Kemudian, Knowledge Catalog mengekstrak metadata teknis dari aset, seperti skema, deskripsi, dan lokasi.

Spanner menyinkronkan metadata ke Knowledge Catalog secara berkala, biasanya setiap enam jam, sehingga perubahan metadata yang dilakukan pada aset Spanner dapat memerlukan waktu sekitar enam jam untuk diterapkan.

Sebelum memulai

Sebelum menggunakan Knowledge Catalog dengan Spanner, selesaikan tugas penyiapan berikut:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Mengaktifkan Dataplex API untuk project.

    Mengaktifkan Dataplex API

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mengelola aset Spanner di Knowledge Catalog, minta administrator untuk memberi Anda peran IAM berikut pada project Anda:

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

Peran yang telah ditetapkan ini berisi izin yang diperlukan untuk mengelola aset Spanner di Knowledge Catalog. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mengelola aset Spanner di Knowledge Catalog:

  • Buat jenis aspek: dataplex.aspectTypes.create
  • Telusuri instance Spanner:
    • dataplex.projects.search
    • spanner.instances.get
  • Telusuri database, tabel, dan tampilan Spanner:
    • dataplex.projects.search
    • spanner.databases.get
  • Melihat aspek pada instance Spanner:
    • dataplex.aspectTypes.get
    • spanner.instances.get
  • Melihat aspek di database, tabel, dan tampilan Spanner:
    • dataplex.aspectTypes.get
    • spanner.databases.get
  • Lampirkan aspek ke resource Spanner menggunakan jenis aspek:
    • dataplex.aspectTypes.use
    • dataplex.entries.update

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

Knowledge Catalog mendukung penelusuran semantik, yang membantu Anda menemukan resource menggunakan bahasa sehari-hari, sehingga tidak memerlukan sintaksis penelusuran yang kompleks. Misalnya, masukkan kueri seperti List all Spanner tables related to sales.

Jika mau, Anda dapat menelusuri resource menggunakan kata kunci, filter, dan sintaksis penelusuran berbasis predikat tertentu.

Untuk menelusuri aset Spanner di Knowledge Catalog, ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Search Knowledge Catalog:

    Buka Penelusuran

  2. Di panel Filters, di bagian Systems, pilih Spanner.

    Knowledge Catalog menampilkan semua aset Spanner yang dapat Anda akses di project Google Cloud .

  3. Gunakan kolom penelusuran untuk memasukkan kueri bahasa alami, seperti List all Spanner tables related to sales.

  4. Opsional: Gunakan penelusuran yang difilter di halaman Penelusuran. Pilih filter di bagian Type, Projects, Locations, dan Aspect types.

  5. Opsional: Di kolom penelusuran, tambahkan parameter penelusuran setelah system=spanner. Pisahkan beberapa parameter dengan spasi atau gunakan tanda kurung dan operator logika AND, OR, dan NOT.

    Misalnya, untuk hanya melihat database, masukkan kueri berikut:

    system=spanner type=database

    Anda juga dapat menggunakan type=service untuk menelusuri instance, atau instance_config=CONFIGURATION_NAME untuk menelusuri konfigurasi instance.

    Untuk opsi kueri lainnya, lihat Sintaksis penelusuran untuk Knowledge Catalog.

  6. Dalam daftar hasil penelusuran, klik nama aset untuk membuka halaman detail entrinya di Knowledge Catalog.

Dari halaman detail entri, Anda dapat melakukan hal berikut:

  • Untuk melihat ringkasan aset dan menambahkan deskripsi, buka tab Details, lalu di bagian Overview, klik Add.
  • Untuk melihat atau melampirkan metadata bisnis dan operasional, buka tab Details, lalu di bagian Aspects, klik Add di samping Optional aspects.
  • Untuk melihat database anggota untuk sebuah instance, klik tab Entry list, lalu klik Show all children entries in search.
  • Untuk memeriksa jenis data, kunci, dan definisi kolom untuk tabel, klik tab Schema.

Kasus penggunaan: Penelusuran dari instance ke kolom

Dalam kasus penggunaan ini, Anda akan menelusuri instance Spanner, lalu melihat perincian salah satu database yang tercantum dalam instance untuk melihat tabel dan kolomnya.

  1. Di konsol Google Cloud , buka halaman Search Knowledge Catalog:

    Buka Penelusuran

  2. Di panel Filters, di bagian Systems, pilih Spanner.

  3. Untuk melihat semua instance Spanner di Knowledge Catalog, gunakan kolom penelusuran untuk memasukkan kueri bahasa alami, seperti List all Spanner instances, lalu tekan Enter.

  4. Pilih nama instance.

  5. Di halaman Spanner details, klik tab Entry list, lalu klik Show all children entries in search.

    Knowledge Catalog menampilkan database dalam instance. Jika tidak ada tab Daftar entri, kembali ke halaman Telusuri dan pilih instance lain.

  6. Pilih nama database. Di halaman Spanner database details, klik tab Entry list, lalu klik Show all children entries in search.

    Knowledge Catalog menampilkan tabel dalam database.

  7. Pilih nama tabel, lalu di halaman Spanner table details, klik Schema untuk melihat kolom tabel.

  8. Opsional: Untuk menambahkan aspek ke kolom, pilih kolom, lalu klik Tambahkan aspek.

Memperkaya metadata dengan aspek

Untuk memperkaya metadata dan menelusuri aset berdasarkan konteks kustom, Anda dapat membuat aspek berdasarkan jenis aspek (template yang dapat digunakan kembali) dan melampirkannya ke aset Spanner Anda. Aspek memungkinkan Anda menambahkan metadata bisnis terstruktur, seperti kepemilikan data, klasifikasi tata kelola, atau kebijakan retensi.

Misalnya, Anda dapat melampirkan aspek berikut ke kolom yang berisi nomor jaminan sosial, yang merupakan informasi identitas pribadi (PII):

pii:true
pii_type:SSN

Untuk melampirkan aspek ke aset Spanner, ikuti langkah-langkah berikut:

  1. Di halaman Search Knowledge Catalog, klik aset yang ingin Anda perkaya.
  2. Di halaman detail entri, pada tab Details, buka bagian Aspects.
  3. Di samping Optional aspects, klik Add.
  4. Telusuri dan pilih jenis aspek yang ingin Anda tambahkan, seperti skema kustom untuk tata kelola data atau privasi.
  5. Di jendela Add aspect, tentukan kolom aspek yang diperlukan.
  6. Klik Simpan.

Untuk mengetahui petunjuk mendetail tentang cara membuat jenis aspek dan mengelola aspek, lihat Mengelola aspek dan memperkaya metadata.

Aspek ekspor dan impor

Saat Anda memindahkan instance Spanner ke konfigurasi instance yang berbeda, proses ini akan menghapus entri dan aspek yang terkait dengan konfigurasi instance sumber di Knowledge Catalog. Untuk mempertahankan aspek kustom, Anda perlu melakukan hal berikut:

  1. Ekspor aspek yang terkait dengan entri dalam konfigurasi instance sumber.
  2. Pindahkan instance ke konfigurasi instance tujuan.
  3. Impor aspek ke dalam konfigurasi instance tujuan.

Mengekspor aspek dari konfigurasi instance sumber

Sebelum memindahkan instance, ambil aspek untuk entri Spanner Anda dalam konfigurasi instance sumber menggunakan Google Cloud CLI, Dataplex API, atau tugas ekspor metadata:

gcloud

Untuk mengambil aspek entri Spanner di grup entri sistem @spanner, gunakan perintah gcloud dataplex entries lookup:

gcloud dataplex entries lookup SOURCE_ENTRY_ID \
  --entry-group=@spanner \
  --location=LOCATION \
  --project=PROJECT_ID \
  --view=all

Ganti kode berikut:

  • SOURCE_ENTRY_ID: ID entri resource Spanner dalam konfigurasi instance sumber.

    Cara menemukan ID entri

    Untuk menemukan nama entri atau menerjemahkan nama yang sepenuhnya memenuhi syarat (FQN) seperti spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, gunakan perintah gcloud dataplex entries search.

  • LOCATION: region konfigurasi instance Spanner, seperti us-central1.

  • PROJECT_ID: ID project Google Cloud yang berisi instance Spanner.

REST API

Untuk mengambil aspek entri Spanner di grup entri sistem @spanner, kirim permintaan GET ke endpoint projects.locations.lookupEntry.

curl -X GET \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@spanner/entries/SOURCE_ENTRY_ID&view=ALL"

Ganti kode berikut:

  • ACCESS_TOKEN: token akses yang digunakan aplikasi Anda untuk melakukan autentikasi ke layanan. Misalnya, gunakan $(gcloud auth print-access-token).

  • PROJECT_ID: ID project Google Cloud yang berisi instance Spanner.

  • LOCATION: region konfigurasi instance Spanner, seperti us-central1.

  • SOURCE_ENTRY_ID: ID entri resource Spanner dalam konfigurasi instance sumber.

    Cara menemukan ID entri

    Untuk menemukan nama entri atau menerjemahkan nama yang sepenuhnya memenuhi syarat (FQN) seperti spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, gunakan perintah gcloud dataplex entries search.

Tugas ekspor

Untuk mengekspor metadata untuk beberapa entri dalam batch ke Cloud Storage, jalankan tugas ekspor metadata.

Memindahkan instance ke konfigurasi instance tujuan

Sebelum mengimpor aspek ke dalam konfigurasi instance tujuan, lakukan hal berikut:

  1. Pindahkan instance Spanner ke konfigurasi instance tujuan. Tunggu hingga metadata Spanner untuk instance yang dipindahkan disinkronkan ke Knowledge Catalog, yang dapat memerlukan waktu sekitar enam jam.

  2. Untuk memverifikasi bahwa sinkronisasi telah selesai, telusuri instance yang dipindahkan menggunakan salah satu metode berikut:

    • Di halaman Search Knowledge Catalog, masukkan kueri berikut:

      system=spanner instance_config=DESTINATION_CONFIG_NAME

    • Jalankan perintah gcloud dataplex entries search:

      gcloud dataplex entries search "fqn=spanner:PROJECT_ID.DESTINATION_CONFIG_ID.INSTANCE_ID" \
    --project=PROJECT_ID

    Jika perintah menampilkan entri untuk konfigurasi instance tujuan, berarti sinkronisasi telah selesai.

Mengimpor aspek ke konfigurasi instance tujuan

Setelah metadata disinkronkan, lampirkan aspek yang disalin ke entri dalam konfigurasi instance tujuan:

gcloud

Untuk melampirkan aspek yang disalin ke entri dalam konfigurasi instance tujuan, gunakan perintah gcloud dataplex entries update-aspects:

gcloud dataplex entries update-aspects DESTINATION_ENTRY_ID \
  --entry-group=@spanner \
  --location=DESTINATION_LOCATION \
  --project=PROJECT_ID \
  --aspects=ASPECTS_FILE

Ganti kode berikut:

  • DESTINATION_ENTRY_ID: ID entri resource Spanner yang dipindahkan dalam konfigurasi instance tujuan.

  • DESTINATION_LOCATION: region konfigurasi instance Spanner tujuan, seperti us-central1.

  • PROJECT_ID: ID project Google Cloud yang berisi instance Spanner.

  • ASPECTS_FILE: jalur ke file JSON atau YAML yang berisi aspek yang akan ditambahkan atau diperbarui.

REST API

Untuk melampirkan aspek yang diekspor ke entri dalam konfigurasi instance tujuan, gunakan metode REST API projects.locations.entryGroups.entries.patch, seperti yang ditunjukkan dalam contoh berikut:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"aspects":{"ASPECT_KEY":{"data":{"FIELD_NAME":"FIELD_VALUE"}}}}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/DESTINATION_LOCATION/entryGroups/@spanner/entries/DESTINATION_ENTRY_ID?updateMask=aspects"

Ganti kode berikut:

  • ACCESS_TOKEN: token akses yang digunakan aplikasi Anda untuk melakukan autentikasi ke layanan. Misalnya, gunakan $(gcloud auth print-access-token).

  • ASPECT_KEY: kunci aspek dalam format PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID untuk aspek tingkat entri, atau PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME untuk aspek tingkat kolom.

  • FIELD_NAME dan FIELD_VALUE: nama dan nilai kolom yang ditentukan oleh jenis aspek Anda.

  • PROJECT_ID: ID project yang berisi instance Spanner.

  • DESTINATION_LOCATION: region konfigurasi instance Spanner tujuan, seperti us-central1.

  • DESTINATION_ENTRY_ID: ID entri resource Spanner yang dipindahkan dalam konfigurasi instance tujuan.

Impor tugas

Untuk mengimpor aspek untuk beberapa entri dalam batch dari Cloud Storage, jalankan tugas impor metadata.

Langkah berikutnya