scpv2-sdk

Samsung SDS SCP (Samsung Cloud Platform) Python SDK.
boto3와 유사한 개발자 경험을 제공합니다.

⚠️ 비공식 프로젝트 안내

이 SDK는 개인이 독립적으로 제작한 비공식 오픈소스 프로젝트입니다. Samsung SDS 또는 SCP(Samsung Cloud Platform)의 공식 배포판이 아니며, 두 회사와 어떠한 관계도 없습니다.

본 소프트웨어는 "있는 그대로(AS IS)" 제공되며, 사용으로 인해 발생하는 어떠한 손해·장애·데이터 손실에 대해서도 제작자는 책임을 지지 않습니다.

---

Requirements

• Python 3.10 이상
• requests 2.28 이상

---

Installation

pip install scpv2-sdk

---

Credentials 설정

자격증명은 아래 순서로 자동 탐색합니다.

1. 명시적 파라미터

import scpv2

sess = scpv2.Session(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
)

2. 환경변수

export SCP_ACCESS_KEY="YOUR_ACCESS_KEY"
export SCP_SECRET_KEY="YOUR_SECRET_KEY"
export SCP_REGION="kr-west1"        # 선택
export SCP_ENVIRONMENT="e"          # 선택

sess = scpv2.Session()  # 환경변수 자동 탐색

3. Credential 파일 (~/.scpconf/)

~/.scpconf/config.json — 엔드포인트 및 리전 설정

{
    "auth-url":       "https://iam.dev2.samsungsdscloud.com/v1",
    "default-region": "kr-west1"
}

~/.scpconf/credentials.json — 자격증명

{
    "access-key": "YOUR_ACCESS_KEY",
    "secret-key": "YOUR_SECRET_KEY"
}

sess = scpv2.Session()  # ~/.scpconf/ 자동 탐색

---

Basic Usage

Session

import scpv2

sess = scpv2.Session(
    access_key="YOUR_ACCESS_KEY",
    secret_key="YOUR_SECRET_KEY",
    region="kr-west1",      # 기본값: kr-west1
    environment="e",        # 기본값: e
    language="ko-KR",       # 기본값: ko-KR
)

Client (저수준 API)

IDE 자동완성을 활용하려면 타입 힌트를 명시하는 것을 권장합니다.

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from scpv2.stubs.vpc_client import VpcClient
    from scpv2.stubs.subnet_client import SubnetClient

# 타입 힌트를 지정하면 IDE에서 해당 서비스 메서드만 자동완성됩니다
vpc_client: VpcClient = sess.client("vpc")

# VPC 목록 조회
result = vpc_client.list_vpcs(size=20, page=0)
print(result["vpcs"])

# VPC 생성
vpc_client.create_vpc(
    name="my-vpc",
    cidr="10.0.0.0/24",
    description="My first VPC",
)

# VPC 삭제
vpc_client.delete_vpc(vpc_id="VPC_ID")

# 다른 서비스도 동일하게 타입 힌트 지정
subnet_client: SubnetClient = sess.client("subnet")
result = subnet_client.list_subnets(vpc_id="VPC_ID")

Resource (고수준 OOP API)

from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from scpv2.stubs.vpc_resource import VpcResource

vpc: VpcResource = sess.resource("vpc")

# client 메서드를 의미있는 이름으로 접근
result = vpc.list()
vpc.create(name="my-vpc", cidr="10.0.0.0/24")
vpc.delete(vpc_id="VPC_ID")

---

Paginator

대량의 결과를 페이지 단위로 자동 순회합니다.

vpc_client = sess.client("vpc")
paginator = vpc_client.get_paginator("list_vpcs")

# 페이지 단위로 순회
for page in paginator.paginate(size=10):
    for vpc in page["vpcs"]:
        print(vpc["name"])

# 전체 결과를 한 번에 수집
result = paginator.paginate(size=10).build_full_result()
all_vpcs = result["vpcs"]

---

Waiter

리소스가 특정 상태가 될 때까지 자동으로 폴링합니다.

vpc_client = sess.client("vpc")

# VPC가 ACTIVE 상태가 될 때까지 대기 (5초 간격, 최대 20회)
waiter = vpc_client.get_waiter("vpc_active")
waiter.wait(id="VPC_ID")
print("VPC가 활성화됐습니다.")

---

Collection

Resource에서 자동 페이지네이션을 지원하는 컬렉션 인터페이스입니다.

vpc = sess.resource("vpc")

# 전체 순회
for v in vpc.vpcs.all():
    print(v["name"])

# 필터 적용
for v in vpc.vpcs.filter(state="ACTIVE"):
    print(v)

# 페이지 크기 지정
for v in vpc.vpcs.page_size(50):
    print(v)

# 처음 N개만
first_5 = vpc.vpcs.limit(5)

---

Error Handling

import scpv2

sess = scpv2.Session()
vpc_client = sess.client("vpc")

try:
    vpc_client.delete_vpc(vpc_id="INVALID_ID")

except scpv2.ClientError as e:
    # API가 에러 응답을 반환한 경우
    print(e.response["code"])       # 에러 코드
    print(e.response["message"])    # 에러 메시지
    print(e.operation_name)         # "delete_vpc"

except scpv2.ValidationError as e:
    # 파라미터 유효성 검사 실패 (API 호출 전 클라이언트 측)
    print(e)

except scpv2.CredentialError as e:
    # 자격증명을 찾을 수 없는 경우
    print(e)

---

ResponseMetadata

모든 API 응답에 ResponseMetadata가 포함됩니다.

result = vpc_client.list_vpcs()

meta = result["ResponseMetadata"]
print(meta["HTTPStatusCode"])   # 200
print(meta["RequestId"])        # 요청 ID
print(meta["RetryAttempts"])    # 실제 재시도 횟수

---

Retry 설정

import scpv2
from scpv2 import RetryConfig

sess = scpv2.Session(
    retry_config=RetryConfig(
        max_attempts=5,     # 최대 시도 횟수 (기본값: 3)
        mode="standard",    # "standard" (지수 백오프) | "legacy" (1초 고정)
    )
)

재시도 대상 HTTP 상태 코드: 429, 500, 502, 503, 504

---

Available Services

현재 207개 서비스가 등록되어 있습니다. 대표 서비스는 다음과 같습니다.

service_name	설명
"vpc"	VPC 생성 / 조회 / 수정 / 삭제
"subnet"	서브넷 CRUD 및 VIP 관리
"virtualserver"	가상 서버 목록 / 상세 / 생성 / 시작 / 중지 등
"keypair"	키페어 목록 조회 / 생성
"loadbalancer"	로드밸런서 CRUD
"hosted_zone"	DNS 호스팅 존 관리
"security_group"	보안 그룹 관리
"mysql_cluster"	MySQL DBaaS 클러스터 관리
"postgresql_cluster"	PostgreSQL DBaaS 클러스터 관리
"kms"	키 관리 서비스
"bucket"	아카이브 스토리지
"iam_user"	IAM 사용자 관리

전체 서비스 목록은 scpv2/resources/data/ 디렉토리의 JSON 파일 이름을 참고하세요.

---

Exception Hierarchy

ScpError
├── ClientError       # API 에러 응답 (4xx, 5xx)
├── ValidationError   # 파라미터 유효성 검사 실패
├── CredentialError   # 자격증명 없음 / 프로파일 없음
├── NoRegionError     # region 미설정
├── WaiterError       # Waiter 타임아웃 / 실패 상태 진입
└── PaginationError   # Paginator 설정 없음

---

License

Apache License 2.0

누구나 자유롭게 사용·수정·배포할 수 있습니다. 상업적 이용도 허용되며, 기여자의 특허 사용권이 자동으로 부여됩니다. 자세한 내용은 Apache License 2.0을 참고하세요.