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.getdi project tempat link disimpan -
Telusuri silsilah tingkat kolom:
datalineage.events.getFieldsdi project tempat link disimpan -
Mengambil detail lengkap proses pipeline:
datalineage.processes.getpada 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
parentdalam permintaan URL harus menggunakan formatprojects/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
locationsdi 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.maxDepthke kedalaman penelusuran target Anda (menerima nilai dari1hingga100).Isi array
locationsdengan 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.
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.
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.
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.
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.
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 , sepertius-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"
}'
Mengambil nama proses untuk link silsilah
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:
Berikan nilai selain nol ke
limits.maxProcessPerLink.Tambahkan parameter kueri
fieldske jalur URL, dengan menentukanlinks.processes.processbersama 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
Pelajari lebih lanjut penelusuran silsilah multiregion.
Pelajari silsilah data lebih lanjut.
Pelajari lebih lanjut visualisasi asal data.