Menelusuri silsilah multi-region menggunakan otomatisasi sisi server

Dokumen ini menjelaskan cara mencari silsilah data lintas region dan multi-level menggunakan searchLineageStreaming API.

The searchLineageStreaming API melakukan penelusuran luas pertama dalam arah yang ditentukan (hulu atau hilir) yang dimulai dari kumpulan 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 luas pertama: Melakukan traversal grafik silsilah lapis demi lapis, menghitung kedalaman setiap aset yang terhubung secara akurat.

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

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

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

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

  • 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 yang telah ditentukan 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 entitas: datalineage.events.get di project tempat link disimpan
  • Menelusuri silsilah tingkat kolom: datalineage.events.getFields di project tempat link disimpan
  • Mengambil detail proses pipeline lengkap: datalineage.processes.get di 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 hanya digunakan untuk mengevaluasi kuota penagihan dan batas frekuensi API.

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

Penyiapan autentikasi

Lakukan inisialisasi variabel lingkungan dengan a Google Cloud token akses 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-level dan multi-project

Untuk menjalankan penelusuran silsilah mendalam yang melakukan traversal di beberapa kedalaman grafik dan memindai di berbagai Google Cloud project, tentukan variabel berikut:

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

  • Isi array locations dengan region target yang ingin Anda referensikan oleh backend (misalnya, ["us", "us-east1"]).

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", "us-east1", "us-central1"],
  "rootCriteria": {
    "entities": {
      "entities": [{
        "fullyQualifiedName": "bigquery:project-prod.dataset.source_table"
      }]
    }
  },
  "direction": "DOWNSTREAM",
  "limits": {
    "maxDepth": 10,
    "maxResults": 5000
  }
}'

Menelusuri beberapa lokasi geografis

Anda dapat membatasi atau memperluas pemindaian grafik silsilah dengan mengubah region geografis yang diteruskan di 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 mengabaikan informasi proses (maxProcessPerLink ditetapkan ke 0 secara default). 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: Streaming yang dihasilkan akan 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 bukan nol ke limits.maxProcessPerLink.

  2. Tambahkan parameter kueri fields ke jalur URL, yang menentukan links.processes.process beserta kolom lain yang diperlukan.

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 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 mempersempit hasil penelusuran silsilah 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 khusus 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 sebagian)

Karena API streaming memindai kumpulan project dan lokasi terdistribusi secara bersamaan, beberapa region jarak jauh mungkin tidak berfungsi, tidak dapat berkomunikasi, atau salah konfigurasi selama eksekusi.

Untuk melindungi integritas data, streaming 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