Data mentah hingga perkiraan dalam hitungan detik dengan agen AI

1. Pengantar

Dalam codelab ini, Anda akan berperan sebagai ilmuwan data untuk perusahaan Froyo fiktif yang meluncurkan rasa produk baru, "Midnight Swirl". Untuk memastikan peluncuran global yang sukses, bisnis harus menjawab pertanyaan penting terkait bahan, permintaan pasar, dan laba atas investasi (ROI). Alur kerja end-to-end ini menunjukkan cara Katalog Pengetahuan Google Cloud (sebelumnya dikenal sebagai Dataplex) dan Lakehouse untuk Apache Iceberg (sebelumnya dikenal sebagai BigLake) menjembatani kesenjangan antara data tidak terstruktur "gelap" dan memberikan insight bisnis yang dapat ditindaklanjuti menggunakan Gemini di IDE (VS Code) Anda melalui lapisan tata kelola terpadu.

Alur kerja peramalan data mentah

Yang akan Anda lakukan

  • Penemuan tidak terstruktur: Resep PDF yang disimpan di Cloud Storage di-crawl oleh Knowledge Catalog DataScan. Buat Tabel objek di BigQuery untuk PDF yang dipindai. Dengan menggunakan Inferensi Semantik Vertex AI, sistem "membaca" PDF untuk mengekstrak informasi terstruktur tentang produk, alergen, bahan, dan atribut terkait. Kemudian, secara cerdas, Gemini akan membuat skema untuk data yang disimpan dalam PDF.
  • Metadata terpadu: Data yang diekstrak dari file PDF disimpan langsung ke BigQuery sebagai tabel lebar native, dan tampilan dibuat untuk membantu kueri umum. Set data input independen yang berisi data penjualan historis disimpan di Tabel Apache Iceberg di Google Cloud Storage. Tabel Iceberg ini akan digabungkan dengan data yang diekstrak di BigQuery pada langkah berikutnya.
  • Analisis lintas mesin: Dengan menggunakan Managed Service for Apache Spark (sebelumnya dikenal sebagai Dataproc) dengan Katalog REST Iceberg, Anda akan menggabungkan metadata PDF baru ini dan data semantik terstruktur yang disimpulkan (dari tabel dan tampilan BigQuery) dengan data penjualan terstruktur yang disimpan dalam Tabel Apache Iceberg di Google Cloud Storage. Hal ini diatur oleh template sesi interaktif Managed Apache Spark yang digunakan sebagai kernel Jupyter Notebook yang memastikan setelan keamanan dan komputasi yang konsisten untuk tugas Spark.
  • Insight semantik: Dengan menggabungkan data produk yang disimpulkan dengan data pelanggan dan penjualan (di BigQuery), demo ini dapat mengekstrak insight seperti mengidentifikasi data alergen dan perkiraan pendapatan.
  • Tata kelola otonom: Seluruh siklus proses—mulai dari pemindaian penemuan hingga eksekusi Spark—diatur melalui template, petunjuk, aturan, dan otomatisasi yang didorong agen yang siap digunakan Gemini, sehingga membuktikan bahwa AI dapat mengelola infrastruktur yang mendukung analisis.

Yang Anda butuhkan

Menyelesaikan codelab ini dapat menimbulkan biaya, yang diperkirakan kurang dari $5 untuk penggunaan umum. Untuk mendapatkan perkiraan biaya mendetail berdasarkan proyeksi penggunaan atau harga saat ini, gunakan Kalkulator Harga Google Cloud.

Pastikan Anda memiliki prasyarat berikut untuk menyelesaikan codelab.

2. Sebelum memulai

Buat Project Google Cloud

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

  1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
  2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
    gcloud auth list
  3. Pastikan project Anda dikonfigurasi:
    gcloud config get project
  4. Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Aktifkan API yang diperlukan

Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:

  gcloud services enable \
    dataplex.googleapis.com \
    datacatalog.googleapis.com \
    discoveryengine.googleapis.com \
    bigqueryconnection.googleapis.com \
    bigquery.googleapis.com \
    biglake.googleapis.com \
    dataproc.googleapis.com \
    metastore.googleapis.com \
    dataform.googleapis.com \
    notebooks.googleapis.com \
    aiplatform.googleapis.com \
    cloudresourcemanager.googleapis.com \
    serviceusage.googleapis.com \
    secretmanager.googleapis.com \
    storage.googleapis.com

Mendownload aset codelab

Repositori ini berisi file Parquet, resep, pemasok, copilot-instructions.md, template.yaml, dan quickstart.py untuk digunakan dengan codelab ini. Pastikan Anda mendownload file ini.

Untuk mendownload file, lakukan hal berikut:

  1. Di Cloud Shell, jalankan perintah berikut:
    git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/next-26-keynotes.git
  2. Buka folder yang baru dibuat:
    cd next-26-keynotes
  3. Tarik folder data-cloud-demo
    git sparse-checkout set genkey/data-cloud-demo
  4. Setelah checkout selesai, buka folder data-cloud-demo dan ekstrak file ZIP untuk mengakses aset codelab.

3. Menyiapkan Lakehouse untuk data pelanggan Froyo

Di bagian ini, Anda akan membuat katalog di Lakehouse untuk menggunakan metastore Lakehouse bagi alur kerja Anda. BigLake menciptakan interoperabilitas antara mesin kueri Anda dengan menawarkan satu sumber tepercaya untuk semua data Iceberg Anda. Hal ini memungkinkan mesin kueri, seperti Apache Spark, menemukan, membaca metadata, dan mengelola tabel Iceberg secara konsisten.

Peran yang diperlukan

Pastikan Anda memiliki peran Identity and Access Management (IAM) berikut:

  • roles/biglake.viewer
  • roles/bigquery.user
  • roles/bigquery.dataEditor
  • roles/biglake.editor
  • roles/biglake.metadataViewer
  • roles/bigquery.connectionUser
  • roles/storage.objectUser
  • roles/storage.objectViewer
  • roles/storage.objectCreator
  • roles/storage.admin

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran IAM, lihat Memberikan peran IAM.

Membuat katalog Lakehouse dengan bucket

Buat katalog Lakehouse untuk mengelola metadata tabel Iceberg Anda. Anda terhubung ke katalog ini di tugas Spark untuk membuat dan mengkueri tabel Iceberg.

  1. Di konsol Google Cloud, buka Lakehouse.
  2. Klik Buat katalog. Halaman Buat katalog akan terbuka.
  3. Untuk Catalog type, pilih Iceberg Rest catalog.
  4. Untuk Select your Lakehouse catalog bucket options, pilih Single bucket catalog.
  5. Untuk Default catalog Cloud Storage bucket, klik Browse, lalu klik Create new bucket.
  6. Di halaman Buat bucket, lakukan hal berikut:
  7. Di bagian Mulai, masukkan nama unik global yang memenuhi persyaratan nama bucket.
  8. Di bagian Pilih tempat untuk menyimpan data Anda, pilih Region untuk Jenis lokasi, lalu masukkan wilayah Anda. Contoh, us-west1.
  9. Di bagian Choose how to control access to objects, hapus centang pada kotak Enforce public access prevention on this bucket.
    Dengan cara ini, Anda dapat menyimulasikan skenario dunia nyata seperti menghosting konten web publik atau repositori data bersama. Tanpa perubahan ini, bucket akan menerapkan kebijakan "khusus pribadi" yang ketat; setiap upaya untuk mengakses aset Anda akan menghasilkan error 403 terlarang, meskipun Anda berhasil memberikan izin publik ke file.
  10. Klik Lanjutkan > Buat > Pilih > Lanjutkan.
  11. Untuk Authentication method, pilih Credential vending mode.
  12. Klik Buat.Katalog Anda akan dibuat dan halaman Detail katalog akan terbuka.
  13. Di bagian Authentication method, klik Set bucket permissions.
  14. Di dialog, klik Konfirmasi.Tindakan ini akan memverifikasi bahwa akun layanan katalog Anda memiliki peran Storage Object User di bucket penyimpanan Anda.
  15. Dari halaman Detail katalog, salin jalur URI katalog REST. Gunakan jalur ini selama tugas Menjalankan tugas Spark.

Upload file Parquet ke bucket

Untuk mengupload file Parquet ke root bucket Anda, lakukan hal berikut:

  1. Di konsol Google Cloud, buka halaman Bucket Cloud Storage.
  2. Dalam daftar bucket, klik nama bucket. Misalnya, acai_demo.
  3. Di tab Objects untuk bucket, klik Upload > Upload files.
  4. Pilih file dari folder Parquet yang Anda clone di bagian Sebelum memulai codelab ini.
  5. Klik Buka.

4. Menyiapkan jaringan VPC

Buat jaringan Virtual Private Cloud (VPC) dan subnet yang memungkinkan resource berkomunikasi dengan Google API tanpa terhubung ke internet publik, serta firewall yang memungkinkan traffic internal mengalir bebas di antara node pemrosesan data Anda.

  1. Di konsol Google Cloud, buka halaman jaringan VPC.
  2. Klik Create VPC network.
  3. Masukkan Name untuk jaringan. Misalnya, acai-network.
  4. Untuk mengonfigurasi unit transmisi maksimum (MTU) jaringan, centang kotak Setel MTU secara otomatis.
  5. Pilih Automatic untuk Subnet creation mode.
  6. Di bagian Firewall rules, centang semua kotak untuk IPv4 firewall rules.
  7. Klik Buat.

Mengaktifkan Akses Google Pribadi

Node Dataproc Serverless tidak memiliki alamat IP publik. Untuk berkomunikasi dengan Katalog Lakehouse dan Cloud Storage, subnet harus mengaktifkan Akses Google Pribadi.

  1. Di konsol Google Cloud, buka halaman jaringan VPC.
  2. Klik nama jaringan yang berisi subnet tempat Anda perlu mengaktifkan Akses Google Pribadi. Misalnya, us-west1.
  3. Klik nama subnet. Halaman detail Subnet akan ditampilkan.
  4. Klik Edit.
  5. Di bagian Akses Google Pribadi, pilih Aktif.
  6. Klik Simpan.

5. Membuat dan menjalankan tugas Spark

Untuk membuat dan membuat kueri tabel Iceberg, upload tugas PySpark dengan pernyataan Spark SQL yang diperlukan. Kemudian, jalankan tugas dengan Managed Service for Spark.

Upload quickstart.py ke bucket Cloud Storage Anda

Setelah meng-clone aset codelab, perbarui skrip quickstart.py dengan detail project Anda dan upload ke bucket Cloud Storage.

  1. Buka skrip quickstart.py di editor teks.
  2. Ganti placeholder BUCKET_NAME dalam skrip dengan nama bucket Cloud Storage Anda dan simpan.
  3. Di konsol Google Cloud, buka bucket Cloud Storage.
  4. Klik nama bucket Anda. Misalnya, acai_demo.
  5. Di tab Objects, klik Upload > Upload files.
  6. Di file browser, pilih file quickstart.py yang telah diupdate, lalu klik Open.

Jalankan tugas Spark

Setelah mengupload skrip quickstart.py, jalankan sebagai tugas batch Managed Service for Spark.

  1. Untuk mengonfigurasi variabel, jalankan perintah berikut di Cloud Shell.
    # Configuration Variables
export PROJECT_ID="<PROJECT_ID>"
export REGION="<REGION>"
export BUCKET_NAME="<BUCKET_NAME>"
export SUBNET="<SUBNET>"
export LAKEHOUSE_CATALOG_ID="<LAKEHOUSE_CATALOG_ID>"
export CATALOG_URI_ID="<CATALOG_URI_ID>"
    Ganti kode berikut:
    • LAKEHOUSE_CATALOG_ID: nama resource katalog Lakehouse yang berisi file aplikasi PySpark Anda. Misalnya, acai_demo
    • PROJECT_ID: project ID Google Cloud Anda.
    • REGION: region tempat menjalankan workload batch Managed Service for Spark. Misalnya, us-west1.
    • BUCKET_NAME: nama bucket Cloud Storage Anda. Misalnya, acai_demo.
    • SUBNET: nama subnet VPC Anda. Misalnya, acai-network.
    • CATALOG_URI_ID: ID URI katalog Lakehouse yang Anda salin saat membuat katalog Lakehouse dengan bucket. Misalnya, https://biglake.googleapis.com/iceberg/v1/restcatalog.
  2. Di Cloud Shell, jalankan batch job Managed Service for Spark berikut menggunakan skrip quickstart.py.
      gcloud dataproc batches submit pyspark gs://${BUCKET_NAME}/quickstart.py \
     --project=${PROJECT_ID} \
     --region=${REGION} \
     --subnet=${SUBNET} \
     --version=2.2 \
     --properties="\
  spark.sql.defaultCatalog=${LAKEHOUSE_CATALOG_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}=org.apache.iceberg.spark.SparkCatalog,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.type=rest,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.uri=${CATALOG_URI_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.warehouse=gs://${BUCKET_NAME},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.header.x-goog-user-project=${PROJECT_ID},\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
  spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.rest-metrics-reporting-enabled=false,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.header.X-Iceberg-Access-Delegation=vended-credentials,\
  spark.sql.catalog.${LAKEHOUSE_CATALOG_ID}.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token"
    Anda dapat mengamati status tugas Spark yang sedang berjalan di Batch Dataproc.Saat tugas selesai, tugas akan menampilkan output yang mirip dengan berikut ini:
     All tables registered successfully!
 Batch [126fa2226a904d2e944c8eecbe0b1840] finished.
 metadata:
   '@type': type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata
   batch: projects/PROJECT_ID/locations/REGION/batches/126fa2226a904d2e944c8eecbe0b1840
   batchUuid: 3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
   createTime: '2026-04-09T13:17:26.222727Z'
   description: Batch
   labels:
     goog-dataproc-batch-id: 126fa2226a904d2e944c8eecbe0b1840
     goog-dataproc-batch-uuid: 3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
     goog-dataproc-drz-resource-uuid: batch-3bff88ca-64d6-4c16-b9ad-2a47ae93ebff
     goog-dataproc-location: REGION
   operationType: BATCH
 name: projects/PROJECT_ID/regions/REGION/operations/47bc59e8-5082-3af9-89a0-22289aa5f4b9

6. Mengkueri tabel dari BigQuery

Dengan berhasil menjalankan tugas batch Spark, Anda telah menggunakan Managed Service for Spark Serverless sebagai mesin komputasi terdistribusi untuk mendaftarkan beberapa tabel, satu per file Parquet dalam Lakehouse Metastore. Pendaftaran ini memungkinkan Google Cloud memperlakukan file mentah Anda di Cloud Storage sebagai tabel berperforma tinggi yang terstruktur.

Langkah-langkah berikut akan memandu Anda mengonfirmasi bahwa metadata telah disinkronkan dengan benar, sehingga memastikan bahwa data Anda tidak hanya disimpan dengan aman, tetapi juga dapat ditemukan dan dikueri sepenuhnya melalui antarmuka BigQuery.

  1. Di konsol Google Cloud, buka BigQuery.
  2. Di editor kueri, masukkan pernyataan berikut. Kueri menggunakan sintaksis project.namespace.dataset.table.
    SELECT * FROM `<PROJECT_ID>.<NAMESPACE>.<ICEBERG_DATASET>.<ICEBERG_TABLE>`
    Misalnya, SELECT * FROM PROJECT_ID.acai_demo.acai_dataset.order_items.
    Ganti kode berikut:
    • PROJECT_ID: project ID Google Cloud Anda.
    • NAMESPACE: namespace yang dibuat pada langkah sebelumnya sebagai hasil dari tugas Spark, yang dapat Anda temukan di halaman penjelajah objek BigQuery. Misalnya, acai_demo.
    • ICEBERG_DATASET: nama set data dalam katalog Iceberg, misalnya, acai_dataset.
    • ICEBERG_TABLE: nama tabel dalam set data Iceberg, misalnya, order_items.
  3. Klik Run. Hasil kueri menampilkan data yang Anda masukkan dengan tugas Spark.Hasil data untuk tabel dari BigQuery

7. Menyiapkan file data produk tidak terstruktur

Di bagian ini, Anda akan membuat struktur organisasi dalam BigQuery untuk menyimpan data resep dan pemasok Froyo, khususnya untuk detail produk Froyo. Hal ini juga membuat Koneksi Resource Cloud, yang berfungsi sebagai "jembatan" aman yang memungkinkan BigQuery membaca file dari sumber eksternal seperti Cloud Storage.

Buat bucket dan upload file detail Froyo

Buat dan upload file pemasok dan resep ke bucket Cloud Storage.

  1. Di konsol Google Cloud, buka halaman Bucket Cloud Storage.
  2. Klik Buat.
  3. Di halaman Buat bucket, masukkan informasi bucket Anda. Setelah setiap langkah berikut, klik Lanjutkan untuk melanjutkan ke langkah berikutnya:
  4. Di bagian Mulai, masukkan nama bucket. Misalnya, acai_pdfs.
  5. Di bagian Pilih tempat untuk menyimpan data Anda, pilih Region, lalu masukkan region Anda. Misalnya, us-west1.
  6. Di bagian Choose how to control access to objects, hapus centang pada kotak Enforce public access prevention on this bucket.
  7. Klik Buat.
  8. Pada daftar bucket, klik bucket yang Anda buat. Misalnya, acai_pdfs.
  9. Di tab Objects untuk bucket, klik Upload > Upload folders.
  10. Pilih folder recipes yang Anda ekstrak di bagian Sebelum Anda memulai codelab ini.
  11. Klik Upload.
  12. Ulangi proses upload untuk folder suppliers.

Membuat koneksi

Buat Koneksi Resource Cloud. Tindakan ini akan menghasilkan Akun Layanan unik yang bertindak sebagai "kartu identitas" BigQuery untuk mengakses file eksternal.

  1. Buka halaman BigQuery.
  2. Di panel kiri, klik Explorer. Jika Anda tidak melihat panel kiri, klik Luaskan panel kiri untuk membuka panel.
  3. Di panel Explorer, luaskan nama project Anda, lalu klik Connections.
  4. Di halaman Koneksi, klik Buat koneksi.
  5. Untuk jenis Connection, pilih Vertex AI remote models, remote functions, BigLake and Spanner (Cloud Resource).
  6. Di kolom Connection ID, masukkan nama ID koneksi. Misalnya, acai_pdf_connection. Pastikan untuk mencatat ID ini karena Anda akan memerlukannya saat menyiapkan pemindaian data nanti dalam codelab ini.
  7. Tetapkan Location type ke Region, lalu pilih region. Misalnya, us-west1. Koneksi harus ditempatkan bersama dengan resource Anda yang lain seperti set data.
  8. Klik Create connection.
  9. Klik Go to connection.
  10. Di panel Connection info, salin ID akun layanan untuk digunakan pada langkah berikutnya. Akun layanan akan terlihat seperti bqcx-175930350285-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com.

Mengelola akses ke akun layanan

Berikan akses ke akun layanan agar Lakehouse dapat membaca PDF Anda.

  1. Buka halaman IAM & Admin.
  2. Klik Grant access. Dialog Add principals akan terbuka.
  3. Di kolom New principals, masukkan ID akun layanan yang Anda salin sebelumnya.
  4. Di kolom Pilih peran, tambahkan peran berikut:
    • roles/storage.objectUser
    • roles/storage.objectViewer
    • roles/bigquery.user
    • roles/bigquery.dataEditor
    • roles/aiplatform.user
    • roles/storage.admin
    • roles/dataproc.serviceAgent
  5. Klik Simpan.

Untuk mengetahui informasi selengkapnya tentang peran IAM di BigQuery, lihat Peran dan izin bawaan.

8. Mengelola izin untuk tugas DataScan

Buat akun layanan (identitas) khusus untuk Spark dan Dataform, lalu berikan izin yang tepat kepada akun layanan tersebut—bersama dengan agen layanan otomatis Google—yang diperlukan untuk membaca penyimpanan, menjalankan tugas BigQuery, dan menggunakan Vertex AI untuk penemuan.

Akses IAM untuk Spark dan Dataform

  1. Di konsol Google Cloud, buka halaman Create service account.
  2. Jika belum dipilih, pilih project Google Cloud Anda.
  3. Klik Create service account.
  4. Masukkan nama akun layanan. Misalnya, sa-spark-stg1. Konsol Google Cloud membuat ID akun layanan berdasarkan nama ini. Edit ID jika diperlukan. Anda tidak dapat mengubah ID nanti.
  5. Untuk menetapkan kontrol akses, klik Buat dan lanjutkan, lalu lanjutkan ke langkah berikutnya.
  6. Pilih peran IAM berikut untuk diberikan ke akun layanan pada project.
    • roles/dataproc.worker
    • roles/storage.objectUser
    • roles/bigquery.dataEditor
    • roles/bigquery.jobUser
    • roles/aiplatform.user
    • roles/dataplex.discoveryPublishingServiceAgent
  7. Setelah selesai menambahkan peran, klik Lanjutkan.
  8. Klik Selesai untuk menyelesaikan pembuatan akun layanan.

Izin koneksi BigQuery untuk mengakses Knowledge Catalog

  1. Di konsol Google Cloud, buka halaman Bucket Cloud Storage.
  2. Dalam daftar bucket, klik nama bucket yang Anda buat untuk Froyo. Misalnya, acai_pdfs.
  3. Di tab Permissions, klik Grant access. Dialog Tambahkan akun utama akan muncul.
  4. Di kolom New principals, masukkan ID akun Layanan BigQuery Anda. Akun layanan akan terlihat seperti bqcx-175930350285-qn3a@gcp-sa-bigquery-condel.iam.gserviceaccount.com.
  5. Pilih satu (atau beberapa) peran berikut dari menu drop-down Select a role.
    • roles/storage.objectUser
    • roles/dataplex.serviceAgent
    • roles/dataplex.securityAdmin
    • roles/aiplatform.serviceAgent
    • roles/dataplex.discoveryPublishingServiceAgent
  6. Klik Simpan.

9. Menyiapkan Knowledge Catalog

Buat Katalog Pengetahuan untuk menyatukan data terkait Froyo dan mengotomatiskan penemuan file tidak terstruktur (seperti resep PDF dan pemasok PDF).

Membuat DataScan melalui curl

Di bagian ini, Anda akan membuat pemindaian untuk bucket Cloud Storage (misalnya, acai_pdfs) dengan menambahkan datascan_ID dan mengarahkannya ke set data BigQuery Anda. Setelah itu, Knowledge Catalog akan otomatis membuat entri untuk PDF Anda di BigQuery.

  1. Untuk memindai PDF (pemasok dan resep), jalankan perintah berikut:
    # 1. Set your variables
PROJECT_ID="<PROJECT_ID>"
REGION="<REGION>"
ENV_SUFFIX="stg1"
DATASCAN_ID="froyo-profile-${ENV_SUFFIX}"
BUCKET_NAME="<BUCKET_NAME>"

# 2. Set this to the Name of the connection you created in Step 7
CONNECTION_ID="<CONNECTION_ID_NAME>"

# 3. Define the API Endpoint
DATAPLEX_API="dataplex.googleapis.com/v1/projects/${PROJECT_ID}/locations/${REGION}"

# 4. Create the DataScan via CURL
echo "Creating Dataplex DataScan: ${DATASCAN_ID}..."

curl -X POST "https://$DATAPLEX_API/dataScans?dataScanId=${DATASCAN_ID}" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d '{
"data": {
   "resource": "//storage.googleapis.com/projects/'"${PROJECT_ID}"'/buckets/'"${BUCKET_NAME}"'"
   },
"executionSpec": {
   "trigger": {
      "on_demand": {}
   }
},
"dataDiscoverySpec": {
   "bigqueryPublishingConfig": {
      "tableType": "BIGLAKE",
      "connection": "projects/'"${PROJECT_ID}"'/locations/'"${REGION}"'/connections/'"${CONNECTION_ID}"'"
   },
   "storageConfig": {
      "unstructuredDataOptions": {
      "entity_inference_enabled": true
      }
   }
   }
}'
  2. Perintah curl menampilkan hasil Knowledge Catalog DataScan, mirip dengan gambar berikut. Hasil pemindaian data

Menjalankan tugas

Jalankan perintah berikut:

  gcloud dataplex datascans run $DATASCAN_ID --location=$REGION

Mendeskripsikan tugas

Untuk mendeskripsikan tugas, jalankan perintah berikut:

  gcloud dataplex datascans describe $DATASCAN_ID --location=$REGION

Menghapus tugas pemindaian data

Jika pemindaian berjalan lebih dari 10 menit, atau jika status tugas tetap Tertunda dalam waktu yang lama tanpa beralih ke Berjalan, hal ini mungkin disebabkan oleh tidak tersedianya resource sementara di region. Jika hal ini terjadi, Anda dapat menjalankan perintah berikut untuk menghapus tugas, lalu mencoba membuat dan menjalankannya lagi. Terkadang, proses awal dapat gagal dengan cepat karena error seperti unable to acquire necessary resources.

   gcloud dataplex datascans delete $DATASCAN_ID --location=$REGION

Melihat status tugas

Untuk memeriksa status tugas, lakukan hal berikut:

  1. Di konsol Google Cloud, buka halaman Kurasi metadata.
  2. Di tab Cloud Storage discovery, klik nama pemindaian penemuan.Status tugas
  3. Di halaman Detail pemindaian, Anda dapat melihat status tugas.
  4. Setelah tugas selesai, periksa apakah Published dataset (misalnya, acai_pdfs_discovered_003) yang Anda buat menggunakan perintah curl ada.Dataset yang dipublikasikan setelah pemindaian

Melihat tabel objek

Untuk melihat tabel objek yang dibuat setelah tugas penemuan, lakukan hal berikut:

  1. Di konsol Google Cloud, buka BigQuery.
  2. Klik Set Data, lalu pilih set data yang dipublikasikan dan dibuat di langkah sebelumnya. Misalnya, acai_pdfs_discovered_003.
  3. Untuk melihat tabel objek, klik ID tabel. Misalnya, acai_pdfs.
  4. Tabel objek yang dihasilkan akan terlihat seperti gambar berikut:Tabel objek set data yang dipublikasikan

10. Ekstraksi semantik

Anda akan menyimpulkan dan mengekstrak tabel terstruktur, objek database lain, dan hubungan untuk tabel objek tidak terstruktur yang Anda buat pada langkah sebelumnya. Untuk itu, Anda akan menggunakan fitur Insight Katalog Pengetahuan untuk membuat pernyataan SQL guna mengekstrak data terstruktur dari tabel tidak terstruktur

  1. Di Konsol Google Cloud, buka halaman Knowledge Catalog Search.
  2. Telusuri tabel set data yang ingin Anda lihat insight-nya. Misalnya, acai_pdfs_discovered_003. Melihat tabel di Katalog Pengetahuan
  3. Di hasil penelusuran, klik tabel untuk membuka halaman entri.
  4. Klik tab Insights. Jika tab kosong, berarti insight untuk tabel ini belum dibuat. Pembuatan insight mungkin memerlukan waktu 15 hingga 25 menit.
  5. Setelah Anda melihat insight, klik Ekstrak > Ekstrak dengan SQL.Mengekstrak insight dengan SQL
  6. Di halaman Ekstrak dengan SQL, untuk Tujuan, masukkan set data Anda. Misalnya, acai_pdfs_discovered_003.
  7. Klik Ekstrak. Tindakan ini akan membuka Editor BigQuery dengan Kueri yang dimuat.
  8. Klik Run. Langkah ini menghasilkan serangkaian pernyataan dan mungkin memerlukan waktu beberapa menit untuk menyelesaikan prosesnya.
  9. Setelah kueri selesai, Anda akan melihat hasil berikut:Hasil kueri insight yang diekstrak
  10. Buka BigQuery, lalu klik Set Data (misalnya, acai_pdfs_discovered_003). Serangkaian objek database terstruktur baru dibuat di set data yang Anda pilih pada langkah nomor 6.Hasil database terstruktur

Menghasilkan insight untuk objek di BigQuery

Untuk membuat insight untuk set data BigQuery, Anda harus mengakses set data di BigQuery menggunakan BigQuery Studio.

  1. Di konsol Google Cloud, buka BigQuery Studio.
  2. Di panel Explorer, pilih project, lalu buka set data yang ingin Anda buat insight-nya.
  3. Klik tab Insights.
  4. Jika Anda melihat tombol Enable API, klik tombol tersebut untuk mengaktifkan Gemini for Google Cloud. Tindakan ini akan membuka jendela Aktifkan fitur inti.
    1. Di bagian Core feature APIs, klik Aktifkan untuk Gemini for Google Cloud API dan BigQuery Unified API, lalu klik Berikutnya.
    2. Di bagian Permissions (optional), berikan peran IAM kepada principal jika diperlukan, lalu klik Next.
  5. Untuk membuat insight dan memublikasikannya ke Katalog Pengetahuan, klik Buat dan publikasikan.
  6. Setelah dipublikasikan, Anda dapat melihat insight di tab tersebut.Insight untuk objek di BigQuery

11. Menyiapkan IDE untuk analisis data berbasis agen

Ekstensi Google Cloud Data Agent Kit untuk Visual Studio Code adalah ekstensi IDE untuk ilmuwan data dan engineer data. Dengan alat ini, Anda dapat terhubung ke dan menggunakan resource serta data Google Data Cloud langsung dari IDE. Untuk mengetahui informasi selengkapnya, lihat Ringkasan ekstensi Data Agent Kit untuk VS Code

Ekstensi Data Agent Kit untuk VS Code berguna saat Anda ingin melakukan hal berikut:

  • Buat, uji, tinjau, dan deploy pipeline data yang siap produksi, seperti Spark ETL atau BigQuery ETL, langsung dari VS Code.
  • Jelajahi data, bangun pipeline pelatihan, identifikasi model ML yang optimal, dan deploy ke endpoint produksi menggunakan bantuan AI.
  • Hubungkan ke sumber data tepercaya, buat model data berperforma tinggi, dan publikasikan dasbor interaktif untuk pemangku kepentingan bisnis.

Menginstal ekstensi Data Agent Kit untuk VS Code

  1. Buka VS Code.
  2. Instal Google Cloud CLI. Untuk mengetahui informasi selengkapnya, lihat Menginstal Google Cloud CLI.
  3. Instal ekstensi Data Agent Kit untuk VS Code.
  4. Selesaikan proses aktivasi ekstensi, yang mengharuskan Anda:
    • Login ke ekstensi
    • Menginstal keahlian, server MCP
  5. Muat ulang atau mulai ulang jendela setelah Anda selesai melakukan aktivasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan dan mengonfigurasi ekstensi Data Agent Kit untuk VS Code.
  6. Setelah IDE dimuat ulang, klik ikon Google Data Cloud di panel navigasi, buka setelan, dan pastikan Anda menyetel project ID dan region (us-west1) dengan benar di setelan umum.

Menyiapkan ruang kerja di VS Code

  1. Buka VS Code, lalu pilih File > Open folder > New folder.
  2. Buat folder baru bernama acai_test, lalu klik Open. VS Code kini menganggap folder yang Anda buka sebagai ruang kerja.
  3. Pada dialog Kepercayaan ruang kerja, pilih Ya, saya memercayai penulis untuk mengaktifkan semua fitur di ruang kerja.
  4. Buat folder .github di ruang kerja acai_test.
  5. Buat file baru copilot-instructions.md di folder .github dan masukkan aturan berikut di dalamnya.
    ## 1. Project Context
- **Project ID**: <PROJECT_ID>
- **Domain**: This project is centralized around "Froyo", a brand of frozen yogurt offering multiple flavors.
- **Documentation**: Raw PDF documents detailing flavors and ingredients are stored in Google Cloud Storage at `gs://<BUCKET_NAME>`.

## 2. Execution & Data Processing Rules
- **CRITICAL RULE - Structured Specs**: The semantic and structured information extracted from the PDFs is available in a BigQuery dataset named `<BQ_DATASET_NAME>` (referred to as the Knowledge Catalog).
- **CRITICAL RULE - Customer Data**: Existing Froyo customer data resides in BigQuery in the dataset `<DATASET_ID>`. When you are referencing a dataset, ensure you are using it with the project ID (`<PROJECT_ID>`) and namespace prefix `<NAMESPACE_NAME>`. For example, to query order table in this dataset you should use `<PROJECT_ID>.<NAMESPACE>.<DATASET_ID>.orders`.
- **CRITICAL RULE - Data Joins between BigQuery dataset and Iceberg dataset**: ANY task requiring a join or integration between the BigQuery datasets `<DATASET_ID>` of the PDF data and the `<DATASET_ID>` of the customer data MUST be executed using **Spark Notebooks**.
- **CRITICAL RULE - Notebook Kernel**: Every Spark notebook utilized MUST exclusively be configured to run on the Serverless Session template `iceberg-federation-template` as its kernel.
- **CRITICAL RULE - Data Science**: ANY data science, machine learning, or advanced analytical task MUST be performed strictly within **Spark Notebooks** using the aforementioned setup.
  6. Buat file baru lainnya template.yaml di ruang kerja acai_test dan masukkan informasi berikut dalam file.
    labels:
 client: "vscode"
jupyterSession:
 displayName: "iceberg-federation-template"
 kernel: "PYTHON"
environmentConfig:
 executionConfig:
   serviceAccount: "sa-spark-dev1@<PROJECT_ID>.iam.gserviceaccount.com"
   subnetworkUri: "projects/<PROJECT_ID>/regions/<REGION>/subnetworks/<SUBNET_NAME>"
runtimeConfig:
 version: "2.3"
 properties:
 # This enables the secure proxy URL you were looking for
   dataproc.tier: "premium"
   spark.dataproc.engine: "lightningEngine"
   spark.dataproc.lightningEngine.runtime: "native"
   spark.memory.offHeap.enabled: "true"
   spark.memory.offHeap.size: "1g"
   spark.executor.memory: "4g"
   "dataproc.component.gateway.enabled": "true"
   "dataproc.jupyter.listen.all.interfaces": "true"
   "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"
   "spark.sql.defaultCatalog": "<CATALOG_NAME>"
   "spark.sql.catalog.<CATALOG_NAME>": "org.apache.iceberg.spark.SparkCatalog"
   "spark.sql.catalog.<CATALOG_NAME>.type": "rest"
   "spark.sql.catalog.<CATALOG_NAME>.uri": "<CATALOG_URI_ID>"
   "spark.sql.catalog.<CATALOG_NAME>.warehouse": "bl://projects/<PROJECT_ID>/catalogs/<CATALOG_NAME>"
   "spark.sql.catalog.<CATALOG_NAME>.rest.auth.type": "org.apache.iceberg.gcp.auth.GoogleAuthManager"
  7. Di VS Code, klik Terminal dan jalankan perintah berikut untuk mengimpor file template.yaml sebagai template sesi. Template ini digunakan oleh agen nanti untuk membuat sesi Spark.
    gcloud beta dataproc session-templates import iceberg-federation-template \
    --source=template.yaml \
    --location=<REGION>
    Ganti REGION dengan region Anda.

12. Melakukan analisis data dengan bantuan agen

  1. Di editor VS Code, klik Toggle chat.
  2. Untuk Konfigurasi agen kustom, pilih Agen. Agen yang dipilih di VS Code
  3. Di panel Search models, klik Manage language models. Ikon kelola model di VS Code
  4. Di halaman Language models, klik Add models.
  5. Pilih Google dari daftar, lalu tekan Enter untuk mengonfirmasi input Anda.Menambahkan model Google Gemini di VS Code
  6. Untuk memasukkan kunci API untuk Google Gemini, lakukan hal berikut:
    1. Buka situs Google AI Studio.
    2. Login dengan Akun Google Anda.
    3. Di sidebar, klik Dapatkan kunci API.
    4. Klik Buat kunci API. Halaman Buat kunci baru akan terbuka.
    5. Dari daftar Select a cloud project, pilih Import project.
    6. Masukkan nama project yang ada.
    7. Klik Create key, lalu salin kunci API. Kunci ini memberikan akses ke resource Gemini API akun Anda.Untuk mengetahui informasi selengkapnya, lihat Menggunakan kunci Gemini API.
  7. Tempelkan kunci API yang Anda buat di kotak penelusuran, lalu klik Enter. Kunci Google Gemini API
  8. Jika model Gemini tidak muncul, tampilkan model tersebut seperti yang ditunjukkan pada gambar berikut: Menampilkan model Google Gemini
  9. Pilih Pratinjau Gemini 3.1 Pro dari daftar model Google Gemini, lalu tutup jendela Model bahasa.
  10. Di jendela percakapan, masukkan pertanyaan berikut:
       Search ingredients for Midnight papaya
  11. Setelah beberapa interaksi, Anda akan melihat hasil berikut:Hasil pertanyaan tentang bahan-bahan pepaya tengah malam
  12. Di jendela percakapan, masukkan pertanyaan lain:
       Search allergen information for Midnight papaya
  13. Setelah beberapa interaksi dan langkah, Anda akan melihat agen merespons dengan nama alergen Soy seperti yang dapat Anda lihat pada gambar berikut:Hasil alergen pepaya tengah malam
  14. Di jendela percakapan, masukkan pertanyaan lain:
       Build a pipeline to join products with our 'Global Loyalty' Iceberg tables in acai customer, sales data to identify popular products
  15. Untuk memilih kernel, buka file .ipynb, lalu klik Select kernel > Remote spark kernels > Iceberg-federation-template on serverless sparkPilih kernel di VS Code
  16. Setelah beberapa interaksi dan langkah, Anda akan melihat agen merespons dengan semua langkah di notebook yang berhasil dieksekusi beserta hasil akhir yang dihasilkan di akhir notebook seperti yang dapat Anda lihat pada gambar berikut:Hasil kueri tabel Iceberg

13. Pembersihan

Untuk menghindari biaya, hapus resource yang Anda buat di lab ini.

  1. Untuk menghapus Knowledge Catalog DataScan, jalankan perintah berikut:
      DATASCAN_ID="<DATASCAN_ID>"
  echo "Deleting Dataplex DataScan: ${DATASCAN_ID}"
  gcloud dataplex datascans delete "${DATASCAN_ID}" --location="${REGION}" --quiet
  2. Untuk menghapus bucket Cloud Storage dan semua isinya, jalankan perintah berikut:
      echo "Deleting Cloud Storage buckets: <BUCKET_NAME1> and <BUCKET_NAME2>"
  gsutil -m rm -r gs://<BUCKET_NAME1>
  gsutil -m rm -r gs://<BUCKET_NAME2>
  3. Untuk menghapus Koneksi BigQuery, jalankan perintah berikut:
      CONNECTION_ID="<CONNECTION_NAME>"
  echo "Deleting BigQuery Connection: ${CONNECTION_ID}"
  bq rm --connection "${PROJECT_ID}.${REGION}.${CONNECTION_ID}"
  4. Untuk menghapus Katalog Lakehouse, jalankan perintah berikut:
      CATALOG_ID="<CATALOG_NAME>"
  echo "Deleting Lakehouse Catalog: ${CATALOG_ID}"
  gcloud biglake catalogs delete "${CATALOG_ID}" --project="${PROJECT_ID}" --location="${REGION}" --quiet
  5. Untuk menghapus set data yang berisi tabel PDF yang ditemukan, jalankan perintah berikut:
      DATASET_NAME="<DATASET_NAME>"
  echo "Deleting BigQuery Dataset: ${DATASET_NAME}"
  bq rm -r -f "${PROJECT_ID}:${DATASET_NAME}"
  6. Untuk menghapus Akun Layanan Kustom, jalankan perintah berikut:
      SERVICE_ACCOUNT="<SERVICE_ACCOUNT>"
  echo "Deleting Service Account: ${SERVICE_ACCOUNT}"
  gcloud iam service-accounts delete "${SERVICE_ACCOUNT}"@"${PROJECT_ID}".iam.gserviceaccount.com --quiet
  7. Untuk menghapus Jaringan VPC, jalankan perintah berikut:
      VPC_NETWORK="<VPC_NETWORK>"
  echo "Deleting VPC Network: ${VPC_NETWORK}"
  gcloud compute networks delete "${VPC_NETWORK}" --quiet
  8. Untuk menghapus seluruh project Google Cloud, jalankan perintah berikut:
      gcloud projects delete "${PROJECT_ID}"

14. Selamat

Selamat! Anda telah berhasil mengatur lanskap data file PDF dan Parquet yang terisolasi dalam tabel BigQuery dan menggabungkannya ke dalam satu ekosistem yang dapat ditelusuri dan digabungkan. Pada dasarnya, Anda telah membangun Lakehouse Data modern yang memperlakukan PDF dan format big data secara cerdas seperti halnya memperlakukan baris dalam database. Dan Anda melakukan semua ini langsung dari agen Anda dalam pengalaman percakapan dengan Gemini.

Dokumen referensi

Untuk mempelajari lebih dalam teknologi inti yang digunakan dalam codelab ini, buka dokumentasi resmi Google Cloud: