Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

서버 측 자동화를 사용하여 멀티 리전 계보 검색

이 문서에서는 searchLineageStreaming API를 사용하여 다중 수준의 교차 리전 데이터 계보를 조회하는 방법을 설명합니다.

searchLineageStreaming API는 정의된 루트 항목 집합에서 시작하여 지정된 방향 (업스트림 또는 다운스트림)으로 너비 우선 검색을 실행하고 통합된 계보 그래프를 실시간 스트리밍 응답으로 반환합니다.

자세한 내용은 다중 리전 계보 검색 정보를 참조하세요.

주요 기능

searchLineageStreaming API에는 다음과 같은 기능이 포함되어 있습니다.

너비 우선 검색: 계보 그래프를 레이어별로 탐색하여 연결된 각 애셋의 깊이를 정확하게 계산합니다.
스트리밍 응답: 백엔드 시스템에서 하위 그래프와 계보 링크를 발견하면 이를 반환합니다. 이는 광범위하거나 심층적인 계보 그래프에 매우 효율적이며 요청 시간 초과를 방지합니다.
다중 위치 및 다중 프로젝트 탐색: 요청 경로에 결제 프로젝트를 하나만 지정하더라도 필요한 권한이 있는 경우 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를 대상 탐색 깊이로 설정합니다 (1 에서 100까지의 값을 허용함).
백엔드에서 교차 참조할 대상 리전으로 locations 배열을 채웁니다 (예: ["us", "us-east1"]).

예를 들면 다음과 같습니다.

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

여러 지리적 위치 검색

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이 아닌 값을 제공합니다.
필요한 다른 필드와 함께 links.processes.process를 지정하여 fields 쿼리 매개변수를 URL 경로에 추가합니다.

예를 들면 다음과 같습니다.

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)

다음 단계

다중 리전 계보 검색에 대해 자세히 알아봅니다 .
데이터 계보에 대해 자세히 알아봅니다 .
계보 시각화에 대해 자세히 알아봅니다.

서버 측 자동화를 사용하여 멀티 리전 계보 검색 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

주요 기능

시작하기 전에

필요한 역할

필수 권한

리소스 범위 지정

인증 설정

사용 예시

다중 수준, 다중 프로젝트 계보 검색

여러 지리적 위치 검색

계보 링크의 프로세스 이름 검색

FieldMask를 사용하여 전체 프로세스 세부정보 검색

테이블 수준 및 열 수준 계보 모두 검색

열 수준 계보에 와일드 카드 사용

계보 결과 필터링

종속성 유형별로 필터링

테이블 전용 계보로 제한

기간으로 필터링

연결할 수 없는 위치 처리 (부분 결과)

다음 단계

서버 측 자동화를 사용하여 멀티 리전 계보 검색