データ ドメインを使用する

Knowledge Catalog（旧称 Dataplex Universal Catalog）のデータドメインを使用すると、検索結果を特定のビジネス コンテキストに絞り込み、定義された境界内でメタデータを検出できます。データドメイン ユーザーは、ドメイン階層の閲覧、ドメイン リソースの検索、ドメイン コンテキストの取得を行い、AI エージェントをグラウンディングできます。

始める前に

ドメインで検索を実行する前に、必要なロールと API が有効になっていることを確認してください。

API を有効にする

Dataplex API が有効になっていない場合は、有効にします。

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

API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を介してこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を介してこの権限を取得できます。ロールを付与する方法を確認する。

API の有効化

必要なロール

データドメインを使用してメタデータを検索して検出するために必要な権限を取得するには、プロジェクトまたはデータドメインに対する次の IAM ロールを付与するよう管理者に依頼してください。

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

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

ドメイン階層を閲覧する

ドメイン階層を閲覧する方法については、ロケーションのデータドメインとサブドメインを表示するをご覧ください。

データドメイン内のリソースを検索する

データドメイン内を検索して、BigQuery データセット、テーブル、データ プロダクトなどのリソースを見つけ、そのメタデータを表示できます。ドメイン内のリソースを検索する手順は次のとおりです。

コンソール

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

    [検索] に移動

  2. [自然検索を試す] をクリックして、自然検索機能を有効にします。

  3. [フィルタ] をクリックします。

  4. [スコープ] フィールドで、リストから [ドメイン] を選択します。

  5. [ドメインを選択] フィールドで、結果を絞り込むドメインを選択します。必要に応じて、追加のフィルタを追加します。

または、[ドメイン内を検索] メニュー オプションを使用して、ドメイン内のリソースを検索することもできます。

  1. Google Cloud コンソールで、[データドメイン] ページに移動します。

    [データドメイン] に移動

  2. メニューから [ドメイン内を検索] を選択します。この操作により、ドメイン フィルタが適用された検索ウィンドウが自動的に開きます。

  3. 検索フィールドを使用して、ドメイン内のリソースを検索します。

REST

データドメインを対象とするエントリを検索するには、projects.locations.searchEntries メソッドを使用し、contexts パラメータにドメインパスを指定します。

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Google Cloud プロジェクト ID。
  • LOCATION_ID: 検索クエリのリージョン（または global）。
  • QUERY: 検索クエリ文字列。
  • DOMAIN_ID: 検索スコープのコンテキストを定義するデータドメインの固有識別子。

HTTP メソッドと URL:

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchEntries

リクエストの本文（JSON）: 

{
  "query": "QUERY",
  "contexts": [ "projects/PROJECT_ID/locations/LOCATION_ID/dataDomains/DOMAIN_ID" ],
  "semantic_search": true,
  "page_size": 100
}

リクエストを送信するには、次のいずれかのオプションを展開します。

成功したことを示すステータス コード（2xx）と空のレスポンスが返されます。

データドメインのコンテキストを取得する

lookupContext メソッドを使用すると、データドメインによってキャプチャされたビジネス コンテキストに AI エージェントをグラウンディングできます。lookupContext メソッドは、次の方法でデータドメインをサポートしています。

  • データドメインのコンテキスト。resources リストでデータドメインを表すエントリを渡すことができます。レスポンスには、データドメインの説明やドメイン階層内の親データドメインなど、データドメインのメタデータが含まれます。
  • データアセットのデータドメイン メンバーシップ。1 つ以上のデータドメインに含まれるデータアセットのコンテキストを取得すると、レスポンスには、アセットが属するデータドメインをリストする dataDomains フィールドが含まれます。このリストは、最も具体的なドメインから始まり、トップレベル ドメインまで昇順で表示されます。

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

curl --request POST \
  'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H 'Content-Type: application/json' \
  -d '{
    "resources": [
      "projects/PROJECT_ID/locations/LOCATION/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION/dataDomains/DATA_DOMAIN_ID"
    ],
    "options": {
      "format": "yaml"
    }
  }'

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

  • PROJECT_ID: データドメインを含むプロジェクトの ID。
  • PROJECT_NUMBER: データドメインを含むプロジェクトの番号。
  • LOCATION: データドメインのロケーション。
  • DATA_DOMAIN_ID: データドメインの ID。

lookupContext メソッドの詳細については、データアセットのコンテキストを取得するをご覧ください。

制限事項

ドメイン コンテキスト外でリソースを検索する場合（グローバル検索を使用する場合など）、ドメインの検出権限は適用されません。表示されるのは、BigQuery などの基盤となるシステムでアクセス権を持つリソースのみです。

BigQuery データセットがデータドメインに含まれているとします。ドメインの Dataplex Data Domain Entry Reader ロールが付与されているが、BigQuery でデータセットを表示する直接的な権限がない。

  • ドメイン内での検索: ドメイン権限が適用されるため、検索結果にデータセットが表示されます。
  • ドメイン外の検索: 検索結果にデータセットが表示されません。一般的な検索では、ドメイン権限は適用されず、BigQuery に直接アクセスすることはできません。

次のステップ