Menggunakan nilai ObjectRef

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

Nilai ObjectRef adalah jenis STRUCT dengan skema yang telah ditetapkan 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 akhiran URI.

Buat nilai ObjectRef

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

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 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 memiliki URI yang disimpan 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 Cloud Storage URI:

-- 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 pemberi otorisasi nullable 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 fungsi AI untuk membangun pipeline ETL spontan yang menangani konversi data tidak terstruktur menjadi data terstruktur. Jika Anda memerlukan tabel persisten yang dapat diupdate sendiri dan terus melacak objek baru yang masuk ke bucket dari waktu ke waktu, sebaiknya buat 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 Insight Cloud Storage

Jika Anda telah mengonfigurasi set data Insight Penyimpanan, set data tersebut sudah menyertakan kolom ref yang berisi nilai ObjectRef. Setiap nilai ObjectRef yang dibuat di set data Insight Penyimpanan tidak memiliki pemberi otorisasi. Untuk mengkueri 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 menggunakan kredensial mereka 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 Cloud Storage dan objek 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 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:

• Penyiapan satu kali. Administrator data harus menyiapkan koneksi resource Cloud untuk mengelola bucket Cloud Storage:
  1. Buat koneksi resource Cloud BigQuery baru atau gunakan kembali koneksi yang ada dalam project.
  2. Cari akun layanan di metadata koneksi.
  3. Beri akun layanan izin storage.objects.get untuk pembacaan, atau izin storage.objects.create untuk penulisan, di project atau bucket Cloud Storage. Anda dapat memberikan izin ini dengan peran Storage Object Viewer atau Storage Object User.
• Penyiapan per pengguna. Administrator data harus memberi pengguna izin bigquery.objectRefs.read untuk pembacaan, atau izin bigquery.objectRefs.write untuk penulisan, ke koneksi BigQuery. Anda dapat memberikan izin ini dengan peran BigQuery ObjectRef Reader atau BigQuery ObjectRef Admin.

Perhatian: Izin bigquery.objectRefs.read dan bigquery.objectRefs.write berlaku untuk koneksi, bukan untuk tabel atau baris individual. Karena izin ini dirancang untuk memberikan akses tingkat koneksi ke objek Cloud Storage apa pun yang dapat diakses oleh akun layanan koneksi (misalnya, melalui OBJ.MAKE_REF, OBJ.LIST, dan OBJ.GET_ACCESS_URL), jangan gunakan izin ini dengan kebijakan akses tingkat baris. Untuk membuat URL bertanda tangan untuk tabel objek dengan kebijakan akses tingkat baris, buat kueri tabel objek dengan fungsi EXTERNAL_OBJECT_TRANSFORM, bukan menggunakan bigquery.objectRefs.read pada koneksi.

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 tidak memiliki izin yang memadai, fungsi akan menulis error "permission denied" ke kolom status dalam hasil.

Contoh berikut menunjukkan kueri yang menggunakan akses yang didelegasikan. Hal 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 Agent Platform User.

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 menghasilkan URL HTTPS bertanda tangan untuk objek, dan URL bertanda tangan tidak dapat melintasi batas perimeter. Fungsi ini menulis salah satu error berikut ke kolom status dalam hasil:

• INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. Error ini terjadi jika perimeter Anda membatasi Agent Platform.
• Cannot fetch content from the provided URL Error ini terjadi jika perimeter Anda membatasi Cloud Storage.

Karena kolom ref dari 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 URI Cloud Storage 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 memberi pengguna akses 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. Karena akses yang didelegasikan memberikan akses ke semua objek yang dapat dijangkau oleh akun layanan koneksi, terlepas dari kebijakan akses tingkat baris pada tabel objek atau tabel standar, cakup izin Cloud Storage setiap koneksi hanya ke bucket atau folder terkelola yang penggunanya diizinkan untuk mengakses.

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 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 adalah 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 untuk 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

• Menentukan kolom ObjectRef dalam skema tabel.
• Menganalisis data multimodal.
• Pelajari lebih lanjut fungsi ObjectRef.