使用 ObjectRef 值

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

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

結構定義

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

details 欄中 gcs_metadata 欄位的 content_type 欄位是從 Cloud Storage 擷取。您可以在 Cloud Storage 中設定物件的內容類型。如果您在 Cloud Storage 中省略這個值，BigQuery 會根據 URI 的後置字串推論內容類型。

建立 ObjectRef 值

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

使用物件資料表

如果資料表未儲存 URI，且您想保留 Cloud Storage 前置字元的所有物件清單，請使用物件資料表。物件資料表會在每個資料列中儲存物件的參照，並包含 ref 資料欄，其中含有 ObjectRef 值。下列查詢會使用 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 儲存空間分析資料集

如果您已設定儲存空間分析資料集，該資料集就會包含 ref 資料欄，其中含有 ObjectRef 值。在 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 Cloud 資源連結，該連結是在 ObjectRef 值的 authorizer 欄位中指定。委派存取權可啟用跨專案資料存取權。

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

舉例來說，如果使用者將具有授權者的 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 範圍內，AI 函式無法處理使用委派存取權的 ObjectRef 值。委派存取權會為物件產生已簽署的 HTTPS 網址，而這類網址無法跨越 perimeter 邊界。函式會將下列其中一項錯誤寫入結果的 status 欄：

  • INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. 如果 perimeter 限制 Agent Platform，就會發生這項錯誤。
  • Cannot fetch content from the provided URL 如果 perimeter 限制 Cloud Storage，就會發生這項錯誤。

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

最佳做法

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

  • 如果小型團隊在單一專案中同時進行資料儲存庫和分析，請使用直接存取。資料管理員會使用 Identity and Access Management，授予使用者 BigQuery 資料和 Cloud Storage 資料的存取權。使用者可以視需要建立 ObjectRef 值，不需授權者即可使用自己的憑證分析物件。
  • 如果大型團隊跨多項專案運作，尤其是資料儲存庫和分析作業分開時，請使用委派存取權。資料管理員可以設定連線，並以連線做為授權方，預先建立 ObjectRef 值以供分析。這種方法適用於物件資料表，或在 URI 清單中使用 OBJ.MAKE_REF。接著，資料管理員可以與分析師共用儲存 ObjectRef 值的資料表。分析師不需存取原始 bucket 即可分析物件。委派存取權會授予連線服務帳戶可存取的所有物件，無論物件資料表或標準資料表是否設有資料列層級存取權政策，因此請將各連線的 Cloud Storage 權限範圍，限定為使用者有權存取的 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;

後續步驟