이 문서에서는 searchLineageStreaming API를 사용하여 다중 수준의 교차 지역 데이터 계보를 조회하는 방법을 설명합니다.
searchLineageStreaming API는 정의된 루트 엔티티 집합에서 시작하여 지정된 방향 (업스트림 또는 다운스트림)으로 너비 우선 검색을 실행하고 통합된 계보 그래프를 실시간 스트리밍 응답으로 반환합니다.
자세한 내용은 멀티 리전 계보 검색 정보를 참고하세요.
주요 기능
searchLineageStreaming API에는 다음 기능이 포함됩니다.
너비 우선 검색: 계보 그래프를 레이어별로 탐색하여 연결된 각 애셋의 깊이를 정확하게 계산합니다.
스트리밍 응답: 백엔드 시스템에서 검색된 하위 그래프와 계보 링크를 반환합니다. 이는 광범위하거나 심층적인 계보 그래프에 매우 효율적이며 요청 시간 초과를 방지합니다.
다중 위치 및 다중 프로젝트 순회: 요청 경로에 하나의 결제 프로젝트만 지정하더라도 필요한 권한이 있으면 API가 여러 Google Cloud 프로젝트와 지리적 위치에서 계보 링크를 자동으로 검색하고 순회합니다.
세분화된 열 수준 계보: 애셋 간 열 수준 종속 항목 검색을 지원합니다.
와일드 카드 조회: 정규화된 이름 (FQN)에
*를 접미사로 추가하여 특정 항목의 모든 열 수준 계보를 가져올 수 있습니다.파이프라인 통계: 계보 링크를 만든 변환 파이프라인 (프로세스)에 관한 메타데이터를 선택적으로 가져옵니다.
시작하기 전에
API에 요청하기 전에 다음 보안 및 환경 기본 요건을 충족해야 합니다.
필요한 역할
데이터 계보 링크를 검색하는 데 필요한 권한을 얻으려면 관리자에게 계보 링크와 프로세스가 저장된 프로젝트에 대한 데이터 계보 뷰어 (roles/datalineage.viewer) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이 사전 정의된 역할에는 데이터 계보 링크를 검색하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
데이터 계보 링크를 검색하려면 다음 권한이 필요합니다.
-
엔티티 수준 계보 검색: 링크가 저장된 프로젝트에 대한
datalineage.events.get권한 -
열 수준 계보 검색:
링크가 저장된 프로젝트에 대한
datalineage.events.getFields권한 -
전체 파이프라인 프로세스 세부정보 가져오기: 프로세스가 저장된 프로젝트에 대한
datalineage.processes.get권한
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
리소스 범위 지정
API 요청을 구성할 때는 관리 결제에 사용되는 리소스와 API에서 실제로 스캔하는 위치를 구분해야 합니다.
결제 상위 경로: URL 요청의
parent경로는projects/project/locations/location형식을 사용해야 합니다. 이 특정 프로젝트-위치 쌍은 결제 할당량 및 API 비율 제한을 평가하는 데만 사용됩니다.타겟 위치: 요청 본문 내
locations배열에서 백엔드가 검색할 리전을 명시적으로 정의합니다.
인증 설정
Google Cloud 액세스 토큰으로 환경 변수를 초기화하여 curl 명령어를 인증합니다.
export ACCESS_TOKEN=$(gcloud auth print-access-token)
사용 예시
다음 예시에서는 datalineage.googleapis.com 엔드포인트를 사용합니다.
다중 수준, 다중 프로젝트 계보 검색
그래프의 여러 깊이를 탐색하고 서로 다른 Google Cloud 프로젝트를 스캔하는 심층 계보 검색을 실행하려면 다음 변수를 정의합니다.
limits.maxDepth을 타겟 순회 깊이로 설정합니다 (1~100값 허용).백엔드에서 교차 참조할 대상 리전 (예:
["us", "us-east1"])으로locations배열을 채웁니다.
C#
C#
이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 Knowledge Catalog C# API 참고 문서를 참고하세요.
Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
자바
Java
이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Knowledge Catalog Java API 참고 문서를 참고하세요.
Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Node.js
Java
이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요.
Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Python
Python
이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 Knowledge Catalog Python API 참고 문서를 참고하세요.
Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
Ruby
Ruby
이 샘플을 사용해 보기 전에 Knowledge Catalog 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 Knowledge Catalog Ruby API 참고 문서를 참고하세요.
Knowledge Catalog에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참조하세요.
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를 사용해야 합니다.
limits.maxProcessPerLink에 0이 아닌 값을 제공합니다.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 목록에 여러 항목을 제공하여 단일 요청에서 테이블 수준 (애셋 수준) 및 열 수준 (필드 수준) 계보를 모두 검색할 수 있습니다.
표 수준 계보의 경우
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)
다음 단계
멀티 리전 계보 검색에 대해 자세히 알아보세요.
데이터 계보에 대해 자세히 알아보세요.
계보 시각화에 대해 자세히 알아보세요.