2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

OpenLineage와 통합

이 문서에서는 OpenLineage를 Knowledge Catalog (이전의 Dataplex Universal Catalog)와 통합하여 외부 시스템에서 데이터 계보를 가져오고 시각화하는 방법을 설명합니다. Knowledge Catalog를 OpenLineage 소비자로 작동함으로써 ProcessOpenLineageRunEvent REST API를 사용하여 서비스의 기본 제공 계보와 함께 커스텀 파이프라인 계보를 통합할 수 있습니다. Google Cloud

개요

OpenLineage는 데이터 계보 정보를 수집하고 분석할 수 있는 개방형 플랫폼입니다. 계보 데이터의 개방형 표준을 사용하는 OpenLineage는 OpenLineage API를 통해 실행, 작업, 데이터 세트를 보고하는 데이터 파이프라인 구성요소에서 계보 이벤트를 캡처합니다.

Data Lineage API를 통해 OpenLineage 이벤트를 가져와 BigQuery, Managed Service for Apache Airflow, Cloud Data Fusion, Managed Service for Apache Spark와 같은 Google Cloud 서비스의 계보 정보와 함께 Knowledge Catalog 웹 인터페이스에 표시할 수 있습니다.

OpenLineage 사양을 사용하는 OpenLineage 이벤트를 가져오려면 OpenLineage 사양을 사용하고 ProcessOpenLineageRunEvent REST API 메서드를 사용하고 OpenLineage 패싯을 Data Lineage API 속성에 매핑합니다.

OpenLineage 통합 제한사항

지원되는 버전: Data Lineage API는 OpenLineage 메이저 버전 1을 지원합니다.
API 작업: Data Lineage API 엔드포인트 ProcessOpenLineageRunEvent 는 OpenLineage 메시지의 프로듀서 가 아닌 소비자 역할만 합니다. 이 API를 사용하면 OpenLineage를 준수하는 도구나 시스템에서 생성된 계보 정보를 Knowledge Catalog로 전송할 수 있습니다. Managed Service for Apache Spark, Managed Airflow와 같은 일부 Google Cloud 서비스에는 이 이벤트를 엔드포인트로 보내 해당 서비스의 계보를 자동으로 캡처할 수 있는 기본 제공 OpenLineage 생성자가 포함되어 있습니다.
지원되지 않는 기능: Data Lineage API는 다음을 지원하지 않습니다.
- 메시지 형식이 변경된 모든 이후 OpenLineage 출시 버전
- DatasetEvent
- JobEvent
메시지 크기: 단일 메시지 최대 크기는 5MB입니다.
이름 길이: 입력 및 출력의 각 정규화된 이름 길이는 4,000자(영문 기준)로 제한됩니다.
링크 제한: 링크 는 이벤트별로 그룹화되며 이벤트당 최대 100개의 링크가 있습니다. 테이블 수준 링크의 최대 집계 수는 1,000개입니다. 메시지에 1, 500개가 넘는 열 수준 링크가 포함되어 있으면 열 수준 정보가 건너뜁니다.
그래프 범위: Knowledge Catalog는 계보 이벤트의 입력과 출력을 보여주는 각 작업 실행의 계보 그래프를 표시합니다. Spark 스테이지와 같은 하위 프로세스는 지원되지 않습니다.

OpenLineage 패싯 속성 매핑

OpenLineage 매핑에 대한 자세한 내용은 OpenLineage 매핑을 참고하세요.

OpenLineage 이벤트 가져오기

아직 OpenLineage를 설정하지 않았다면 시작하기를 참고하세요.

OpenLineage 이벤트를 Knowledge Catalog로 가져오려면 API 메서드 ProcessOpenLineageRunEvent를 호출합니다.

C#

이 샘플을 사용해 보기 전에 C# Data Lineage 빠른 시작: 클라이언트 라이브러리 사용의 설정 안내를 따르세요. 자세한 내용은 Data Lineage C# API 참조 문서를 참고하세요.

Data Lineage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참고하세요.

using Google.Cloud.DataCatalog.Lineage.V1;
using Google.Protobuf.WellKnownTypes;

public sealed partial class GeneratedLineageClientSnippets
{
    /// <summary>Snippet for ProcessOpenLineageRunEvent</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 void ProcessOpenLineageRunEventRequestObject()
    {
        // Create client
        LineageClient lineageClient = LineageClient.Create();
        // Initialize request argument(s)
        ProcessOpenLineageRunEventRequest request = new ProcessOpenLineageRunEventRequest
        {
            Parent = "",
            OpenLineage = new Struct(),
        };
        // Make the request
        ProcessOpenLineageRunEventResponse response = lineageClient.ProcessOpenLineageRunEvent(request);
    }
}

Go

이 샘플을 사용해 보기 전에 Go 설정 안내를 따르세요. Data Lineage 빠른 시작: 클라이언트 라이브러리 사용 자세한 내용은 Data Lineage Go API 참조 문서를 참고하세요.

Data Lineage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참고하세요.


//go:build examples

package main

import (
	"context"

	lineage "cloud.google.com/go/datacatalog/lineage/apiv1"
	lineagepb "cloud.google.com/go/datacatalog/lineage/apiv1/lineagepb"
)

func main() {
	ctx := context.Background()
	// 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://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := lineage.NewClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &lineagepb.ProcessOpenLineageRunEventRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/datacatalog/lineage/apiv1/lineagepb#ProcessOpenLineageRunEventRequest.
	}
	resp, err := c.ProcessOpenLineageRunEvent(ctx, req)
	if err != nil {
		// TODO: Handle error.
	}
	// TODO: Use resp.
	_ = resp
}

자바

Java

이 샘플을 사용해 보기 전에 Java 설정 안내를 따르세요. Data Lineage 빠른 시작: 클라이언트 라이브러리 사용 자세한 내용은 Data Lineage Java API 참조 문서를 참고하세요.

Data Lineage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참고하세요.

import com.google.cloud.datacatalog.lineage.v1.LineageClient;
import com.google.cloud.datacatalog.lineage.v1.ProcessOpenLineageRunEventRequest;
import com.google.cloud.datacatalog.lineage.v1.ProcessOpenLineageRunEventResponse;
import com.google.protobuf.Struct;

public class SyncProcessOpenLineageRunEvent {

  public static void main(String[] args) throws Exception {
    syncProcessOpenLineageRunEvent();
  }

  public static void syncProcessOpenLineageRunEvent() 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()) {
      ProcessOpenLineageRunEventRequest request =
          ProcessOpenLineageRunEventRequest.newBuilder()
              .setParent("parent-995424086")
              .setOpenLineage(Struct.newBuilder().build())
              .setRequestId("requestId693933066")
              .build();
      ProcessOpenLineageRunEventResponse response =
          lineageClient.processOpenLineageRunEvent(request);
    }
  }
}

Python

이 샘플을 사용해 보기 전에 Python 설정 안내를 따르세요. Data Lineage 빠른 시작: 클라이언트 라이브러리 사용 자세한 내용은 Data Lineage Python API 참조 문서를 참고하세요.

Data Lineage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참고하세요.

# 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_process_open_lineage_run_event():
    # Create a client
    client = datacatalog_lineage_v1.LineageClient()

    # Initialize request argument(s)
    request = datacatalog_lineage_v1.ProcessOpenLineageRunEventRequest(
        parent="parent_value",
    )

    # Make the request
    response = client.process_open_lineage_run_event(request=request)

    # Handle the response
    print(response)

Ruby

이 샘플을 사용해 보기 전에 Ruby 설정 안내를 따르세요. Data Lineage 빠른 시작: 클라이언트 라이브러리 사용 자세한 내용은 Data Lineage Ruby API 참조 문서를 참고하세요.

Data Lineage에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 로컬 개발 환경의 인증 설정을 참고하세요.

require "google/cloud/data_catalog/lineage/v1"

##
# Snippet for the process_open_lineage_run_event 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#process_open_lineage_run_event.
#
def process_open_lineage_run_event
  # 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::ProcessOpenLineageRunEventRequest.new

  # Call the process_open_lineage_run_event method.
  result = client.process_open_lineage_run_event request

  # The returned object is of type Google::Cloud::DataCatalog::Lineage::V1::ProcessOpenLineageRunEventResponse.
  p result
end

REST

OpenLineage 이벤트를 가져오려면 processOpenLineageRunEvent 메서드를 사용합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
LOCATION_ID: Google Cloud 위치(예: us-central1)

HTTP 메서드 및 URL:

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

JSON 요청 본문:

{
  "eventTime": "2023-04-04T13:21:16.098Z",
  "eventType": "COMPLETE",
  "inputs": [
    {
      "name": "somename",
      "namespace": "customnamespace"
    }
  ],
  "job": {
    "name": "somename",
    "namespace": "customnamespace"
  },
  "outputs": [
    {
      "name": "somename",
      "namespace": "customnamespace"
    }
  ],
  "producer": "someproducer",
  "run": {
    "runId": "somerunid"
  },
  "schemaURL": "https://openlineage.io/spec/1-0-5/OpenLineage.json#/$defs/RunEvent"
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:processOpenLineageRunEvent"

PowerShell(Windows)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datalineage.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID:processOpenLineageRunEvent" | Select-Object -Expand Content

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "process": "projects/my-project/locations/us-central1/processes/my-process",
  "run": "projects/my-project/locations/us-central1/processes/my-process/runs/my-run",
  "lineageEvents": [
    "projects/my-project/locations/us-central1/processes/my-process/runs/my-run/lineageEvents/my-lineage-event"
  ]
}

OpenLineage 메시지 전송 도구

Data Lineage API로 이벤트를 간단하게 전송하려면 다양한 도구와 라이브러리를 사용하면 됩니다.

Data Lineage용 Google Cloud 클라이언트 라이브러리: Google은 Data Lineage API와 프로그래매틱 방식으로 상호작용할 수 있는 클라이언트 라이브러리를 제공합니다. 설치 안내는 클라이언트 라이브러리를 참고하세요.
Google Cloud Java 프로듀서 라이브러리: Google은 OpenLineage 이벤트를 구성하고 Data Lineage API로 전송하는 데 도움이 되는 오픈소스 Java 라이브러리를 제공합니다. 자세한 내용은 데이터 계보용 프로듀서 Java 라이브러리가 이제 오픈소스입니다 블로그 게시물을 참고하세요. 이 라이브러리는 GitHub 및 Maven에서 제공됩니다.
OpenLineage GCP 전송: Java 기반 OpenLineage 프로듀서의 경우 전용 GcpLineage 전송을 사용할 수 있습니다. Data Lineage API로 이벤트를 전송하는 데 필요한 코드를 최소화하여 Data Lineage API와의 통합을 간소화합니다. GcpLineageTransport는 Airflow, Spark, Flink와 같은 기존 OpenLineage 프로듀서의 이벤트 싱크로 구성될 수 있습니다. 자세한 내용과 예시는 GcpLineage를 참고하세요.

OpenLineage의 정보 분석

가져온 OpenLineage 이벤트를 분석하려면 Knowledge Catalog UI에서 계보 그래프 보기를 참고하세요.

저장된 OpenLineage 패싯 데이터

Data Lineage API는 OpenLineage 메시지의 모든 패싯 데이터를 저장하지 않습니다. Data Lineage API는 다음 패싯 필드를 저장합니다.

spark_version
- openlineage-spark-version
- spark-version
모든 spark.logicalPlan.*
environment-properties(커스텀 Google Cloud 계보 패싯)
- origin.sourcetype 및 origin.name
- spark.app.id
- spark.app.name
- spark.batch.id
- spark.batch.uuid
- spark.cluster.name
- spark.cluster.region
- spark.job.id
- spark.job.uuid
- spark.project.id
- spark.query.node.name
- spark.session.id
- spark.session.uuid

Data Lineage API는 다음 정보를 저장합니다.

eventTime
run.runId
job.namespace
job.name

다음 단계

Managed Service for Apache Spark 및 Hive 데이터 계보 통합을 사용하여 데이터 계보에 대해 자세히 알아보세요.

대화형 실습에서 사용해 보기: 데이터 계보 및 OpenLineage를 사용하여 데이터 업데이트 캡처 및 탐색

OpenLineage와 통합 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

개요

OpenLineage 통합 제한사항

OpenLineage 패싯 속성 매핑

OpenLineage 이벤트 가져오기

C#

C#

Go

Go

자바

Java

Python

Python

Ruby

Ruby

REST

cURL(Linux, macOS, Cloud Shell)

PowerShell(Windows)

OpenLineage 메시지 전송 도구

OpenLineage의 정보 분석

저장된 OpenLineage 패싯 데이터

다음 단계

OpenLineage와 통합