Использование Python SDK (zinn-sdk)

zinn-sdk — это наш официальный клиент Python для API Zinn Digital®, опубликованный в 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(...) аналогичны, поддерживают ожидание (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