Menelusuri silsilah multi-region menggunakan otomatisasi sisi server

Dokumen ini menjelaskan cara mencari asal data lintas regional dan multi-level menggunakan searchLineageStreaming API.

API searchLineageStreaming melakukan penelusuran breadth-first dalam arah yang ditentukan (hulu atau hilir) yang dimulai dari serangkaian entitas root yang ditentukan, dan menampilkan grafik silsilah terpadu sebagai respons streaming real-time.

Untuk mengetahui informasi selengkapnya, lihat Tentang penelusuran silsilah multi-region.

Kemampuan utama

searchLineageStreaming API mencakup kemampuan berikut:

  • Penelusuran first-breadth: Menelusuri grafik silsilah lapis demi lapis, menghitung secara akurat kedalaman setiap aset yang terhubung.

  • Respons streaming: Menampilkan subgrafik dan link asal data saat ditemukan oleh sistem backend. Hal ini sangat efisien untuk grafik asal data yang luas atau dalam dan mencegah waktu tunggu permintaan habis.

  • Penelusuran multi-lokasi dan multi-project: Meskipun Anda hanya menentukan satu project penagihan di jalur permintaan, API akan otomatis menemukan dan menelusuri link silsilah di beberapa project Google Cloud dan lokasi geografis, asalkan Anda memiliki izin yang diperlukan.

  • Silsilah tingkat kolom yang terperinci: Mendukung penelusuran dependensi tingkat kolom antar-aset.

  • Pencarian karakter pengganti: Memungkinkan Anda mengambil semua silsilah tingkat kolom untuk entity tertentu dengan menambahkan akhiran * ke nama yang sepenuhnya memenuhi syarat (FQN).

  • Insight pipeline: Secara opsional mengambil metadata tentang pipeline transformasi (proses) yang membuat link silsilah.

Sebelum memulai

Sebelum membuat permintaan ke API, pastikan Anda telah memenuhi prasyarat keamanan dan lingkungan berikut:

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menelusuri link silsilah data, minta administrator untuk memberi Anda peran IAM Data Lineage Viewer (roles/datalineage.viewer) di project tempat link dan proses silsilah disimpan. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menelusuri link silsilah data. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menelusuri link silsilah data:

  • Menelusuri silsilah tingkat entity: datalineage.events.get di project tempat link disimpan
  • Telusuri silsilah tingkat kolom: datalineage.events.getFields di project tempat link disimpan
  • Mengambil detail lengkap proses pipeline: datalineage.processes.get pada project tempat proses disimpan

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Pencakupan resource

Saat mengonfigurasi permintaan API, Anda harus membedakan antara resource yang digunakan untuk penagihan administratif dan lokasi sebenarnya yang dipindai oleh API:

  • Jalur induk penagihan: Jalur parent dalam permintaan URL harus menggunakan format projects/project/locations/location. Pasangan project-lokasi tertentu ini digunakan secara eksklusif untuk mengevaluasi kuota penagihan dan batas kecepatan API.

  • Lokasi target: Tentukan secara eksplisit region yang ingin dipindai backend dalam array locations di dalam isi permintaan.

Penyiapan autentikasi

Lakukan inisialisasi variabel lingkungan dengan token akses Google Cloud untuk mengautentikasi perintah curl Anda:

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

Contoh penggunaan

Contoh berikut menggunakan endpoint datalineage.googleapis.com.

Menelusuri silsilah multi-project dan multi-level

Untuk menjalankan penelusuran silsilah mendalam yang melintasi beberapa kedalaman grafik dan memindai di seluruh project yang berbeda, tentukan variabel berikut: Google Cloud

  • Tetapkan limits.maxDepth ke kedalaman penelusuran target Anda (menerima nilai dari 1 hingga 100).

  • Isi array locations dengan wilayah target yang ingin Anda jadikan referensi silang backend (misalnya, ["us", "us-east1"]).

C#

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai Knowledge Catalog menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Knowledge Catalog C# API.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Knowledge Catalog menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Knowledge Catalog Java API.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai Knowledge Catalog menggunakan library klien.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

/**
 * 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan memulai Knowledge Catalog menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Knowledge Catalog Python API.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

# 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan memulai Knowledge Catalog menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Knowledge Catalog Ruby API.

Untuk melakukan autentikasi ke Knowledge Catalog, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk menelusuri silsilah data, gunakan metode searchLineageStreaming.

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

  • PROJECT_ID: project ID Google Cloud Anda yang digunakan untuk penagihan administratif dan evaluasi kuota.
  • LOCATION_ID: lokasi Google Cloud , seperti us-central1.
  • SOURCE_PROJECT_ID: Google Cloud project ID tempat tabel sumber berada.
  • DATASET_ID: ID set data BigQuery.
  • TABLE_ID: ID tabel BigQuery.

Metode HTTP dan URL:

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

Meminta isi 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
  }
}

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

Anda akan melihat respons JSON seperti berikut:

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

Menelusuri beberapa lokasi geografis

Anda dapat membatasi atau memperluas pemindaian grafik silsilah dengan mengubah wilayah geografis yang diteruskan dalam kolom array berulang locations.

Contoh:

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"
}'

Secara default, API akan membiarkan informasi proses tidak disertakan (maxProcessPerLink secara default adalah 0). Untuk mengambil nama resource pipeline yang membuat link data Anda, konfigurasi limits.maxProcessPerLink ke bilangan bulat positif bukan nol.

Contoh:

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
  }
}'

Perilaku respons: Aliran yang dihasilkan mengisi kolom links[].processes dengan pesan proses yang hanya berisi nama resource sistem absolutnya (seperti projects/my-project/locations/us/processes/my-process).

Mengambil detail proses lengkap menggunakan FieldMask

Jika Anda memerlukan metadata struktural lengkap tentang pipeline (seperti displayName, attributes sistem, atau origin eksekusi), bukan hanya nama resource-nya, Anda harus menggunakan FieldMask API:

  1. Berikan nilai selain nol ke limits.maxProcessPerLink.

  2. Tambahkan parameter kueri fields ke jalur URL, dengan menentukan links.processes.process bersama dengan kolom wajib diisi lainnya.

Contoh:

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
  }
}'

Menelusuri silsilah tingkat tabel dan tingkat kolom

Anda dapat menelusuri silsilah tingkat tabel (tingkat aset) dan tingkat kolom (tingkat kolom) dalam satu permintaan dengan memberikan beberapa entitas dalam daftar rootCriteria.entities.entities:

  • Untuk silsilah tingkat tabel, hapus array field.

  • Untuk silsilah tingkat kolom, tentukan satu kolom dalam array field.

Contoh:

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"
     }'

Menggunakan karakter pengganti untuk silsilah tingkat kolom

Untuk menelusuri semua silsilah tingkat kolom yang tersedia untuk tabel tertentu tanpa mencantumkan setiap kolom satu per satu, gunakan karakter pengganti * sebagai satu-satunya nilai dalam array field.

Contoh:

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"
     }'

Memfilter hasil silsilah

Anda dapat mempertajam hasil penelusuran asal-usul dengan menggunakan blok filters di isi permintaan.

Memfilter menurut jenis dependensi

Untuk membatasi hasil ke jenis dependensi tertentu, seperti salinan langsung (EXACT_COPY) atau transformasi seperti pemfilteran dan pengelompokan (OTHER), gunakan filter dependencyTypes.

Contoh:

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"]
       }
     }'

Membatasi ke silsilah hanya tabel

Untuk memastikan bahwa penelusuran hanya menampilkan silsilah tingkat tabel dan sepenuhnya mengecualikan silsilah tingkat kolom, tetapkan filter entitySet ke ENTITIES.

Contoh:

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"
       }
     }'

Memfilter menurut rentang waktu

Anda dapat membatasi hasil penelusuran silsilah ke interval waktu tertentu.

Misalnya, untuk menelusuri data silsilah yang dibuat setelah stempel waktu tertentu, gunakan permintaan berikut:

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"
         }
       }
     }'

Menangani lokasi yang tidak dapat dijangkau (Hasil parsial)

Karena API streaming memindai di seluruh set project dan lokasi yang didistribusikan secara bersamaan, beberapa region jarak jauh mungkin tidak berfungsi untuk sementara, tidak dapat berkomunikasi, atau salah dikonfigurasi selama eksekusi.

Untuk melindungi integritas data, aliran searchLineageStreamingResponse berisi kolom diagnostik khusus yang disebut unreachable:

  • Nama kolom: unreachable (direpresentasikan sebagai string berulang)

  • Format nilai: projects/PROJECT_NUMBER/locations/LOCATION (misalnya, projects/123456789/locations/us-east1)

Langkah berikutnya