Integrasi Knowledge Catalog

Dokumen ini menjelaskan cara Cortex Framework terintegrasi dengan Knowledge Catalog, yang bertindak sebagai lapisan tata kelola untuk produk data perusahaan di seluruh organisasi Anda. Dokumen ini juga menjelaskan cara alat sinkronisasi Knowledge Catalog Google Cloud Cortex Framework membantu mendaftarkan dan menyinkronkan produk data Google Cloud Cortex Framework dengan Knowledge Catalog, sehingga menyederhanakan penemuan dan berbagi yang aman.

Dengan mengaktifkan integrasi ini, produk data Cortex Framework yang di-deploy, termasuk deskripsi bisnis yang diperkaya, metadata kepemilikan, dan set data serta tabel BigQuery fisik yang mendasarinya, akan otomatis dikatalogkan dan dapat ditemukan di Knowledge Catalog.

Manfaat utama

Mengintegrasikan Cortex Framework dengan Knowledge Catalog memberikan manfaat utama berikut:

  • Kemampuan penemuan data otomatis: Pengguna dapat menjelajahi dan menelusuri produk data perusahaan standar langsung dalam antarmuka pengguna Knowledge Catalog tanpa memerlukan entri katalog manual.
  • Konteks bisnis yang diperkaya: Mengimpor nama tampilan, deskripsi bisnis mendetail, dan URL dokumentasi secara otomatis langsung dari file manifest.yaml ke Knowledge Catalog.
  • Penautan aset terpadu: Menghubungkan setiap tabel dasar pelaporan yang sesuai langsung ke produk data Knowledge Catalog yang sesuai. Hal ini memberikan visibilitas langsung kepada konsumen data tentang objek data fisik yang mendukung domain bisnis tertentu.
  • Rekonsiliasi siklus proses dan penyimpangan otomatis: Saat model data perusahaan Anda berkembang, menjalankan alat sinkronisasi akan otomatis merekonsiliasi metadata dan link aset. Alat ini mendaftarkan tabel baru, memperbarui definisi yang diubah, dan menghapus link yang tidak digunakan lagi sekaligus melindungi item katalog yang tidak dikelola dan dibuat pengguna.
  • Keamanan pengelolaan sistem: Menggunakan label sistem khusus (cortex-framework-created dan cortex-framework-version) untuk mengidentifikasi dan mengelola hanya resource yang dibuat oleh Cortex Framework, sehingga mencegah penimpaan aset Knowledge Catalog yang dikelola pelanggan secara tidak sengaja.

Cara integrasi berfungsi

Komponen utama Solusi Google Cloud Cortex Framework

Integrasi Knowledge Catalog didukung oleh alat sinkronisasi cortex-kc-sync (tools.dataplex.kc_sync). Saat dijalankan, alat sinkronisasi akan melakukan alur kerja multi-langkah berikut:

Sinkronisasi Google Cloud Cortex Framework dengan Knowledge Catalog

1. Konfigurasi dan ekstraksi manifes

Alat sinkronisasi mengurai file konfigurasi config/config.yaml global Anda untuk mengidentifikasi semua modul produk data yang diaktifkan (data.modules.products) dan set data BigQuery targetnya (data.targets).

Untuk setiap modul yang diaktifkan, alat sinkronisasi mengekstrak metadata deskriptif dari manifest.yaml modul (menggunakan penyedia modul ruang kerja):

  • displayName: Judul produk data yang dapat dibaca manusia.
  • description: Ringkasan bisnis modul.
  • documentation: URL yang mengarah ke dokumentasi modul internal atau eksternal.

2. Penemuan aset BigQuery

Daripada memverifikasi daftar statis definisi tabel, cortex-kc-sync membuat kueri BigQuery (list_dataset_tables) untuk menemukan secara dinamis tabel dan tampilan mana yang sudah di-deploy di set data target Anda.

Alat ini menyelesaikan dan memfilter tabel dengan mencari label pelacakan tertentu yang diterapkan selama deployment:

  • cortex-framework-namespaced-module-type yang cocok dengan jalur modul yang sepenuhnya memenuhi syarat (misalnya, cortex.sap.products.sales_performance), atau
  • cortex-framework-module-type yang cocok dengan nama jenis modul kanonis (misalnya, sales_performance).

Hanya tabel dan tampilan yang terwujud yang memiliki label ini di BigQuery yang akan dikatalogkan dan ditautkan sebagai aset di bawah produk data.

3. Rekonsiliasi dan pelabelan resource terkelola

Alat sinkronisasi berkomunikasi dengan dataplex_v1 API (DataProductClient) untuk merekonsiliasi setiap produk data yang ditemukan di target Google Cloud location:

  • Pembuatan (NEEDS_CREATION): Jika produk data tidak ada, alat sinkronisasi akan membuat produk data Knowledge Catalog baru yang diisi dengan metadata manifes yang diekstrak dan menautkan aset BigQuery yang diselesaikan. Alat ini menandai resource dengan dua label sistem:

    • cortex-framework-created: ditetapkan ke "true"
    • cortex-framework-version: ditetapkan ke "7-0-0"

  • Perlindungan resource yang tidak dikelola (NOT_MANAGED): Jika produk data Knowledge Catalog dengan ID yang sama sudah ada di katalog, tetapi tidak memiliki label sistem ini (is_managed_data_product == False), alat sinkronisasi akan melewatinya untuk melindungi aset katalog yang dibuat pengguna atau yang sudah ada.

  • Pembaruan (NEEDS_UPDATE): Jika produk data terkelola ada dan memiliki perubahan dalam metadata atau komposisi tabelnya, alat sinkronisasi akan memperbarui definisi produk data Knowledge Catalog dan merekonsiliasi aset BigQuery yang ditautkan (BigQueryAssetLinks). Alat ini otomatis membuat link DataAsset baru untuk tabel yang baru ditambahkan dan menghapus link yang tidak digunakan lagi, sekaligus mempertahankan link yang tidak berubah.

Penyiapan dan konfigurasi

Bagian ini menjelaskan prasyarat, konfigurasi metadata, dan langkah-langkah eksekusi yang diperlukan untuk menyiapkan dan menjalankan sinkronisasi antara Cortex Framework dan Knowledge Catalog.

Prasyarat

Sebelum menjalankan sinkronisasi Knowledge Catalog, pastikan Anda telah memenuhi persyaratan berikut:

Mengaktifkan Google Cloud layanan

Di bagian ini, kita akan mengaktifkanlayanan berikut di Google Cloud project Anda: Google Cloud

  • Cloud Dataplex API (dataplex.googleapis.com)

Aktifkanlayanan Google Cloud ini menggunakan Cloud Shell dengan menjalankan perintah berikut di terminal Anda:

gcloud config set project PROJECT_ID

gcloud services enable dataplex.googleapis.com \
         --project=PROJECT_ID

Peran untuk project target

Untuk mendapatkan izin yang Anda perlukan untuk menyinkronkan Knowledge Catalog, minta administrator Anda untuk memberi Anda peran IAM berikut di project target Anda:

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

Peran bawaan ini berisi izin dataplex.dataProducts.create, dataplex.dataProducts.update, dataplex.dataAssets.create, dataplex.dataAssets.delete , yang diperlukan untuk menyinkronkan Knowledge Catalog.

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

Untuk memberikan peran yang diminta kepada pengguna, Anda dapat menggunakan skrip:

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.editor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.dataProductsEditor"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/dataplex.entryOwner"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.metadataViewer"
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_EMAIL" \
        --role="roles/bigquery.dataViewer"

Pipeline Dataform yang dieksekusi

Anda harus menjalankan cortex-build-and-deploy atau cortex-deploy terlebih dahulu seperti yang dijelaskan dalam Panduan deployment dan menjalankan tindakan pipeline Dataform untuk mewujudkan tabel dan tampilan BigQuery sebelum mencoba menyinkronkan dengan Knowledge Catalog. Untuk mengetahui petunjuk langkah demi langkah tentang cara menjalankan transformasi, lihat Langkah-langkah pasca-deployment.

Mengonfigurasi metadata produk data

Anda dapat menyesuaikan metadata bisnis yang ditampilkan di Knowledge Catalog dengan mengubah file manifest.yaml yang terletak di dalam setiap direktori modul produk data (misalnya, src/data_modules/cortex/sap/products/accounts_payable/manifest.yaml).

Contoh berikut menunjukkan cara menentukan displayName, description, dan documentation dalam manifes modul:

displayName: "SAP Accounts Payable"
description: >
  SAP Data Product for Accounts Payable containing conformed vendor invoices, 
  payment aging schedules, and financial accounting documents.
documentation: "https://docs.cloud.google.com/cortex/docs/data-product"

category: foundational_product
type: accounts_payable
dependencies:
  sapModule:
    supportedVersions:
      - ecc
      - s4
    tables:
      ecc:
        - bsik
        - bsak
      s4:
        - acdoca
        - bseg
      common:
        - bkpf
    modulePath: cortex.sap.foundations.sap
builder: sap_product

Menjalankan perintah sinkronisasi

Setelah produk data Anda di-deploy dan diwujudkan di BigQuery, jalankan alat CLI cortex-kc-sync menggunakan uv:

uv run cortex-kc-sync --config config/config.yaml --owner-email USER_EMAIL

Untuk mengetahui daftar lengkap flag dan argumen yang tersedia, lihat referensi CLI KC sync (uv run cortex-kc-sync).

Verifikasi sinkronisasi Knowledge Catalog

Untuk memverifikasi keberhasilan sinkronisasi antara aset Google Cloud Cortex Framework dan Knowledge Catalog, ikuti langkah-langkah berikut:

  • Di Google Cloud konsol, buka Knowledge Catalog
  • Opsional: Di dialog penelusuran, Anda dapat menggunakan salah satu filter cepat seperti Data Products atau Tables.
  • Di kolom penelusuran layar utama Knowledge Catalog, klik Filters.
  • Di tampilan Filters yang terbuka, pilih dari menu drop-down Project project yang Anda gunakan untuk menyinkronkan produk data Google Cloud Cortex Framework.
  • Setelah sinkronisasi berhasil, Anda kini dapat memilih atau menelusuri aset data yang diekspos oleh Google Cloud Cortex Framework, termasuk semua metadata yang dipublikasikan.

Mengotomatiskan alur kerja

Di lingkungan produksi, sebaiknya jalankan cortex-kc-sync secara otomatis sebagai langkah pasca-pemrosesan di dalam pipeline orkestrasi CI/CD atau DAG Knowledge Catalog (Airflow) segera setelah eksekusi pipeline Dataform berhasil:

  1. Membuat dan men-deploy: Jalankan cortex-deploy (uv run cortex-deploy --config config/config.yaml) untuk mengompilasi dan menyiapkan konfigurasi ke Dataform.
  2. Menjalankan transformasi: Memicu eksekusi Dataform untuk mewujudkan lapisan dasar data dan tabel pelaporan yang sesuai di BigQuery.
  3. Sinkronisasi katalog: Jalankan cortex-kc-sync (uv run cortex-kc-sync --config config/config.yaml) untuk memverifikasi pembuatan tabel dan menyinkronkan semua produk data, deskripsi, dan link asal data yang diperbarui langsung ke Knowledge Catalog.

Langkah berikutnya