Bekerja dengan nilai ObjectRef

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

Nilai ObjectRef adalah jenis STRUCT dengan skema standar yang mereferensikan objek Cloud Storage untuk analisis multimodal. Data ini dapat diproses oleh fungsi OBJ, 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 Pembuatan 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. Objek 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 menghilangkannya di Cloud Storage, BigQuery akan menyimpulkan jenis konten dari sufiks URI.

Buat nilai ObjectRef

Anda dapat membuat nilai ObjectRef menggunakan tabel objek, fungsi OBJ.MAKE_REF, fungsi OBJ.LIST, atau dataset Cloud Storage Insights.

Menggunakan tabel objek

Gunakan tabel objek jika Anda tidak memiliki URI yang disimpan dalam tabel dan ingin mempertahankan daftar 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 TABLE untuk 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 pengotorisasi 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 fungsi OBJ.MAKE_REF jika Anda sudah menyimpan URI dalam tabel dan ingin membuat nilai ObjectRef 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 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 pengotor yang dapat bernilai null untuk mendukung akses langsung dan akses yang didelegasikan.

Menggunakan fungsi OBJ.LIST

Gunakan fungsi OBJ.LIST untuk penemuan spontan. Fungsi OBJ.LIST menampilkan tabel metadata dan nilai ObjectRef untuk file yang disimpan di Cloud Storage. Data Cloud Storage dapat mencakup dokumen, gambar, dan audio.

Penggunaan OBJ.LIST menggantikan kebutuhan untuk membuat nilai ObjectRef secara manual dalam tabel persisten. Anda dapat dengan cepat menambahkan objek Cloud Storage ke dalam fungsi AI untuk membangun pipeline ETL spontan yang menangani konversi data tidak terstruktur menjadi data terstruktur. Jika Anda memerlukan tabel yang persisten dan diperbarui sendiri yang terus melacak objek baru yang tiba di bucket dari waktu ke waktu, Anda harus membuat tabel objek BigQuery standar.

Kueri berikut menggunakan karakter pengganti (*) untuk menemukan jenis file tertentu, dan menggunakan fungsi AI.IF untuk memfilter data tidak terstruktur. Kueri ini hanya mencantumkan file PNG yang berisi gambar.

SELECT
  uri,
  content_type,
  size
FROM
  OBJ.LIST('gs://mybucket/images/*.png')
WHERE
  AI.IF(('Does this image contain a dog?', ref))
ORDER BY
  uri;

Menggunakan set data Cloud Storage Insights

Jika Anda telah mengonfigurasi set data Insight Penyimpanan, set data tersebut sudah menyertakan kolom ref yang berisi nilai ObjectRef. Nilai ObjectRef yang dibuat di 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 memberikan otorisasi 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 dengan 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.
  • Pekerjaan 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 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 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")));

Akses yang didelegasikan

Dengan akses yang didelegasikan, pengguna yang menjalankan kueri mendelegasikan akses objek ke koneksi resource Cloud BigQuery, yang ditentukan di kolom authorizer 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 akan menulis error "permission denied" ke kolom status dalam hasil.

Contoh berikut menunjukkan kueri yang menggunakan akses yang didelegasikan. Hal ini memerlukan 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")),
  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 membuat URL HTTPS bertanda tangan 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 dari tabel objek selalu menggunakan koneksi tabel objek sebagai pemberi otorisasi, meneruskan ref ke fungsi AI di dalam perimeter selalu menampilkan error ini. Untuk menganalisis objek, teruskan nilai OBJ.MAKE_REF(uri) argumen tunggal, 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 pengguna ke data BigQuery dan data Cloud Storage. Pengguna dapat membuat nilai ObjectRef sesuai permintaan tanpa pemberi otorisasi untuk menganalisis objek menggunakan kredensial mereka 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 otorisasi. Pendekatan ini berfungsi dengan tabel objek atau dengan 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 tidak ada 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.

Jika 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 yang deskriptif dan 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 dua jenis error yang umum:

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

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

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

Langkah berikutnya