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

このドキュメントでは、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 を目標のトラバーサル深度に設定します(1100 の値を受け付けます)。

  • locations 配列に、バックエンドで相互参照するターゲット リージョン(["us", "us-east1"] など)を入力します。

C#

C#

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

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

using Google.Api.Gax.Grpc;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.DataCatalog.Lineage.V1;
using System.Threading.Tasks;

public sealed partial class GeneratedLineageClientSnippets
{
    /// <summary>Snippet for SearchLineageStreaming</summary>
    /// <remarks>
    /// 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://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public async Task SearchLineageStreamingRequestObject()
    {
        // Create client
        LineageClient lineageClient = LineageClient.Create();
        // Initialize request argument(s)
        SearchLineageStreamingRequest request = new SearchLineageStreamingRequest
        {
            ParentAsLocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            Locations = { "", },
            RootCriteria = new SearchLineageStreamingRequest.Types.RootCriteria(),
            Direction = SearchLineageStreamingRequest.Types.SearchDirection.Unspecified,
            Filters = new SearchLineageStreamingRequest.Types.SearchFilters(),
            Limits = new SearchLineageStreamingRequest.Types.SearchLimits(),
        };
        // Make the request, returning a streaming response
        using LineageClient.SearchLineageStreamingStream response = lineageClient.SearchLineageStreaming(request);

        // Read streaming responses from server until complete
        // Note that C# 8 code can use await foreach
        AsyncResponseStream<SearchLineageStreamingResponse> responseStream = response.GetResponseStream();
        while (await responseStream.MoveNextAsync())
        {
            SearchLineageStreamingResponse responseItem = responseStream.Current;
            // Do something with streamed response
        }
        // The response stream has completed
    }
}

Java

Java

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

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

import com.google.api.gax.rpc.ServerStream;
import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.LocationName;
import com.google.cloud.datacatalog.lineage.v1.SearchLineageStreamingRequest;
import com.google.cloud.datacatalog.lineage.v1.SearchLineageStreamingResponse;
import java.util.ArrayList;

public class AsyncSearchLineageStreaming {

  public static void main(String[] args) throws Exception {
    asyncSearchLineageStreaming();
  }

  public static void asyncSearchLineageStreaming() throws Exception {
    // 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://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (LineageClient lineageClient = LineageClient.create()) {
      SearchLineageStreamingRequest request =
          SearchLineageStreamingRequest.newBuilder()
              .setParent(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .addAllLocations(new ArrayList<String>())
              .setRootCriteria(SearchLineageStreamingRequest.RootCriteria.newBuilder().build())
              .setFilters(SearchLineageStreamingRequest.SearchFilters.newBuilder().build())
              .setLimits(SearchLineageStreamingRequest.SearchLimits.newBuilder().build())
              .build();
      ServerStream<SearchLineageStreamingResponse> stream =
          lineageClient.searchLineageStreamingCallable().call(request);
      for (SearchLineageStreamingResponse response : stream) {
        // Do something when a response is received.
      }
    }
  }
}

Node.js

Java

このサンプルを試す前に、クライアント ライブラリを使用した Knowledge Catalog のクイックスタートにある Java の設定手順を行ってください。

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.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The project and location to initiate the search from.
 */
// const parent = 'abc123'
/**
 *  Required. The locations to search in.
 */
// const locations = ['abc','def']
/**
 *  Required. Criteria for the root of the search.
 */
// const rootCriteria = {}
/**
 *  Required. Direction of the search.
 */
// const direction = {}
/**
 *  Optional. Filters for the search.
 */
// const filters = {}
/**
 *  Optional. Limits for the search.
 */
// const limits = {}

// Imports the Lineage library
const {LineageClient} = require('@google-cloud/lineage').v1;

// Instantiates a client
const lineageClient = new LineageClient();

async function callSearchLineageStreaming() {
  // Construct request
  const request = {
    parent,
    locations,
    rootCriteria,
    direction,
  };

  // Run request
  const stream = await lineageClient.searchLineageStreaming(request);
  stream.on('data', (response) => { console.log(response) });
  stream.on('error', (err) => { throw(err) });
  stream.on('end', () => { /* API call completed */ });
}

callSearchLineageStreaming();

Python

Python

このサンプルを試す前に、クライアント ライブラリを使用した Knowledge Catalog のクイックスタートにある Python の設定手順を行ってください。詳細については、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 datacatalog_lineage_v1


def sample_search_lineage_streaming():
    # Create a client
    client = datacatalog_lineage_v1.LineageClient()

    # Initialize request argument(s)
    request = datacatalog_lineage_v1.SearchLineageStreamingRequest(
        parent="parent_value",
        locations=["locations_value1", "locations_value2"],
        direction="UPSTREAM",
    )

    # Make the request
    stream = client.search_lineage_streaming(request=request)

    # Handle the response
    for response in stream:
        print(response)

Ruby

Ruby

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

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

require "google/cloud/data_catalog/lineage/v1"

##
# Snippet for the search_lineage_streaming call in the Lineage service
#
# 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://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::DataCatalog::Lineage::V1::Lineage::Client#search_lineage_streaming.
#
def search_lineage_streaming
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::DataCatalog::Lineage::V1::Lineage::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::DataCatalog::Lineage::V1::SearchLineageStreamingRequest.new

  # Call the search_lineage_streaming method to start streaming.
  output = client.search_lineage_streaming request

  # The returned object is a streamed enumerable yielding elements of type
  # ::Google::Cloud::DataCatalog::Lineage::V1::SearchLineageStreamingResponse
  output.each do |current_response|
    p current_response
  end
end

REST

データリネージを検索するには、searchLineageStreaming メソッドを使用します。

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

  • PROJECT_ID: 管理課金と割り当て評価に使用される Google Cloud プロジェクト ID。
  • LOCATION_ID: Google Cloud ロケーション(us-central1 など)。
  • SOURCE_PROJECT_ID: ソーステーブルが配置されている Google Cloud プロジェクト ID。
  • DATASET_ID: BigQuery データセット ID。
  • TABLE_ID: BigQuery テーブル ID。

HTTP メソッドと URL:

POST https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:searchLineageStreaming

リクエストの本文(JSON):

{
  "parent": "projects/PROJECT_ID/locations/LOCATION_ID",
  "locations": [
    "LOCATION_ID",
    "us-east1",
    "us-central1"
  ],
  "rootCriteria": {
    "entities": {
      "entities": [
        {
          "fullyQualifiedName": "bigquery:SOURCE_PROJECT_ID.DATASET_ID.TABLE_ID"
        }
      ]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}

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

次のような JSON レスポンスが返されます。

{
  "links": [
    {
      "source": {
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      },
      "target": {
        "fullyQualifiedName": "bigquery:project-prod.dataset.target_table"
      },
      "depth": 1,
      "location": "us"
    }
  ]
}

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

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 を使用する必要があります。

  1. limits.maxProcessPerLink に 0 以外の値を指定します。

  2. URL パスに fields クエリ パラメータを追加し、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

次のステップ