생성된 lakeFS SDK 사용하기

생성된(generated) Python SDK는 서버가 공개하는 OpenAPI 스펙에서 lakeFS API에 직접 접근하게 해줘요. 이 저수준(low-level) SDK는 API 상호작용을 완전히 제어할 수 있게 해주며, High-Level SDK가 다루지 않는 기능이 필요하거나 API를 직접 다루는 쪽을 선호할 때 유용해요.

각 lakeFS 에디션이 자체 API 서피스를 제공하기 때문에, 생성된 SDK는 에디션별로 하나의 패키지로 배포돼요. 두 패키지 모두 같은 OpenAPI 제너레이터에서 나오고 동일한 클라이언트 형태를 공유하기 때문에, 설치할 패키지는 코드를 어떻게 작성하고 싶은지가 아니라 실행 중인 lakeFS가 무엇인지에 따라 정해져요.

출처: 생성된 lakeFS SDK 사용하기

본문

언제 사용하나요?

다음 경우에 생성된 SDK를 사용해요:

• 요청을 완전히 제어하는 저수준 API 접근이 필요할 때

• High-Level SDK에서는 사용할 수 없는 기능이 필요할 때

• 직접 API 상호작용 패턴을 선호할 때

• 모든 API 엔드포인트에 프로그래매틱으로 접근해야 할 때

Info

대부분의 일반적인 lakeFS 연산(브랜치, 태그, 커밋, 객체)에는 더 파이썬다운 인터페이스를 제공하는 High-Level SDK가 권장돼요.

lakeFS 에디션과 버전에 맞는 패키지 고르기

먼저 접속하려는 lakeFS를 확인하세요. 실행 중인 에디션이 어떤 패키지로 그 API를 기술할 수 있는지 결정해요:

Package	Use it against	Import name	Python	API reference
lakefs-enterprise-sdk	lakeFS Enterprise, self-managed or hosted	lakefs_enterprise_sdk	3.10 and above	pydocs-enterprise-sdk.lakefs.io
lakefs-sdk	lakeFS Community	lakefs_sdk	3.7 and above	pydocs-sdk.lakefs.io

에디션들이 공유하는 부분에 대해서는 두 패키지가 모듈 이름만 다른 동일한 클라이언트예요. 그래서 이 문서의 모든 예시에는 Enterprise 탭과 Community 탭이 있고, 둘의 유일한 차이는 그 모듈 이름이에요. Enterprise 패키지는 여기에 lakeFS Enterprise만 제공하는 API 그룹을 추가하는데, 이는 Enterprise 전용 API 그룹 섹션에서 다뤄요. 자신의 에디션에 맞는 탭을 한 번 고르면 이 페이지의 다른 모든 탭 블록도 그 선택을 따라가요.

lakefs-enterprise-sdk는 lakeFS Enterprise에서 사용할 수 있으며, 사용은 Enterprise SDK 라이선스의 규정을 따라요. 무료 체험을 시작해 보세요.

패키지 버전을 lakeFS 버전에 맞추기

각 패키지는 자신의 에디션이 공개하는 OpenAPI 스펙에서 해당 에디션의 모든 릴리스마다 재생성되고, 버전도 그에 맞춰 매겨져요. 따라서 새 기능은 그것을 도입한 변형(variant)과 버전의 생성 SDK에 도달해요. 특정 lakeFS Enterprise 릴리스에서 추가된 엔드포인트는 같은 버전의 lakefs-enterprise-sdk에 나타나고, 두 에디션은 서로의 버전 라인을 맞추지 않고 각자 진행해요.

서버에 해당하는 패키지 버전을 설치하고, requirements에 버전을 고정(pin)하세요. 그래야 무관한 업그레이드가 실행 중인 서버 밑에서 클라이언트를 바꿔놓는 일이 없어요:

lakeFS Enterprise

pip install "lakefs-enterprise-sdk==<your lakeFS Enterprise version>"

lakeFS Community

pip install "lakefs-sdk==<your lakeFS Community version>"

서버보다 오래된 클라이언트는 최신 메서드가 없을 뿐이고, 그 기능이 필요 없다면 무해해요. 반면 서버보다 새로운 클라이언트는 주의할 케이스예요. 내 버전이 아직 제공하지 않는 엔드포인트용으로 생성된 메서드가 Python에는 존재하고, 호출 시점에만 실패해요. lakeFS Community에 Enterprise 전용 그룹을 호출하는 것과 같은 방식이죠. 어떤 호출이 이유 없이 실패한다면, 무엇보다 먼저 패키지 버전과 서버 버전을 비교해 보세요. 어떤 버전이 특정 기능을 도입했는지는 lakeFS Enterprise 릴리스 노트와, Community 패키지의 경우 lakeFS Community releases에 기록돼 있어요.

한 환경에는 두 패키지 중 하나만 설치하세요. 서로 다른 최상위 모듈을 선언하기 때문에 기술적으로는 나란히 둘 수 있지만, 양쪽의 클라이언트를 함께 들고 있으면 어떤 호출이 어느 API 서피스에 속하는지 알기 어려워져요.

설치

에디션에 맞는 패키지를 pip으로 설치해요:

lakeFS Enterprise

pip install lakefs-enterprise-sdk

또는 최신 버전으로 업그레이드:

pip install --upgrade lakefs-enterprise-sdk

lakeFS Community

pip install lakefs-sdk

또는 최신 버전으로 업그레이드:

pip install --upgrade lakefs-sdk

기본 설정

SDK 초기화

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.rest import ApiException

# Configure the API client
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

# Create an API client
api_client = lakefs_enterprise_sdk.ApiClient(configuration)

lakeFS Community

import lakefs_sdk
from lakefs_sdk.rest import ApiException

# Configure the API client
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

# Create an API client
api_client = lakefs_sdk.ApiClient(configuration)

인증 옵션

SDK는 여러 인증 방식을 지원해요:

lakeFS Enterprise

import lakefs_enterprise_sdk
import os

# HTTP Basic Authentication
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username=os.environ["LAKEFS_ACCESS_KEY"],
    password=os.environ["LAKEFS_SECRET_KEY"]
)

# JWT Bearer Token
configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    access_token=os.environ["LAKEFS_TOKEN"]
)

api_client = lakefs_enterprise_sdk.ApiClient(configuration)

lakeFS Community

import lakefs_sdk
import os

# HTTP Basic Authentication
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username=os.environ["LAKEFS_ACCESS_KEY"],
    password=os.environ["LAKEFS_SECRET_KEY"]
)

# JWT Bearer Token
configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    access_token=os.environ["LAKEFS_TOKEN"]
)

api_client = lakefs_sdk.ApiClient(configuration)

간단한 예제

저장소 목록 조회

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
        for repo in response.results:
            print(f"Repository: {repo.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

lakeFS Community

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
        for repo in response.results:
            print(f"Repository: {repo.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

저장소 상세 정보 조회

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)
    repository = "my-repo"

    try:
        repo = api_instance.get_repository(repository)
        print(f"Repository: {repo.id}")
        print(f"Storage: {repo.storage_namespace}")
        print(f"Created: {repo.creation_date}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

lakeFS Community

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)
    repository = "my-repo"

    try:
        repo = api_instance.get_repository(repository)
        print(f"Repository: {repo.id}")
        print(f"Storage: {repo.storage_namespace}")
        print(f"Created: {repo.creation_date}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

브랜치 목록 조회

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.branches_api import BranchesApi

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = BranchesApi(api_client)
    repository = "my-repo"

    try:
        response = api_instance.list_branches(repository)
        for branch in response.results:
            print(f"Branch: {branch.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

lakeFS Community

import lakefs_sdk
from lakefs_sdk.api.branches_api import BranchesApi

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = BranchesApi(api_client)
    repository = "my-repo"

    try:
        response = api_instance.list_branches(repository)
        for branch in response.results:
            print(f"Branch: {branch.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

커밋 생성

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.commits_api import CommitsApi
from lakefs_enterprise_sdk.models.commit_creation import CommitCreation

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = CommitsApi(api_client)
    repository = "my-repo"
    branch = "main"

    commit_creation = CommitCreation(
        message="My commit message",
        metadata={"author": "data-team"}
    )

    try:
        commit = api_instance.commit(repository, branch, commit_creation)
        print(f"Committed: {commit.id}")
    except lakefs_enterprise_sdk.ApiException as e:
        print(f"Error: {e}")

lakeFS Community

import lakefs_sdk
from lakefs_sdk.api.commits_api import CommitsApi
from lakefs_sdk.models.commit_creation import CommitCreation

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = CommitsApi(api_client)
    repository = "my-repo"
    branch = "main"

    commit_creation = CommitCreation(
        message="My commit message",
        metadata={"author": "data-team"}
    )

    try:
        commit = api_instance.commit(repository, branch, commit_creation)
        print(f"Committed: {commit.id}")
    except lakefs_sdk.ApiException as e:
        print(f"Error: {e}")

에러 처리

ApiException으로 API 에러를 처리해요:

lakeFS Enterprise

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.repositories_api import RepositoriesApi
from lakefs_enterprise_sdk.rest import ApiException

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
    except ApiException as e:
        if e.status == 401:
            print("Unauthorized - check credentials")
        elif e.status == 404:
            print("Resource not found")
        else:
            print(f"API Error: {e.reason}")

lakeFS Community

import lakefs_sdk
from lakefs_sdk.api.repositories_api import RepositoriesApi
from lakefs_sdk.rest import ApiException

configuration = lakefs_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_sdk.ApiClient(configuration) as api_client:
    api_instance = RepositoriesApi(api_client)

    try:
        response = api_instance.list_repositories()
    except ApiException as e:
        if e.status == 401:
            print("Unauthorized - check credentials")
        elif e.status == 404:
            print("Resource not found")
        else:
            print(f"API Error: {e.reason}")

Enterprise 전용 API 그룹

lakeFS Enterprise에서 사용할 수 있어요. 무료 체험을 시작해 보세요.

ActionsApi, AuthApi, BranchesApi, CommitsApi, ObjectsApi, PullsApi, RefsApi, RepositoriesApi, StagingApi, TagsApi 같은 공유 API 클래스와 함께, lakefs_enterprise_sdk 모듈은 Community 패키지에 대응물이 없는 아래 그룹을 노출해요:

API class	Covers
DatasetsApi	The named, versioned views described under Datasets, including their versions, metadata keys and pull requests
TenantsApi	Tenant management

이 그룹은 Enterprise 탭에만 나타나요. Community 패키지는 해당 클래스를 노출하지도 않고, 그런 API를 제공하는 서버와 통신하지도 않기 때문이에요. 호출 방식은 다른 API 클래스와 같은 패턴이고, 설치 환경의 데이터셋을 나열하는 것도 평범한 페이징 호출처럼 읽혀요:

import lakefs_enterprise_sdk
from lakefs_enterprise_sdk.api.datasets_api import DatasetsApi
from lakefs_enterprise_sdk.rest import ApiException

configuration = lakefs_enterprise_sdk.Configuration(
    host="https://example.lakefs.io/api/v1",
    username="your-access-key",
    password="your-secret-key"
)

with lakefs_enterprise_sdk.ApiClient(configuration) as api_client:
    api_instance = DatasetsApi(api_client)

    try:
        response = api_instance.list_datasets(amount=100)
        for dataset in response.results:
            print(f"Dataset: {dataset.id}")
    except ApiException as e:
        print(f"Error: {e}")

전체 API 레퍼런스

완전한 API 문서와 메서드 시그니처는 설치한 패키지의 레퍼런스를 참고하세요:

• Enterprise Generated SDK API Reference - Enterprise 전용 API 그룹을 포함해 lakefs-enterprise-sdk의 API 클래스, 메서드, 모델 전체 문서

• Generated SDK API Reference - lakefs-sdk의 동일한 내용

더 알아보기 (Learn more)

공식 문서의 원문은 https://docs.lakefs.io/reference/python/generated-sdk/ 에서 확인할 수 있어요.