A Python SDK (zinn-sdk) használata

A zinn-sdk a hivatalos Python kliensünk a Zinn Digital® API-hoz, amely a PyPI-on érhető el, és zinn_sdk néven importálható. Ugyanabból az OpenAPI specifikációból készül, amelyre az API is épül, minden művelet rendelkezik synchronous és asyncio változatokkal, és a specifikáció módosításakor automatikusan új verzió jelenik meg. Ez az útmutató bemutatja a telepítést, a hitelesítést és az első hívások kezdeményezését.

Telepítés

pip install zinn-sdk

Használatához Python 3.11 vagy újabb verzió szükséges, és MIT-licenccel rendelkezik.

API-kulcs létrehozása

Nyissa meg a vezérlőpult API-kulcsok oldalát (app.zinndigital.com/api-keys), majd nyomja meg a Kulcs létrehozása gombot. Adjon nevet a kulcsnak, és kizárólag azokat az engedélyeket biztosítsa, amelyekre a kódjának szüksége van — például sites.view az oldalak kilistázásához. A kulcs csak egyszer jelenik meg; tárolja egy környezeti változóban vagy a titkos kulcstárban, soha ne a forráskódban. A kulcsot bármikor visszavonhatja ugyanezen az oldalon.

A nyilvános katalógus-végpontokhoz, mint például a tárhelyrégiókhoz és -csomagokhoz, egyáltalán nincs szükség kulcsra.

Az első hívásai

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)

Művelet keresése

A műveletek API-terület szerint vannak csoportosítva a zinn_sdk.api alatt, és a műveletazonosítójuk után kapták a nevüket snake_case formátumban. A webhelyek listázása a zinn_sdk.api.hosting.list_sites; a tartományok és a DNS a zinn_sdk.api.domains alatt találhatók; a számlázás a zinn_sdk.api.billing alatt. Az API-referencia megjeleníti az egyes műveletek azonosítóját.

Sync, async és a teljes válasz

Minden műveleti modul négy függvényt tartalmaz:

• A sync(...) a feldolgozott modellt adja vissza, vagy None értéket váratlan állapot esetén.
• A sync_detailed(...) egy Response objektumot ad vissza status_code, headers és parsed mezőkkel.
• Az asyncio(...) és az asyncio_detailed(...) ugyanezek, de bevárhatók (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())

Használja a _detailed változatokat, ha meg kell különböztetnie a 403-as hibát (a kulcs nem rendelkezik engedéllyel) a 404-estől.

Merre tovább

• Útmutató a weboldalunkon: zinndigital.com/developers/sdk-python
• Minden végpont, annak paraméterei és jogosultsága: zinndigital.com/developers/api
• A csomag a PyPI-n: pypi.org/project/zinn-sdk