データアセットのコンテキストを取得する

このプロダクトまたは機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります 。 pre-GA のプロダクトと機能は「現状のまま」利用できますが、サポートが制限されることがあります。 詳細については、 リリース ステージの説明をご覧ください。

データのコンテキストにより、AI アプリケーションはデータアセットを深く理解し、LLM が生成するレスポンスの精度と関連性を向上させることができます。

The lookupContext メソッドは、単一の API リクエストを使用してコンテキストのギャップを埋め、インタラクティブな Agentic Workflows に最適化されたデータアセットのメタデータの事前フォーマット済みバンドルを取得します。このコンパクトな LLM 対応コンテキストを使用して、エージェントがデータアセットを評価して使用する際の根拠にすることができます。

lookupContext メソッドは、Knowledge Catalog に保存されているデータアセット（BigQuery テーブル、データセット、その他の エントリなど）に使用できます。

lookupContext メソッドを使用してアセットのコンテキストを取得する方法

1. エージェントは、コンテキストの取得に関連する可能性のあるデータアセットを取得します（Knowledge Catalog のセマンティック検索などを使用）。
2. エージェントは lookupContext メソッドを使用して、特定のアセットのコンテキストを取得する単一の API 呼び出しまたは MCP ツール リクエストを行います。

3. このメソッドは、事前フォーマットされたテキスト ブロックを含むレスポンスを返します。リクエストで指定する format パラメータに応じて、ドキュメントの形式は YAML、XML、JSON になります。

   レスポンスには次のコンテキスト要素が含まれます。

   コンテキスト要素	説明
   テクニカル メタデータ	リソース スキーマと物理構成（BigQuery のパーティショニングとクラスタリング戦略など）。
   運用メタデータ	過去のクエリログとデータ分析情報に基づく結合やその他の関係。詳細については、データ関係を表示するをご覧ください。
   ビジネスの説明	関連するビジネス用語、概要、カタログ アノテーション、ソースシステムでキャプチャされ Knowledge Catalog で自動生成された説明、ガイドライン。 注: データアセットのガイドライン アスペクトを使用すると、エージェントがデータアセットを検出、検査、使用する際に役立つ追加のコンテキストをキャプチャできます。
   データ プロファイル	分布統計、個別の値の数、null 比率、サンプル値。
   データ品質	事前定義されたルールに対する自動データ品質チェックの出力。
   関連するデータアセットのコンテキスト	関連するデータアセットのコンテキスト（用語集の用語や、頻繁に結合されるテーブルなどの関連アセット）。関連アセットに対して返されるコンテキストには、メインアセットと同じ範囲の要素が含まれます。

4. エージェントはこのレスポンスを使用して、関連するアセットの選択や使用をガイドします。

始める前に

lookupContext メソッドを使用する前に、必要なロールが付与され、必要な API が有効になっていることを確認してください。

必要なロール

lookupContext メソッドを呼び出すために必要な権限を取得するには、プロジェクトに対する次の IAM ロールを付与するように管理者へ依頼してください。 Google Cloud iam.gserviceaccount.com

• エントリ、エントリ グループ、用語集などのカタログ リソースへの読み取りアクセス: Dataplex Catalog 閲覧者 （roles/dataplex.catalogViewer）

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

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

API を有効にする

lookupContext メソッドを使用するには、プロジェクトで次の API を有効にします。

• Knowledge Catalog API

API を有効にするために必要なロール

API を有効にするには、serviceusage.services.enable 権限を含む Service Usage 管理者 IAM ロール（roles/serviceusage.serviceUsageAdmin）が必要です。詳しくは、ロールを付与する方法をご覧ください。

API の有効化

データアセットのコンテキストを取得する

データアセットのコンテキストを取得するには、lookupContext メソッドに Dataplex API で直接アクセスするか、Knowledge Catalog リモート Model Context Protocol（MCP）サーバー または データベース向け MCP ツールボックス を使用します。

lookupContext メソッドは、権限に基づいてリソースをフィルタします。レスポンスには、ID にアクセスするために必要な Identity and Access Management（IAM）権限があるアセットのデータのみが含まれます。リクエストされたリソースに対する権限がない場合、このメソッドは空のレスポンスを返します。

REST

データアセットのコンテキストを取得するには、次のリクエストを送信します。

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

次のように置き換えます。

• PROJECT_ID: プロジェクトの ID Google Cloud
• LOCATION: アセット が存在するリージョン（例: us-central1）
• RESOURCES：コンテキストを取得するエントリ名（最大 10 個）。projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry} の形式で指定します。 複数のリソースの場合、API はリクエストされたリソース間の関係（頻繁なスキーマ結合など）を確立し、コンテキストに関係情報を返します。
• OPTIONS: コンテキストを定義できるオプション:
  • format はコンテキスト ファイルの形式です。例: yaml
  • context_budget は、レスポンスが制限される文字数です。all_schema_fields パラメータを true に設定すると、API は context_budget の値に関係なく、すべてのスキーマ フィールドを返します。

BigQuery テーブルのコンテキストを取得するリクエストの例は次のとおりです。

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

レスポンスは、次のような事前フォーマットされたテキスト ブロックです。

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

このサンプルを試す前に、Python の設定手順を Knowledge Catalog クイックスタート: クライアント ライブラリの使用にある を完了してください。詳細については、 Knowledge Catalog Python API リファレンス・ドキュメントをご覧ください。

Knowledge Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。 詳細については、 ローカル開発環境の認証の設定をご覧ください。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

次の例は、BigQuery テーブルのコンテキストを取得する方法を示しています。

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

lookupContext メソッドのベスト プラクティス

lookupContext メソッドを使用する際に結果を最適化するには、次のベスト プラクティスを検討してください。

• context_budget パラメータを使用して、出力コンテキストの選択した長さをリクエストします。lookupContext メソッドは、パラメータで指定された制限内で、最も関連性の高いコンテキストを出力に含めることを目指します。
• resources リストには、最大 10 個のデータアセットを一覧表示できます。たとえば、resources リストに複数のテーブルを含めると、API はそれらのテーブルだけでなく、それらのテーブル間の結合パスのコンテキストも提供するため、これらのテーブルを一緒に使用する方法について必要なガイダンスを提供できます。
• 高コストの変換を回避するには、LLM またはエージェントの解析ロジックに最適な format オプション（yaml、json など）を使用します。

次のステップ

• データ検出エージェントを作成する方法を学習する。
• メタデータを強化するエージェントを作成する方法を学習する。
• Knowledge Catalog の検索構文を理解する。
• データ関係の表示の詳細を確認する。