Menggunakan nilai ObjectRef

Dokumen ini menjelaskan nilai ObjectRef dan cara membuat serta menggunakannya di BigQuery.

Nilai ObjectRef adalah jenis STRUCT dengan skema yang telah ditentukan sebelumnya yang mereferensikan objek Cloud Storage untuk analisis multimodal. Nilai ini dapat di proses oleh OBJ fungsi, fungsi AI, atau fungsi yang ditentukan pengguna Python.

Skema

Nilai ObjectRef memiliki kolom berikut:

Nama Jenis Mode Deskripsi Contoh
uri STRING REQUIRED URI objek Cloud Storage. "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE Generasi objek. "1560286006357632"
authorizer STRING NULLABLE ID koneksi BigQuery untuk akses yang didelegasikan atau NULL untuk akses langsung. ID dapat memiliki format berikut:
"region.connection"
atau
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE Metadata objek atau error dari pemrosesan objek. Kolom ini dapat menyertakan kolom content_type, md5_hash, size, dan updated untuk objek. {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

Kolom content_type di kolom gcs_metadata dari kolom details diambil dari Cloud Storage. Anda dapat menetapkan jenis konten objek di Cloud Storage. Jika Anda menghapusnya di Cloud Storage, BigQuery akan menyimpulkan jenis konten dari akhiran URI.

Membuat nilai ObjectRef

Anda dapat membuat ObjectRef nilai menggunakan tabel objek, fungsi OBJ.MAKE_REF, atau set data Insight Penyimpanan Cloud.

Menggunakan tabel objek

Gunakan tabel objek jika Anda tidak memiliki URI yang disimpan dalam tabel dan ingin mencantumkan semua objek dari awalan Cloud Storage. Tabel objek menyimpan referensi ke objek di setiap baris, dan memiliki kolom ref yang berisi nilai ObjectRef. Kueri berikut menggunakan pernyataan CREATE EXTERNAL TABLEuntuk membuat tabel objek:

CREATE EXTERNAL TABLE mydataset.images
WITH CONNECTION `us.myconnection`
OPTIONS (uris=["gs://mybucket/images/*"], object_metadata="SIMPLE");

SELECT ref AS image_ref FROM mydataset.images;

Nilai ObjectRef dari tabel objek harus memiliki pemberi otorisasi untuk akses yang didelegasikan. Koneksi pemberi otorisasi adalah koneksi yang sama dengan yang Anda gunakan untuk membuat tabel objek.

Menggunakan fungsi OBJ.MAKE_REF

Gunakan OBJ.MAKE_REF fungsi jika Anda sudah memiliki URI yang disimpan dalam tabel dan ingin membuat ObjectRef nilai dari URI tersebut. Kueri berikut menunjukkan cara membuat nilai ObjectRef di kolom image_ref dari kolom uri yang berisi URI Cloud Storage:

-- Specify only the URI
SELECT *, OBJ.MAKE_REF(uri) AS image_ref FROM mydataset.images;
-- Specify the URI and the connection
SELECT *, OBJ.MAKE_REF(uri, "us.myconnection") AS image_ref FROM mydataset.images;

Untuk mengubah pemberi otorisasi dari nilai ObjectRef yang ada, Anda dapat menggunakan fungsi OBJ.MAKE_REF:

-- Remove the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>NULL) AS image_ref FROM mydataset.images;
-- Change the authorizer
SELECT *, OBJ.MAKE_REF(ref, authorizer=>"us.myconnection2") AS image_ref FROM mydataset.images;

Fungsi OBJ.MAKE_REF menerima pemberi otorisasi yang dapat di-nullable untuk mendukung akses langsung dan akses yang didelegasikan.

Menggunakan set data Cloud Storage Insights

Jika Anda memiliki set data Insight Penyimpanan yang dikonfigurasi, set data tersebut sudah menyertakan kolom ref yang berisi nilai ObjectRef. Nilai ObjectRef yang dibuat dalam set data Storage Insights tidak memiliki pemberi otorisasi. Untuk membuat kueri objek ini, Anda harus memiliki akses langsung ke objek atau menambahkan pemberi otorisasi ke ObjectRef untuk menggunakan akses yang didelegasikan.

Pemberi otorisasi dan izin

Saat Anda meneruskan nilai ObjectRef ke fungsi ObjectRef, fungsi AI, atau UDF Python, fungsi tersebut perlu mengakses objek yang disimpan di Cloud Storage. Anda dapat mengotorisasi akses ini berdasarkan nilai kolom authorizer dengan dua cara: akses langsung dan akses yang didelegasikan.

Akses langsung

Dengan akses langsung, pengguna yang menjalankan kueri mengakses objek secara langsung menggunakan kredensialnya sendiri. Akses langsung digunakan saat nilai ObjectRef tidak memiliki pemberi otorisasi.

Akses langsung memiliki batasan berikut:

  • Pengguna harus memiliki izin untuk mengakses objek.
  • Tugas kueri yang menggunakan fungsi AI.GENERATE, AI.IF, AI.SCORE, atau AI.CLASSIFY tanpa koneksi mengharuskan pengguna memiliki izin tambahan. Kueri hanya dapat mengakses bucket dan objek Cloud Storage dari project yang sama dengan tempat tugas dijalankan.

Misalnya, jika Anda memanggil fungsi AI.GENERATE pada nilai ObjectRef yang tidak memiliki pemberi otorisasi, fungsi tersebut akan membaca objek sebagai Anda. Jika Anda tidak memiliki izin untuk membaca objek, fungsi tersebut akan menulis error "permission denied" ke kolom status dalam hasil.

Contoh berikut menunjukkan kueri yang menggunakan akses langsung:

-- Requires that the end user can read the object "gs://cloud-samples-data/vision/demo-img.jpg" and use the Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

Akses yang didelegasikan

Dengan akses yang didelegasikan, pengguna yang menjalankan kueri mendelegasikan akses objek ke koneksi resource Cloud BigQuery, yang ditentukan dalam kolom authorizer dari nilai ObjectRef. Akses yang didelegasikan dapat mengaktifkan akses data lintas project.

Untuk menggunakan akses yang didelegasikan, administrator data Anda harus mengikuti langkah-langkah berikut untuk menyiapkan koneksi dan izin:

Misalnya, jika pengguna meneruskan nilai ObjectRef yang memiliki pemberi otorisasi ke fungsi AI.GENERATE, fungsi tersebut akan memverifikasi bahwa pengguna memiliki izin bigquery.objectRefs.read, lalu membaca objek menggunakan akun layanan koneksi. Jika pengguna atau akun layanan memiliki izin yang tidak memadai, fungsi tersebut akan menulis error "permission denied" ke kolom status dalam hasil.

Contoh berikut menunjukkan kueri yang menggunakan akses yang didelegasikan. Kueri ini memerlukan hal berikut:

  • Pengguna memiliki izin bigquery.objectRefs.read di connection1.
  • Akun layanan untuk connection1 memiliki izin storage.objects.get pada objek.
  • Akun layanan untuk connection2 memiliki peran Pengguna Agent Platform.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1")),
  endpoint => 'gemini-2.5-pro',
  connection_id => "us.connection2");

Di dalam perimeter Kontrol Layanan VPC, fungsi AI tidak dapat memproses nilai ObjectRef yang menggunakan akses yang didelegasikan. Akses yang didelegasikan menghasilkan URL HTTPS yang ditandatangani untuk objek, dan Gemini Enterprise Agent Platform memblokir pengambilan HTTP dan HTTPS untuk project di dalam perimeter. Fungsi ini menulis error berikut ke kolom status dalam hasil:

INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC.

Karena kolom ref tabel objek selalu menggunakan koneksi tabel objek sebagai pemberi otorisasi, meneruskan ref ke fungsi AI di dalam perimeter akan selalu menampilkan error ini. Untuk menganalisis objek, teruskan nilai argumen tunggal OBJ.MAKE_REF(uri), yang menggunakan akses langsung dan mengirimkan Cloud Storage URI ke model tanpa membuat URL bertanda tangan.

Praktik terbaik

Pertimbangkan praktik terbaik berikut saat Anda memutuskan apakah akan menggunakan akses langsung atau yang didelegasikan:

  • Gunakan akses langsung untuk tim kecil yang beroperasi dalam satu project untuk penyimpanan dan analisis data. Administrator data menggunakan Identity and Access Management untuk memberikan akses kepada pengguna ke data BigQuery dan data Cloud Storage. Pengguna dapat membuat nilai ObjectRef sesuai permintaan tanpa pemberi otorisasi untuk menganalisis objek menggunakan kredensialnya sendiri.
  • Gunakan akses yang didelegasikan untuk tim besar yang beroperasi di beberapa project, terutama saat penyimpanan dan analisis data dipisahkan. Administrator data dapat menyiapkan koneksi dan membuat nilai ObjectRef untuk analisis terlebih dahulu dengan koneksi sebagai pemberi otorisasinya. Pendekatan ini berfungsi dengan tabel objek atau menggunakan OBJ.MAKE_REF pada daftar URI. Kemudian, administrator data dapat membagikan tabel yang menyimpan nilai ObjectRef kepada analis. Analis tidak perlu mengakses bucket asli untuk menganalisis objek.

Error

Fungsi yang menggunakan nilai ObjectRef melaporkan error dengan dua cara:

  • Kegagalan kueri: kueri mungkin gagal dengan pesan error dan tanpa hasil.
  • Nilai error yang ditampilkan: kueri berhasil, tetapi fungsi mungkin menulis error sebagai bagian dari nilai yang ditampilkan. Untuk mengetahui informasi tentang format nilai yang ditampilkan, lihat halaman referensi untuk fungsi yang Anda gunakan.

Saat fungsi menampilkan nilai ObjectRef, kolom details dari nilai tersebut mungkin berisi kolom errors. Jika ada, nilai kolom tersebut adalah array error. Setiap error memiliki skema berikut:

Nama Jenis Mode Deskripsi Contoh
code INT64 REQUIRED Kode error HTTP standar. 400
message STRING REQUIRED Pesan error deskriptif yang mudah dipahami pengguna. "Connection credential for myproject.us.nonexistent_connection cannot be used. Either the connection does not exist, or the user does not have sufficient permissions (bigquery.objectRefs.read)"
source STRING REQUIRED Nama fungsi yang memicu error. "OBJ.MAKE_REF"

Berikut adalah dua jenis error umum:

  • Error objek: URI atau versi objek yang diberikan tidak ada.
  • Error pemberi otorisasi: koneksi tidak ada atau pengguna tidak memiliki izin untuk menggunakannya untuk akses yang didelegasikan.

Kueri berikut menunjukkan cara memilih ObjectRef nilai yang berisi error dari kolom Objectref:

SELECT ref
FROM mydataset.images
WHERE ref.details.errors IS NOT NULL;

Langkah berikutnya