ObjectRef 値を操作する

このドキュメントでは、ObjectRef 値と、BigQuery での作成方法と使用方法について説明します。

ObjectRef 値は、マルチモーダル分析用の Cloud Storage オブジェクトを参照する、事前定義されたスキーマを持つ STRUCT 型 です 。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}}

details 列の gcs_metadata フィールドの content_type フィールドは、Cloud Storage から取得されます。Cloud Storage でオブジェクトの コンテンツ タイプを設定できます。Cloud Storage で省略すると、BigQuery は URI の接尾辞からコンテンツ タイプを推測します。

ObjectRef 値を作成する

ObjectRef 値は、 オブジェクト テーブル、 OBJ.MAKE_REF 関数、 または Cloud Storage Insights データセットを使用して作成できます。

オブジェクト テーブルを使用する

テーブルに 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 関数は、 直接アクセスと委任アクセスをサポートするために、null 許容の承認者を受け入れます。

Cloud Storage Insights データセットを使用する

Storage Insights データセットが構成されている場合、 データセットにはすでに ref 列が含まれており、 ObjectRef 値が含まれています。Storage Insights データセットで作成された ObjectRef 値には承認者がありません。これらのオブジェクトに対してクエリを実行するには、 オブジェクトへの直接アクセス権があるか、委任アクセスを使用するために ObjectRefに承認者を追加する必要があります。

承認者と権限

ObjectRef 値を ObjectRef 関数、AI 関数、または Python UDF に渡すと、これらの関数は Cloud Storage に保存されているオブジェクトにアクセスする必要があります。このアクセスは、authorizer フィールドの値に基づいて、直接アクセスと委任アクセスの 2 つの方法で承認できます。

ダイレクト アクセス

直接アクセスでは、クエリを実行するユーザーは、自分の認証情報を使用してオブジェクトに直接アクセスします 。直接アクセスは、ObjectRef 値に承認者がいない場合に使用されます。

直接アクセスには次の制限があります。

  • ユーザーにはオブジェクトにアクセスする権限が必要です。
  • 接続のない AI.GENERATE、 AI.IF、 AI.SCORE、または AI.CLASSIFY 関数を使用するクエリジョブでは、ユーザーに 追加の権限が必要です。 クエリは、ジョブが実行されるプロジェクトと同じプロジェクトの Cloud Storage バケットとオブジェクトにのみアクセスできます。

たとえば、承認者のない 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")),
  endpoint => 'gemini-2.5-pro');

アクセス権の委任

アクセス権の委任 __では、クエリを実行するユーザーは、オブジェクト アクセスを BigQuery Cloud リソース接続に委任します。 これは、authorizer 値の 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")),
  endpoint => 'gemini-2.5-pro',
  connection_id => "us.connection2");

VPC Service Controls の境界内では、AI 関数 は委任アクセスを使用する ObjectRef 値を処理できません。委任アクセスはオブジェクトの署名付き HTTPS URL を生成し、Gemini Enterprise Agent Platform は境界内のプロジェクトの HTTP フェッチと HTTPS フェッチをブロックします。関数は、結果の status 列に次のエラーを書き込みます。

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

オブジェクト テーブルの ref 列は常にオブジェクト テーブルの接続を承認者として使用するため、境界内の AI 関数に ref を渡すと、常にこのエラーが返されます。オブジェクトを分析するには、代わりに 単一引数の OBJ.MAKE_REF(uri) 値を渡します。この値は 直接アクセスを使用し、署名付き URL を生成せずに Cloud Storage URI を モデルに送信します。

ベスト プラクティス

直接アクセスと委任アクセスのどちらを使用するかを決定する際は、次のベスト プラクティスを考慮してください。

  • データの保存と分析の両方に単一のプロジェクトで運用する小規模なチームには、直接アクセス を使用します。データ管理者は、Identity and Access Management を使用して、BigQuery データと Cloud Storage データへのアクセス権をユーザーに付与します。ユーザーは、独自の認証情報を使用してオブジェクトを分析するために、承認者なしで ObjectRef 値をオンデマンドで作成できます。
  • 複数のプロジェクトにまたがって運用する大規模なチームには、特にデータの保存と分析が分離されている場合は、委任アクセス を使用します。データ管理者は、接続を承認者として使用して、接続を設定し、分析用の ObjectRef 値を事前に作成できます。この方法は、オブジェクト テーブルを使用するか、URI のリストで OBJ.MAKE_REF を使用して行います。 その後、データ管理者は ObjectRef 値を保存するテーブルをアナリストと共有できます。アナリストは、オブジェクトを分析するために元のバケットにアクセスする必要はありません。

エラー

ObjectRef 値を使用する関数は、次の 2 つの方法でエラーを報告します。

  • クエリの失敗: クエリがエラー メッセージで失敗し、結果が返されないことがあります。
  • 返されたエラー値: クエリは成功しますが、関数が戻り値の一部としてエラーを書き込むことがあります。戻り値の形式については、使用している関数のリファレンス ページをご覧ください。

関数が 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"

一般的なエラーには次の 2 種類があります。

  • オブジェクト エラー: 指定されたオブジェクト URI またはバージョンが存在しません。
  • 承認者エラー: 接続が存在しないか、ユーザーに委任アクセスに使用する 権限がありません。

次のクエリは、エラーを含む ObjectRef 値を Objectref 列から選択する方法を示しています:

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

次のステップ