Utilizzo dell'SDK Python (zinn-sdk)

zinn-sdk è il nostro client Python ufficiale per l'API di Zinn Digital®, pubblicato su PyPI e importato come zinn_sdk. È generato dalla stessa specifica OpenAPI su cui è basata l'API, ogni operazione dispone di varianti synchronous e asyncio, e una nuova versione viene pubblicata automaticamente ogni volta che la specifica cambia. Questa guida illustra come installarlo, autenticarlo ed eseguire le prime chiamate.

Installazione

pip install zinn-sdk

Richiede Python 3.11 o versioni successive ed è concesso in licenza MIT.

Creare una chiave API

Apra la pagina Chiavi API della Sua bacheca (app.zinndigital.com/api-keys) e prema Crea una chiave. Assegni un nome alla chiave e soltanto i permessi di cui il Suo codice ha bisogno — ad esempio sites.view per elencare i siti. La chiave viene mostrata una sola volta; la memorizzi in una variabile di ambiente o nel Suo archivio dei segreti, mai nel codice sorgente. Può revocare una chiave in qualsiasi momento dalla stessa pagina.

Gli endpoint del catalogo pubblico, come le regioni di hosting e i piani, non richiedono alcuna chiave.

Le Sue prime chiamate

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)

Individuare un'operazione

Le operazioni sono raggruppate per area API in zinn_sdk.api e denominate in base al rispettivo id operazione in snake case. L'elenco dei siti è zinn_sdk.api.hosting.list_sites; i domini e il DNS sono sotto zinn_sdk.api.domains; la fatturazione sotto zinn_sdk.api.billing. La guida di riferimento dell'API mostra l'id di ciascuna operazione.

Sync, async e la risposta completa

Ogni modulo di operazione dispone di quattro funzioni:

• sync(...) restituisce il modello analizzato oppure None in caso di stato imprevisto.
• sync_detailed(...) restituisce una Response con status_code, headers e parsed.
• asyncio(...) e asyncio_detailed(...) sono identiche, ma 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())

Utilizzi le varianti _detailed quando deve distinguere un errore 403 (alla chiave manca un'autorizzazione) da un 404.

Dove proseguire

• La guida sul nostro sito web: zinndigital.com/developers/sdk-python
• Ogni endpoint, i suoi parametri e la sua autorizzazione: zinndigital.com/developers/api
• Il pacchetto su PyPI: pypi.org/project/zinn-sdk