ObjectRef 値を操作する

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

ObjectRef 値は、マルチモーダル分析のために Cloud Storage オブジェクトを参照する、事前定義されたスキーマを持つ STRUCT 型 です 。 関数、 AI 関数、または Python ユーザー定義関数でOBJ処理できます。

スキーマ

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 列が含まれています。ObjectRefStorage 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.GET_ACCESS_URL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg"), 'r')));

アクセス権の委任

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

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

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

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

  • ユーザーに connection1 に対する bigquery.objectRefs.read 権限がある。
  • connection1 のサービス アカウントに、オブジェクトに対する storage.objects.get 権限がある。
  • connection2 のサービス アカウントに Vertex AI ユーザーロールがある。
SELECT AI.GENERATE(
  ("Describe this image:",
    OBJ.GET_ACCESS_RUL(OBJ.MAKE_REF("gs://cloud-samples-data/vision/demo-img.jpg", "us.connection1"), 'r')),
  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 種類があります。

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

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

次のステップ