שימוש ב-Python SDK (zinn-sdk)

zinn-sdk הוא לקוח ה-Python הרשמי שלנו עבור ה-API של Zinn Digital®, שפורסם ב-PyPI ומיובא כ-zinn_sdk. הוא מיוצר מאותו מפרט OpenAPI שממנו נבנה ה-API, לכל פעולה יש גרסאות synchronous ו-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 ונקראות על שם ה-id של הפעולה שלהן ב-snake case. רשימת אתרים היא zinn_sdk.api.hosting.list_sites; דומיינים ו-DNS נמצאים תחת zinn_sdk.api.domains; חיוב תחת zinn_sdk.api.billing. מפרט ה-API מציג את ה-id של כל פעולה.

Sync, async והתגובה המלאה

לכל מודול פעולה יש ארבע פונקציות:

• 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