Python SDK(zinn-sdk) 사용

zinn-sdk는 Zinn Digital® API를 위한 공식 Python 클라이언트로, PyPI에 배포되어 있으며 zinn_sdk로 임포트됩니다. API가 구축된 동일한 OpenAPI 사양을 기반으로 생성되며, 모든 작업에는 동기식 및 asyncio 변형이 제공되고, 사양이 변경될 때마다 새 버전이 자동으로 배포됩니다. 이 가이드는 설치, 인증 및 첫 번째 호출 수행 과정을 안내합니다.

설치

pip install zinn-sdk

Python 3.11 이상이 필요하며 MIT 라이선스가 적용됩니다.

API 키 생성

대시보드의 API 키 페이지(app.zinndigital.com/api-keys)를 열고 키 생성을 누르십시오. 키 이름을 지정하고 코드에 필요한 권한만 부여하십시오(예: 사이트 목록을 조회하기 위한 sites.view). 키는 한 번만 표시되므로 환경 변수나 보안 저장소에 보관하시고, 소스 코드에는 절대 저장하지 마십시오. 동일한 페이지에서 언제든지 키를 취소할 수 있습니다.

호스팅 리전 및 플랜과 같은 공개 카탈로그 엔드포인트에는 키가 전혀 필요하지 않습니다.

첫 번째 호출

import os

from zinn_sdk import AuthenticatedClient, Client
from zinn_sdk.api.catalog import list_public_hosting_regions
from zinn_sdk.api.hosting import list_sites

# Public catalogue endpoints need no key.
public = Client(base_url="https://api.zinndigital.com")
regions = list_public_hosting_regions.sync(client=public)
print([region.slug for region in regions.data])

# Everything else uses a per-organisation API key.
api = AuthenticatedClient(base_url="https://api.zinndigital.com", token=os.environ["ZINN_API_KEY"])
page = list_sites.sync(client=api, limit=5)
for site in page.data:
    print(site.name, site.status)

작업 찾기

작업은 zinn_sdk.api 아래에서 API 영역별로 그룹화되며, 스네이크 케이스(snake case)의 작업 ID를 따라 이름이 지정됩니다. 사이트 목록 조회는 zinn_sdk.api.hosting.list_sites이고, 도메인 및 DNS는 zinn_sdk.api.domains 아래에 있으며, 결제는 zinn_sdk.api.billing 아래에 있습니다. API 참조에 각 작업의 ID가 표시됩니다.

동기, 비동기 및 전체 응답

모든 작업 모듈에는 네 가지 함수가 있습니다:

• sync(...)는 파싱된 모델을 반환하거나, 예상치 못한 상태 코드의 경우 None을 반환합니다.
• sync_detailed(...)는 status_code, headers, parsed가 포함된 Response를 반환합니다.
• asyncio(...) 및 asyncio_detailed(...)는 동일하며 대기 가능(awaitable)합니다.

import asyncio

from zinn_sdk.api.hosting import list_sites

async def main() -> None:
    response = await list_sites.asyncio_detailed(client=api, limit=5)
    print(response.status_code, len(response.parsed.data))

asyncio.run(main())

403(키에 권한이 없음)과 404를 구분해야 할 때는 _detailed 변형을 사용하십시오.

다음 단계

• 당사 웹사이트의 가이드: zinndigital.com/developers/sdk-python
• 모든 엔드포인트, 매개변수 및 권한: zinndigital.com/developers/api
• PyPI의 패키지: pypi.org/project/zinn-sdk