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 関数、OBJ.LIST 関数、または 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 許容の認可者を受け入れます。

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")));

アクセス権の委任

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

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

たとえば、ユーザーが認可者を持つ 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 が生成されます。署名付き URL は境界を越えることができません。この関数は、結果の status 列に次のいずれかのエラーを書き込みます。

  • INVALID_ARGUMENT: HTTP links are not supported for requests restricted by VPCSC. このエラーは、境界が Agent Platform を制限している場合に発生します。
  • Cannot fetch content from the provided URL このエラーは、境界で Cloud Storage が制限されている場合に発生します。

オブジェクト テーブルの 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 値を格納するテーブルをアナリストと共有できます。アナリストは、オブジェクトを分析するために元のバケットにアクセスする必要はありません。委任アクセスでは、オブジェクト テーブルまたは標準テーブルの行レベルのアクセス ポリシーに関係なく、接続のサービス アカウントがアクセスできるすべてのオブジェクトへのアクセス権が付与されます。そのため、各接続の Cloud Storage 権限のスコープは、ユーザーがアクセスを許可されているバケットまたはマネージド フォルダのみに設定してください。

エラー

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;

次のステップ