使用 ObjectRef 值

本文說明 ObjectRef 值，以及如何在 BigQuery 中建立及使用這些值。

ObjectRef 值是 STRUCT 型別，具有預先定義的結構定義，可參照 Cloud Storage 物件進行多模態分析。可由 OBJ 函式、AI 函式或 Python 使用者定義函式處理。

結構定義

ObjectRef 值包含下列欄位：

系統會從 Cloud Storage 擷取 details 資料欄的 gcs_metadata 欄位中的 content_type 欄位。您可以在 Cloud Storage 中設定物件的內容類型。如果您在 Cloud Storage 中省略這項資訊，BigQuery 會根據 URI 的後置字元推斷內容類型。

建立 ObjectRef 值

您可以使用物件表格、OBJ.MAKE_REF 函式、OBJ.LIST 函式或 Cloud Storage 儲存空間分析資料集建立 ObjectRef 值。

使用物件資料表

如果沒有儲存在表格中的 URI，且想保存 Cloud Storage 前置字元中的所有物件清單，請使用物件表格。物件資料表會在每個資料列中儲存物件的參照，並包含含有 ObjectRef 值的 ref 資料欄。下列查詢使用 CREATE EXTERNAL TABLE 陳述式建立物件資料表：

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;

物件表格中的 ObjectRef 值必須具備委派存取權的授權者。授權者連線與您用來建立物件資料表的連線相同。

使用 OBJ.MAKE_REF 函式

如果表格中已儲存 URI，且您想從這些 URI 建立 ObjectRef 值，請使用 OBJ.MAKE_REF 函式。下列查詢顯示如何從包含 Cloud Storage URI 的 uri 欄，在 image_ref 欄中建立 ObjectRef 值：

-- 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;

如要修改現有 ObjectRef 值的授權方，可以使用 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;

OBJ.MAKE_REF 函式接受可為空值的授權者，以支援直接存取和委派存取。

使用 OBJ.LIST 函式

使用 OBJ.LIST 函式進行自發探索。OBJ.LIST 函式會傳回儲存在 Cloud Storage 中的檔案中繼資料和 ObjectRef 值表格。Cloud Storage 資料可能包含文件、圖片和音訊。

使用 OBJ.LIST 就不必在永久資料表中手動建構 ObjectRef 值。您可以快速將 Cloud Storage 物件新增至 AI 函式，建構可處理非結構化資料轉換為結構化資料的自發性 ETL 管道。如果您需要持續追蹤一段時間內抵達 bucket 的新物件，請改為建立標準 BigQuery 物件資料表。

下列查詢會使用萬用字元 (*) 探索特定檔案類型，並使用 AI.IF 函式篩選非結構化資料。這項查詢只會列出含有狗圖片的 PNG 檔案。

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;

使用 Cloud Storage 儲存空間分析資料集

如果您已設定儲存空間分析資料集，則該資料集已包含含有 ObjectRef 值的 ref 欄。在 Storage Insights 資料集中建立的任何 ObjectRef 值都沒有授權人。如要查詢這些物件，您必須直接存取物件，或在 ObjectRef 中新增授權者，以使用委派存取權。

授權者和權限

將 ObjectRef 值傳遞至 ObjectRef 函式、AI 函式或 Python UDF 時，這些函式需要存取 Cloud Storage 中儲存的物件。您可以根據 authorizer 欄位的值，透過直接存取和委派存取兩種方式授權存取權。

直接存取

如果採用直接存取，執行查詢的使用者會使用自己的憑證直接存取物件。如果 ObjectRef 值沒有授權者，系統會使用直接存取權。

直接存取有下列限制：

• 使用者必須擁有存取物件的權限。
• 使用 AI.GENERATE、AI.IF、AI.SCORE 或 AI.CLASSIFY 函式 (不含連線) 的查詢作業，需要使用者具備額外權限。查詢只能存取執行工作所在專案的 Cloud Storage bucket 和物件。

舉例來說，如果您在沒有授權者的 ObjectRef 值上呼叫 AI.GENERATE 函式，該函式就會以您的身分讀取物件。如果沒有讀取物件的權限，函式會在結果的 status 欄中寫入 "permission denied" 錯誤。

以下範例顯示使用直接存取的查詢：

-- 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")));

委派存取權

透過委派存取權，執行查詢的使用者會將物件存取權委派給 BigQuery 雲端資源連線，該連線是在 ObjectRef 值的 authorizer 欄位中指定。委派存取權可啟用跨專案資料存取權。

如要使用委派存取權，資料管理員必須按照下列步驟設定連線和權限：

• 一次性設定。資料管理員必須設定 Cloud 資源連結，才能管理 Cloud Storage bucket：
  1. 建立新的 BigQuery Cloud 資源連結，或重複使用專案中的現有連結。
  2. 在連線的中繼資料中查詢服務帳戶。
  3. 在專案或 Cloud Storage bucket 中，授予服務帳戶讀取權限 storage.objects.get 或寫入權限 storage.objects.create。您可以透過「Storage 物件檢視者」或「Storage 物件使用者」角色授予這些權限。
• 為每位使用者設定。資料管理員必須授予使用者 BigQuery 連線的讀取權限 bigquery.objectRefs.read 或寫入權限 bigquery.objectRefs.write。您可以透過「BigQuery ObjectRef 讀取者」或「BigQuery ObjectRef 管理員」角色授予這些權限。

舉例來說，如果使用者將具有授權者的 ObjectRef 值傳遞至 AI.GENERATE 函式，該函式會驗證使用者是否具有 bigquery.objectRefs.read 權限，然後使用連線的服務帳戶讀取物件。如果使用者或服務帳戶的權限不足，函式會在結果的 status 欄中寫入 "permission denied" 錯誤。

以下範例顯示使用委派存取的查詢。需要下列條件：

• 使用者在 connection1 上擁有 bigquery.objectRefs.read 權限。
• connection1 的服務帳戶具備物件的 storage.objects.get 權限。
• connection2 的服務帳戶具有 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");

在 VPC Service Controls perimeter 內，AI 函式無法處理使用委派存取的 ObjectRef 值。委派存取權會為物件產生已簽署的 HTTPS 網址，且 Gemini Enterprise Agent Platform 會封鎖周邊內專案的 HTTP 和 HTTPS 擷取作業。函式會在結果的 status 欄中寫入下列錯誤：

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

由於物件表格的 ref 欄一律會使用物件表格的連線做為授權者，因此在安全範圍內將 ref 傳遞至 AI 函式時，一律會傳回這項錯誤。如要分析物件，請改為傳遞單一引數 OBJ.MAKE_REF(uri) 值，這會使用直接存取，並將 Cloud Storage URI 傳送至模型，而不產生經簽署的網址。

最佳做法

決定是否要使用直接或委派存取權時，請考慮下列最佳做法：

• 如果小型團隊在單一專案中運作，且需要儲存及分析資料，請使用直接存取。資料管理員會使用 Identity and Access Management，授予使用者 BigQuery 資料和 Cloud Storage 資料的存取權。使用者可以視需要建立 ObjectRef 值，無須授權者即可使用自有憑證分析物件。
• 如果團隊規模龐大，且需要跨多個專案運作，請使用委派存取權，尤其是在資料儲存和分析作業彼此獨立的情況下。資料管理員可以設定連線，並以連線做為授權者，預先建立用於分析的ObjectRef值。這個方法適用於物件資料表，或在 URI 清單上使用 OBJ.MAKE_REF。接著，資料管理員可以與分析師共用儲存 ObjectRef 值的資料表。分析師不必存取原始 bucket 即可分析物件。

錯誤

使用 ObjectRef 值的函式會透過兩種方式回報錯誤：

• 查詢失敗：查詢可能會失敗並顯示錯誤訊息，且不會傳回結果。
• 傳回的錯誤值：查詢成功，但函式可能會將錯誤寫入傳回值。如要瞭解回傳值的格式，請參閱所用函式的參考頁面。

如果函式傳回 ObjectRef 值，該值的 details 欄位可能包含 errors 欄位。如果有的話，該欄位的值就是錯誤陣列。每個錯誤都有下列結構定義：

以下是兩種常見的錯誤類型：

• 物件錯誤：提供的物件 URI 或版本不存在。
• 授權者錯誤：連線不存在，或使用者沒有權限將連線用於委派存取權。

下列查詢顯示如何從 Objectref 欄選取含有錯誤的 ObjectRef 值：

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

後續步驟

• 在資料表結構定義中指定 ObjectRef 資料欄。
• 分析多模態資料。
• 進一步瞭解 ObjectRef 函式。