使用 ObjectRef 值

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

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

結構定義

ObjectRef 值具有下列欄位：

名稱 類型 模式 說明 範例
uri STRING REQUIRED Cloud Storage 物件的 URI。 "gs://cloud-samples-data/vision/demo-img.jpg"
version STRING NULLABLE 物件產生。 "1560286006357632"
authorizer STRING NULLABLE 委派存取權的 BigQuery 連線 ID，或NULL直接存取權。 ID 的格式如下：
"region.connection"
或
"project.region.connection"		 "myproject.us.myconnection"
details JSON NULLABLE 物件中繼資料或處理物件時發生的錯誤。這可能包括物件的 content_type、md5_hash、size 和 updated 欄位。 {"gcs_metadata":{"content_type":"image/png","md5_hash":"dfbbb5cf034af026d89f2dc16930be15","size":915052,"updated":1560286006000000}}

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

建立 ObjectRef 值

您可以使用物件表格、OBJ.MAKE_REF 函式或 Cloud Storage Insights 資料集建立 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 函式接受可為空值的授權者，以支援直接存取和委派存取。

使用 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 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')));

委派存取權

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

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

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

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

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

最佳做法

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

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

錯誤

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

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

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

名稱 類型 模式 說明 範例
code INT64 REQUIRED 標準 HTTP 錯誤代碼。 400
message STRING REQUIRED 清楚易懂的錯誤訊息。 "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 觸發錯誤的函式名稱。 "OBJ.MAKE_REF"

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

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

下列查詢說明如何從 Objectref 資料欄選取含有錯誤的 ObjectRef 值：

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

後續步驟