Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

サーバーサイドの自動化を使用してマルチリージョンリネージを検索する

このドキュメントでは、searchLineageStreaming API を使用してマルチレベルのクロスリージョンデータリネージを検索する方法について説明します。

searchLineageStreaming API は、定義されたルートエンティティのセットから指定された方向（上流または下流）に幅優先検索を実行し、統合されたリネージグラフをリアルタイムストリーミングレスポンスとして返します。

詳細については、マルチリージョンリネージ検索についてをご覧ください。

主な機能

searchLineageStreaming API には次の機能があります。

幅優先探索: リネージグラフをレイヤごとに走査し、接続されている各アセットの深さを正確に計算します。
ストリーミングレスポンス: バックエンドシステムで検出されたサブグラフとリネージリンクを返します。これは、広範な系統グラフや詳細な系統グラフに非常に効率的で、リクエストのタイムアウトを防ぎます。
マルチロケーションとマルチプロジェクトのトラバーサル: リクエストパスで指定する課金プロジェクトは 1 つだけですが、必要な権限があれば、API は複数の Google Cloud プロジェクトと地理的位置にわたってリネージリンクを自動的に検出してトラバースします。
きめ細かい列レベルのリネージ: アセット間の列レベルの依存関係の検索をサポートします。
ワイルドカード検索: 完全修飾された名前（FQN）に * を付加することで、特定のエンティティのすべての列レベルのリネージを取得できます。
パイプラインの分析情報: リネージリンクを作成した変換パイプライン（プロセス）に関するメタデータを必要に応じて取得します。

始める前に

API にリクエストを行う前に、次のセキュリティと環境の前提条件を満たしていることを確認してください。

必要なロール

データリネージリンクを検索するために必要な権限を取得するには、リネージリンクとプロセスが保存されているプロジェクトに対する Data Lineage 閲覧者（roles/datalineage.viewer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織に対するアクセス権の管理をご覧ください。

この事前定義ロールには、データリネージリンクの検索に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

データリネージリンクを検索するには、次の権限が必要です。

エンティティレベルの系統を検索する: リンクが保存されているプロジェクトに対する datalineage.events.get
列レベルのリネージを検索する: リンクが保存されているプロジェクトに対する datalineage.events.getFields
パイプラインプロセスの詳細をすべて取得する: プロセスが保存されているプロジェクトに対する datalineage.processes.get

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

リソースのスコープ設定

API リクエストを構成するときは、管理請求に使用されるリソースと API によってスキャンされる実際のロケーションを区別する必要があります。

請求先親パス: URL リクエストの parent パスは projects/project/locations/location 形式を使用する必要があります。この特定のプロジェクトとロケーションのペアは、課金割り当てと API レート制限の評価にのみ使用されます。
ターゲットのロケーション: リクエスト本文内の locations 配列で、バックエンドにスキャンさせるリージョンを明示的に定義します。

認証の設定

curl コマンドを認証する Google Cloud アクセストークンを使用して環境変数を初期化します。

export ACCESS_TOKEN=$(gcloud auth print-access-token)

使用例

次の例では、エンドポイント datalineage.googleapis.com を使用します。

マルチレベル、マルチプロジェクトの系統を検索する

グラフの複数の深さをトラバースし、個別の Google Cloud プロジェクトをスキャンする詳細なリネージ検索を実行するには、次の変数を定義します。

limits.maxDepth を目標のトラバーサル深度に設定します（1～100 の値を受け付けます）。
locations 配列に、バックエンドで相互参照するターゲットリージョン（["us", "us-east1"] など）を入力します。

次に例を示します。

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "us-east1", "us-central1"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      }]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}'

複数の地理的位置を検索する

locations 繰り返し配列フィールド内で渡される地理的リージョンを変更することで、リネージグラフのスキャンを制限または拡大できます。

次に例を示します。

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us", "europe-west1", "asia-south2"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.global_table"
      }]
    }
  },
  "direction": "DOWNSTREAM"
}'

リネージリンクのプロセス名を取得する

デフォルトでは、API はプロセス情報を省略します（maxProcessPerLink はデフォルトで 0 に設定されています）。データリンクを作成したパイプラインのリソース名を取得するには、limits.maxProcessPerLink を 0 以外の正の整数に構成します。

次に例を示します。

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

レスポンスの動作: 結果のストリームは、絶対システムリソース名（projects/my-project/locations/us/processes/my-process など）のみを含むプロセスメッセージで links[].processes フィールドを移入します。

FieldMask を使用してプロセス全体の詳細を取得する

リソース名だけでなく、パイプラインの完全な構造メタデータ（displayName、システム attributes、実行 origin など）が必要な場合は、API FieldMask を使用する必要があります。

limits.maxProcessPerLink に 0 以外の値を指定します。
fields クエリパラメータを URL パスに追加し、links.processes.process と他の必須フィールドを指定します。

次に例を示します。

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-X POST "https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming?fields=links.processes.process,links.source,links.target,links.depth" \
--data '{
  "parent": "projects/my-billing-project/locations/us",
  "locations": ["us"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:my-project.dataset.target_table"
      }]
    }
  },
  "direction": "UPSTREAM",
  "limits": {
    "maxProcessPerLink": 5
  }
}'

テーブルレベルと列レベルの両方のリネージを検索する

rootCriteria.entities.entities リストに複数のエンティティを指定すると、1 つのリクエストでテーブルレベル（アセットレベル）と列レベル（フィールドレベル）の両方のリネージを検索できます。

テーブルレベルのリネージの場合は、field 配列を省略します。
列レベルのリネージの場合は、field 配列で単一の列を指定します。

次に例を示します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_a"
             },
             {
               "fullyQualifiedName": "bigquery:my-project.dataset.table_b",
               "field": ["email"]
             }
           ]
         }
       },
       "direction": "DOWNSTREAM"
     }'

列レベルのリネージにワイルドカードを使用する

すべての列を個別にリストすることなく、特定のテーブルで使用可能なすべての列レベルの系統を検索するには、field 配列の単一の値としてワイルドカード文字 * を使用します。

次に例を示します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table",
             "field": ["*"]
           }]
         }
       },
       "direction": "DOWNSTREAM"
     }'

リネージの結果をフィルタする

リクエスト本文の filters ブロックを使用して、リネージ検索結果を絞り込むことができます。

依存関係のタイプでフィルタする

結果を特定の依存関係タイプ（直接コピー（EXACT_COPY）やフィルタリングやグループ化などの変換（OTHER）など）に制限するには、dependencyTypes フィルタを使用します。

次に例を示します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "dependencyTypes": ["EXACT_COPY"]
       }
     }'

テーブルのみのリネージに制限する

検索でテーブルレベルのリネージのみが返され、列レベルのリネージが完全に除外されるようにするには、entitySet フィルタを ENTITIES に設定します。

次に例を示します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "entitySet": "ENTITIES"
       }
     }'

期間でフィルタ

リネージ検索結果を特定の期間に制限できます。

たとえば、特定のタイムスタンプの後に作成されたリネージデータを検索するには、次のリクエストを使用します。

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -X POST https://datalineage.googleapis.com/v1/projects/my-billing-project/locations/us:searchLineageStreaming \
     --data '{
       "parent": "projects/my-billing-project/locations/us",
       "locations": ["us"],
       "rootCriteria": {
         "entities": {
           "entities": [{
             "fullyQualifiedName": "bigquery:my-project.dataset.my_table"
           }]
         }
       },
       "direction": "DOWNSTREAM",
       "filters": {
         "timeRange": {
           "startTime": "2026-01-01T00:00:00Z"
         }
       }
     }'

アクセスできないロケーションを処理する（部分的な結果）

ストリーミング API は分散されたプロジェクトとロケーションを同時にスキャンするため、実行中に一部のリモートリージョンが一時的にダウンしたり、通信不能になったり、構成が誤っている可能性があります。

データの完全性を保護するため、searchLineageStreamingResponse ストリームには unreachable という専用の診断フィールドが含まれています。

フィールド名: unreachable（繰り返し文字列として表される）
値の形式: projects/PROJECT_NUMBER/locations/LOCATION（例: projects/123456789/locations/us-east1）

次のステップ

詳しくは、マルチリージョンリネージ検索をご覧ください。
詳しくは、データリネージをご覧ください。
詳しくは、リネージの可視化をご覧ください。

サーバーサイドの自動化を使用してマルチリージョン リネージを検索する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

主な機能

始める前に

必要なロール

必要な権限

リソースのスコープ設定

認証の設定

使用例

マルチレベル、マルチプロジェクトの系統を検索する

複数の地理的位置を検索する

リネージ リンクのプロセス名を取得する

FieldMask を使用してプロセス全体の詳細を取得する

テーブルレベルと列レベルの両方のリネージを検索する

列レベルのリネージにワイルドカードを使用する

リネージの結果をフィルタする

依存関係のタイプでフィルタする

テーブルのみのリネージに制限する

期間でフィルタ

アクセスできないロケーションを処理する（部分的な結果）

次のステップ

サーバーサイドの自動化を使用してマルチリージョンリネージを検索する

リネージリンクのプロセス名を取得する