Verwendung des Python SDK (zinn-sdk)

zinn-sdk ist unser offizieller Python-Client für die Zinn Digital®-API, veröffentlicht auf PyPI und importiert als zinn_sdk. Er wird aus derselben OpenAPI-Spezifikation generiert, auf der die API basiert, jede Operation verfügt über synchrone und asyncio-Varianten, und bei jeder Änderung der Spezifikation wird automatisch eine neue Version veröffentlicht. Dieser Leitfaden installiert ihn, authentifiziert ihn und führt Ihre ersten Aufrufe durch.

Installieren

pip install zinn-sdk

Es erfordert Python 3.11 oder neuer und ist MIT-lizenziert.

Einen API-Schlüssel erstellen

Öffnen Sie die Seite API-Schlüssel Ihres Dashboards (app.zinndigital.com/api-keys) und drücken Sie auf Schlüssel erstellen. Geben Sie dem Schlüssel einen Namen und nur die Berechtigungen, die Ihr Code benötigt — zum Beispiel sites.view, um Websites aufzulisten. Der Schlüssel wird nur einmal angezeigt; speichern Sie ihn in einer Umgebungsvariable oder Ihrem Secret-Store, niemals im Quellcode. Sie können einen Schlüssel jederzeit auf derselben Seite widerrufen.

Öffentliche Katalog-Endpunkte, wie Hosting-Regionen und -Tarife, benötigen überhaupt keinen Schlüssel.

Ihre ersten Aufrufe

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)

Eine Operation finden

Operationen sind nach API-Bereich unter zinn_sdk.api gruppiert und nach ihrer Operations-ID in Snake-Case benannt. Das Auflisten von Websites lautet zinn_sdk.api.hosting.list_sites; Domains und DNS befinden sich unter zinn_sdk.api.domains; die Abrechnung unter zinn_sdk.api.billing. Die API-Referenz zeigt die ID jeder Operation an.

Synchron, asynchron und die vollständige Antwort

Jedes Operationsmodul verfügt über vier Funktionen:

• sync(...) gibt das geparste Modell zurück, oder None bei einem unerwarteten Status.
• sync_detailed(...) gibt eine Response mit status_code, headers und parsed zurück.
• asyncio(...) und asyncio_detailed(...) sind identisch, jedoch 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())

Verwenden Sie die Varianten _detailed, wenn Sie einen 403 (dem Schlüssel fehlt eine Berechtigung) von einem 404 unterscheiden müssen.

Wie es weitergeht

• Der Leitfaden auf unserer Website: zinndigital.com/developers/sdk-python
• Jeder Endpunkt, seine Parameter und seine Berechtigung: zinndigital.com/developers/api
• Das Paket auf PyPI: pypi.org/project/zinn-sdk