非構造化データに検出スキャンを使用する

非構造化データのデータ プロファイル スキャンでは、Cloud Storage 検出スキャン中に Vertex AI Gemini 2.5 Pro モデルを使用して、Cloud Storage 内の未加工の非構造化ファイル（PDF など）を BigQuery 内の構造化されたクエリ可能なアセットに変換します。この自動化されたワークフローは、Cloud Storage 内の未加工のファイルから始めるユーザー向けに設計されています。既存の BigQuery オブジェクト テーブルがすでに存在する場合や、カスタマイズされたプロンプトを使用して抽出をガイドする場合は、非構造化データにデータ プロファイルを使用するをご覧ください。

このドキュメントでは、必要な権限を設定し、非構造化ファイルを準備し、REST API を使用してセマンティック推論が有効になっている Cloud Storage 検出スキャンを作成し、生成された分析情報を表示し、グラフ プロファイルをキュレートし、データを BigQuery に抽出する方法について説明します。

始める前に

検出スキャンを作成する前に、必要な権限があり、必要な API が有効になっていることを確認してください。

API を有効にする

プロジェクトで次の API を有効にします。

• dataplex.googleapis.com
• bigquery.googleapis.com
• aiplatform.googleapis.com（Vertex AI）

API を有効にする

必要なロールと権限

非構造化データのデータ プロファイル スキャンを構成して実行するには、検出スキャンのベースライン権限を満たし、複数のサービス エージェントにわたるセマンティック推論の追加ロールを付与する必要があります。

ベースライン検出スキャンのロール

Knowledge Catalog で使用されるユーザーとサービス アカウントに、標準検出スキャンに必要なベースライン権限があることを確認します。完全なリストについては、Cloud Storage データの検出とカタログ化をご覧ください。

セマンティック推論の追加ロール

ベースライン検出ロールに加えて、自分とサービス アカウントに次の Identity and Access Management（IAM）ロールが付与されていることを確認します。

エンドユーザーの役割と権限

スキャンの作成、分析情報の表示、グラフ プロファイルのキュレーション、データの抽出に必要な権限がユーザー アカウントに付与されるように、プロジェクトに対する次の IAM ロールをユーザー アカウントに付与するよう管理者に依頼してください。

• スキャンを作成して分析情報を表示する:
  • Dataplex DataScan 編集者 （roles/dataplex.dataScanEditor）
  • Dataplex Catalog 編集者 （roles/dataplex.catalogEditor）
• SQL またはパイプラインを使用してデータを抽出する:
  • BigQuery データ編集者 （roles/bigquery.dataEditor）
  • BigQuery ジョブユーザー （roles/bigquery.jobUser）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、スキャンの作成、分析情報の表示、グラフ プロファイルのキュレーション、データの抽出に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、これらの権限をユーザー アカウントに付与することもできます。

Dataplex Discovery サービス エージェントのロールと権限

Dataplex 検出サービス エージェントは、Vertex AI を使用してスキャンを実行し、セマンティック推論を行うためにアクセス権が必要なサービス エージェントです。

Dataplex 検出サービス エージェント（通常は service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）に、スキャンを実行し、Vertex AI を使用してセマンティック推論を実行するために必要な権限が付与されるように、プロジェクトの Dataplex 検出サービス エージェント（通常は service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）に次の IAM ロールを付与するよう管理者に依頼してください。

• すべて:
  • Vertex AI ユーザー （roles/aiplatform.user）
  • Dataplex Discovery サービス エージェント （roles/dataplex.discoveryServiceAgent）
  • BigQuery ジョブユーザー （roles/bigquery.jobUser）
  • BigQuery データ閲覧者 （roles/bigquery.dataViewer）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、Vertex AI を使用してスキャンを実行し、セマンティック推論を実行するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

管理者は、Dataplex 検出サービス エージェント（通常は service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）に、カスタムロールや他の事前定義ロールを付与することもできます。

BigQuery 接続サービス アカウントのロールと権限

BigQuery Cloud リソース接続を使用すると、Knowledge Catalog は Cloud Storage に保存されている非構造化データにアクセスできます。接続を作成すると、BigQuery は専用のサービス アカウントを自動的に作成します。このサービス アカウントは、外部データソースへの接続に使用される ID として機能します。

デフォルトでは、このサービス アカウントには権限がありません。データを含む Cloud Storage バケットに必要な IAM ロールをこのサービス アカウントに明示的に付与する必要があります。既存の BigQuery 接続を使用するか、ソース Cloud Storage バケットと同じロケーションに新しい接続を作成できます。接続の共有の詳細については、ユーザーと接続を共有するをご覧ください。

BigQuery 接続サービス アカウント（接続の詳細の接続情報セクションから ID を取得）にオブジェクト テーブルの読み取りと推論の実行に必要な権限があることを確認するには、BigQuery 接続サービス アカウント（接続の詳細の接続情報セクションから ID を取得）に次の IAM ロールを付与するよう管理者に依頼してください。

• すべて:
  • 非構造化データを含むバケットに対する Storage オブジェクト閲覧者 （roles/storage.objectViewer）
  • プロジェクトに対する Vertex AI ユーザー （roles/aiplatform.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、オブジェクト テーブルの読み取りと推論の実行に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

管理者は、BigQuery 接続のサービス アカウント（接続の詳細の接続情報セクションから ID を取得）に、カスタムロールや他の事前定義ロールを付与することもできます。

パイプライン実行サービス アカウントのロールと権限（省略可）

自動化されたパイプラインを使用して推論されたデータを抽出する場合は、パイプラインを実行するための専用のサービス アカウントを作成するか、指定する必要があります。この実行サービス アカウントは、BigQuery でバックグラウンドのデータ抽出タスクと分析タスクを認証して実行する ID として機能します。また、この実行サービス アカウントの権限を借用する権限をデフォルトの Dataform サービス アカウントに付与する必要があります。

パイプライン実行サービス アカウントに、パイプラインを使用して推論されたエンティティとリレーションを抽出するために必要な権限が付与されるように、プロジェクトに対する次の IAM ロールをパイプライン実行サービス アカウントに付与するよう管理者に依頼してください。

• すべて:
  • BigQuery データ編集者 （roles/bigquery.dataEditor）
  • BigQuery ジョブユーザー （roles/bigquery.jobUser）
  • BigQuery ユーザー（roles/bigquery.user）
  • Vertex AI ユーザー （roles/aiplatform.user）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、パイプラインを使用して推論されたエンティティとリレーションシップを抽出するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

管理者は、カスタムロールや他の事前定義ロールを使用して、これらの権限をパイプライン実行サービス アカウントに付与することもできます。

デフォルトの Dataform サービス アカウント（service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com）に、パイプライン実行サービス アカウントの権限を借用するために必要な権限があることを確認するには、パイプライン実行サービス アカウントに対する次の IAM ロールをデフォルトの Dataform サービス アカウント（service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com）に付与するよう管理者に依頼してください。

• すべて: サービス アカウント トークン作成者 （roles/iam.serviceAccountTokenCreator）

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、パイプライン実行サービス アカウントの権限を借用するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

管理者は、デフォルトの Dataform サービス アカウント（service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com）に、カスタムロールや他の事前定義ロールを付与することもできます。

非構造化データを準備する

検出スキャンを実行する前に、非構造化データを Cloud Storage バケットにアップロードする必要があります。非構造化データのデータ プロファイル スキャンは、PDF ドキュメントの分析用に最適化されています。

Cloud Storage でのファイルの保存と管理の詳細については、オブジェクトをアップロードするをご覧ください。

Cloud リソース接続を作成する

検出スキャンの結果を BigQuery オブジェクト テーブルとして公開するには、Cloud リソース接続を作成し、そのサービス アカウントに Cloud Storage の非構造化データへのアクセス権を付与する必要があります。

1. Cloud リソース接続を作成します。
2. 非構造化データを含む Cloud Storage バケットで、接続に関連付けられたサービス アカウントに Storage オブジェクト閲覧者（roles/storage.objectViewer）ロールを付与します。詳細については、サービス アカウントにアクセス権を付与するをご覧ください。

非構造化データの検出スキャンを作成する

非構造化データからセマンティック分析情報を抽出するには、まず Cloud Storage 検出スキャンを作成する必要があります。このスキャンでは、Cloud Storage 内の非構造化ファイルが自動的に特定され、オブジェクト テーブルにカタログ化されます。このプロセスでセマンティック推論を有効にすると、Knowledge Catalog は Vertex AI Gemini 2.5 Pro モデルを使用してファイルを分析し、推論されたメタデータ、スキーマ、関係を生成します。

セマンティック推論が有効になっている Cloud Storage 検出スキャンは、 Google Cloud コンソールまたは REST API を使用して作成できます。

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
"description": "Cloud Storage discovery scan with semantic inference",
"data": {
"resource": "//storage.googleapis.com/BUCKET_NAME"
},
"executionSpec": {
"trigger": {
  "onDemand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
  "tableType": "OBJECT_TABLE",
  "connection": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID"
},
"unstructuredDataEventsConfig": {
  "enabled": true
}
}
}

検出スキャンを実行する

オンデマンドで実行するように検出スキャンを構成した場合は、スキャンを手動でトリガーして、非構造化データを特定し、分析情報を生成する必要があります。

検出スキャンは、 Google Cloud コンソールまたは REST API を使用してトリガーできます。

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN:run"

Knowledge Catalog は検出スキャンを実行し、オブジェクト テーブルを作成して、AI 生成のメタデータでカタログ エントリを拡充します。通常、このプロセスには標準データセットで数分かかります。

オブジェクト テーブルを見つける

検出スキャンが完了すると、Knowledge Catalog は 1 つ以上のオブジェクト テーブルを作成し、AI 生成メタデータで強化された対応するエントリを Knowledge Catalog に入力します。検出スキャンによって複数のエントリが作成された場合、各エントリには独自の [分析情報] タブがあります。自動生成されたテーブルの説明、推論されたスキーマ、リレーションシップ グラフを表示できます。

1. Google Cloud コンソールで、[BigQuery] ページに移動します。

   [BigQuery] に移動

2. ナビゲーション メニューで、[ガバナンス> メタデータのキュレーション] をクリックします。

3. [Cloud Storage 検出] ペインで、非構造化データに対して実行した検出スキャンをクリックします。

   • [スキャンの詳細] セクションには、検出スキャンの詳細が表示されます。
   • [スキャンのステータス] セクションには、最新のスキャンジョブの検出結果が表示されます。

4. [公開済みデータセット] のリンクをクリックします。

5. BigQuery データセットに表示されたテーブルのリストで、検出データ スキャン用に生成されたオブジェクト テーブルを選択します。

6. テーブル ID をコピーします。これは次のセクションで必要になります。

検出スキャン結果を調べる

オブジェクト テーブルとその推論されたセマンティック グラフは、Knowledge Catalog で確認できます。

1. Google Cloud コンソールで、Knowledge Catalog の [検索] ページに移動します。

   [検索] に移動

2. 前のセクションで選択した ID のオブジェクト テーブルを貼り付けて検索します。

3. 検索結果で、表をクリックしてエントリページを開きます。

4. [詳細] タブの [アスペクト] で、グラフ プロファイル アスペクト（dataplex-types.global.graph-profile）が存在することを確認します。このアスペクトには、エンティティとリレーションシップの推論されたスキーマが含まれています。

5. [分析情報] タブをクリックします。[分析情報] タブでは、次の情報を確認できます。

   • セマンティック抽出。抽出可能なエンティティとリレーションが検出されたことを示すバナーが表示されます。このバナーには、SQL またはパイプラインのデプロイを使用してデータを具体化するための [抽出] ボタンが含まれています。

   • 説明。AI が生成した人が読める形式の要約で、非構造化データのコンテンツを説明します。検出されたプライマリ ノード（エンティティ）と、エッジ（関係）を介して互いにマッピングする方法について説明します。

   • パイプライン。このリソースに関連付けられている、以前にデプロイされたデータ抽出パイプラインのリスト。表示名、リージョン、作成時間、パイプラインを作成したユーザーを表示できます。

   • 推論されたエンティティと関係。非構造化データの検出されたセマンティック構造が、インタラクティブなグラフで視覚的に表示されます。グラフには、個別のエンティティ（Recipe や Ingredient など）を表すノードと、それらの間の接続（HasAllergenStatus など）を表すエッジが含まれています。凡例を使用して、特定のノードとエッジをフィルタして探索できます。

   • エンティティ。検出されたプライマリ エンティティの詳細なリスト。各エンティティを展開して、AI によって生成された説明と、フィールド名、データ型、フィールドの説明を含む推論されたスキーマを表示できます。

   • 関係。検出されたエンティティ間の接続の詳細なリスト。各関係を展開して、その説明と、エンティティ間のマッピング方法を定義するスキーマを表示できます。

推論された分析情報を更新する

推論された分析情報は、オブジェクト テーブルに付加されたアスペクトとして Knowledge Catalog カタログに保存されます。これらの分析情報は、REST API を使用して手動で更新できます。

BigQuery にデータを抽出する

SQL または自動パイプラインを使用して、推論されたエンティティとリレーションシップを BigQuery の構造化テーブルまたはビューにマテリアライズできます。

1. Google Cloud コンソールで、Knowledge Catalog の [検索] ページに移動します。

   [検索] に移動

2. スキャンで生成されたオブジェクト テーブルを検索します。

3. 検索結果で、表をクリックしてエントリページを開きます。

4. [分析情報] タブをクリックします。

5. [分析情報] タブで、[抽出] をクリックします。

6. 分析のニーズと非構造化データの規模に基づいて、次のいずれかの方法を選択します。

   • SQL で抽出: 迅速なアドホック分析、小規模から中規模のデータセット、または BigQuery リモートモデルを使用したインフラストラクチャ不要のアプローチが必要な場合は、このオプションを選択します。

     SQL を使用して抽出する手順は次のとおりです。

     1. [SQL で抽出] を選択します。
     2. [SQL で抽出] ペインで、宛先データセットを選択します。データセットは、ソースと同じロケーションに存在する必要があります。
     3. [Extract] をクリックします。
     4. BigQuery エディタで、ML.PROCESS_DOCUMENT 関数を利用する事前入力されたクエリが開きます。クエリを実行して、標準テーブルとビューを作成します。

     SQL を使用してドキュメントの分析情報を抽出する方法については、ML.PROCESS_DOCUMENT 関数を使用してドキュメントを処理するをご覧ください。

   • パイプラインで抽出: 大規模なデータ処理を行う場合や、大量のドキュメントを処理するために堅牢な再試行ロジック、エラー処理、自動オーケストレーションが必要な場合は、このオプションを選択します。

     パイプラインを使用して抽出する手順は次のとおりです。

     1. [Extract by pipeline] を選択します。
     2. [パイプラインで抽出] ペインで、パイプラインの表示名を入力します。
     3. リージョンを選択します。
     4. 宛先データセットを選択します。データセットは、ソースと同じロケーションに存在する必要があります。
     5. [抽出] をクリックします。これにより、Dataform を使用してデータ マテリアライズをオーケストレートする BigQuery パイプラインが作成されます。
     6. パイプライン内のすべてのタスクを実行して、構造化されたノードビューとエッジビューを生成します。

     データ ワークフローの実行の詳細については、Dataform の概要をご覧ください。

セマンティック分析情報を抽出して BigQuery にマテリアライズすると、次のタスクを実行できます。

• 構造化データをクエリします。新しく作成したテーブルに対して標準 SQL クエリを実行して、抽出したエンティティとリレーションシップを分析します。

• 既存のデータと結合する。非構造化ファイルから抽出した定性的な分析情報を、既存の構造化 BigQuery データセットと組み合わせます（解析された請求書データを会計テーブルと結合するなど）。

• データ分析情報を確認します。BigQuery Studio のデータ分析情報機能を使用して、新しい構造化アセットの自然言語の質問と SQL クエリを自動的に生成します。

• Gemini で分析する。Gemini in BigQuery を使用して、会話分析の実行、傾向の要約、抽出されたデータに基づくデータポータルのダッシュボードの作成を行います。

次のステップ

• 非構造化データにデータ プロファイルを使用する方法を学習する。
• 詳しくは、データの検出をご覧ください。
• データ プロファイリングについてを読む。