Використання Python SDK (zinn-sdk)

zinn-sdk — це наш офіційний клієнт Python для Zinn Digital® API, опублікований на PyPI та імпортований як zinn_sdk. Він згенерований на основі тієї самої специфікації OpenAPI, на якій побудовано API, кожна операція має синхронний та 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)

Пошук операції

Операції згруповано за областями API під zinn_sdk.api та названо відповідно до їхнього ідентифікатора операції у стилі snake case. Отримання списку сайтів — це zinn_sdk.api.hosting.list_sites; домени та DNS знаходяться під zinn_sdk.api.domains; білінг — під zinn_sdk.api.billing. Довідник API показує ідентифікатор кожної операції.

Синхронний, асинхронний та повна відповідь

Кожен модуль операції містить чотири функції:

• sync(...) повертає розібрану модель або None у разі неочікуваного статусу.
• sync_detailed(...) повертає Response із status_code, headers та parsed.
• asyncio(...) та asyncio_detailed(...) працюють так само, але підтримують await (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())

Використовуйте варіанти _detailed, коли вам потрібно відрізнити 403 (ключу бракує дозволу) від 404.

Куди переходити далі

• Посібник на нашому вебсайті: zinndigital.com/developers/sdk-python
• Кожна кінцева точка, її параметри та дозвіл: zinndigital.com/developers/api
• Пакет на PyPI: pypi.org/project/zinn-sdk