Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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` 値を作成する

オブジェクトテーブル、OBJ.MAKE_REF 関数、OBJ.LIST 関数、または 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 関数は、直接アクセスと委任アクセスをサポートするために、null 可能なオーソライザーを受け入れます。

`OBJ.LIST` 関数を使用する

自発的な検出には OBJ.LIST 関数を使用します。OBJ.LIST 関数は、Cloud Storage に保存されているファイルのメタデータと ObjectRef 値のテーブルを返します。Cloud Storage のデータには、ドキュメント、画像、音声を含めることができます。

OBJ.LIST を使用すると、永続テーブルで ObjectRef 値を手動で作成する必要がなくなります。Cloud Storage オブジェクトを AI 関数にすばやく追加して、非構造化データを構造化データに変換する自律型 ETL パイプラインを構築できます。バケットに到着する新しいオブジェクトを継続的に追跡する永続的な自己更新テーブルが必要な場合は、代わりに標準の 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 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 Agent Platform model.
SELECT AI.GENERATE(
  ("Describe this image:",
  OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg")));

アクセス権の委任

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

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

1 回限りの設定。データ管理者は、Cloud Storage バケットを管理するために、Cloud リソース接続を設定する必要があります。
1. 新しい BigQuery Cloud リソース接続を作成するか、プロジェクト内の既存の接続を再利用します。
2. 接続のメタデータでサービスアカウントを検索します。
3. プロジェクトまたは Cloud Storage バケットのいずれかで、読み取り用の storage.objects.get 権限または書き込み用の storage.objects.create 権限をサービスアカウントに付与します。これらの権限は、ストレージオブジェクト閲覧者ロールまたは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 の境界内では、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;

ObjectRef 値を操作する

スキーマ

ObjectRef 値を作成する

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

OBJ.MAKE_REF 関数を使用する

OBJ.LIST 関数を使用する