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 データセットが構成されている場合、データセットには ObjectRef 値を含む ref 列がすでに含まれています。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 Vertex AI model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")),
  endpoint => 'gemini-2.5-pro');

アクセス権の委任

委任アクセスを使用すると、クエリを実行するユーザーは、ObjectRef 値の authorizer フィールドで指定された BigQuery Cloud リソース接続にオブジェクト アクセスを委任します。委任アクセスにより、プロジェクト間のデータアクセスが可能になります。

委任アクセスを使用するには、データ管理者が次の手順で接続と権限を設定する必要があります。

たとえば、ユーザーが認可関数を持つ ObjectRef 値を AI.GENERATE 関数に渡すと、関数はユーザーに bigquery.objectRefs.read 権限があることを確認し、接続のサービス アカウントを使用してオブジェクトを読み取ります。ユーザーまたはサービス アカウントに十分な権限がない場合、関数は結果の status 列に "permission denied" エラーを書き込みます。

次の例は、委任されたアクセスを使用するクエリを示しています。そのためには、次のものが必要です。

  • ユーザーは connection1 に対する bigquery.objectRefs.read 権限を持っています。
  • connection1 のサービス アカウントに、オブジェクトに対する storage.objects.get 権限が付与されている。
  • connection2 のサービス アカウントには、Agent Platform User ロールが付与されています。
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");

ベスト プラクティス

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

  • データ ストレージと分析の両方で単一のプロジェクトで運用する小規模なチームには、直接アクセスを使用します。データ管理者は、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;

次のステップ