Używanie pakietu SDK języka Python (zinn-sdk)

zinn-sdk to nasz oficjalny klient języka Python dla interfejsu API Zinn Digital®, opublikowany w serwisie PyPI i importowany jako zinn_sdk. Jest on generowany na podstawie tej samej specyfikacji OpenAPI, w oparciu o którą zbudowano API, każda operacja posiada warianty synchroniczne oraz asyncio, a nowa wersja jest publikowana automatycznie przy każdej zmianie specyfikacji. W tym przewodniku zainstalują go Państwo, uwierzytelnią i wykonają swoje pierwsze wywołania.

Instalacja

pip install zinn-sdk

Wymaga środowiska Python 3.11 lub nowszego i jest udostępniane na licencji MIT.

Utwórz klucz API

Otwórz stronę Klucze API w swoim panelu nawigacyjnym (app.zinndigital.com/api-keys) i naciśnij Utwórz klucz. Nadaj kluczowi nazwę i tylko te uprawnienia, których potrzebuje twój kod — na przykład sites.view, aby wyświetlić listę witryn. Klucz jest wyświetlany tylko raz; zapisz go w zmiennej środowiskowej lub magazynie wpisów tajnych, nigdy w kodzie źródłowym. Klucz można unieważnić w dowolnym momencie na tej samej stronie.

Publiczne punkty końcowe katalogu, takie jak regiony hostingu i plany, nie wymagają żadnego klucza.

twoje pierwsze wywołania

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)

Wyszukiwanie operacji

Operacje są pogrupowane według obszaru API w zinn_sdk.api i nazwane zgodnie z ich identyfikatorem operacji zapisanym w konwencji snake_case. Listowanie witryn to zinn_sdk.api.hosting.list_sites; domeny i DNS znajdują się w zinn_sdk.api.domains; rozliczenia w zinn_sdk.api.billing. Dokumentacja referencyjna API przedstawia identyfikator każdej operacji.

Tryb synchroniczny, asynchroniczny i pełna odpowiedź

Każdy moduł operacji zawiera cztery funkcje:

• sync(...) zwraca przetworzony model lub None w przypadku nieoczekiwanego statusu.
• sync_detailed(...) zwraca obiekt Response zawierający status_code, headers oraz parsed.
• asyncio(...) i asyncio_detailed(...) działają tak samo, lecz są oczekiwalne (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())

Używaj wariantów _detailed, gdy musisz odróżnić błąd 403 (klucz nie ma uprawnienia) od 404.

Gdzie przejść dalej

• Przewodnik w naszej witrynie: zinndigital.com/developers/sdk-python
• Każdy punkt końcowy, jego parametry i uprawnienia: zinndigital.com/developers/api
• Pakiet w serwisie PyPI: pypi.org/project/zinn-sdk