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 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. Objek ini dapat mencakup 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, atau set data Cloud Storage Insights.

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 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 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 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 set data Cloud Storage Insights

Jika Anda telah mengonfigurasi set data Storage Insights, set data tersebut sudah menyertakan kolom ref yang berisi nilai ObjectRef. Nilai ObjectRef yang dibuat di set data Insight Penyimpanan 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 mengizinkan 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 Vertex AI model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.GET_ACCESS_URL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg"), 'r')));

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 Vertex AI User.
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.GET_ACCESS_RUL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1"), 'r')),
  connection_id => "us.connection2");

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 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 ya, 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 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