استفاده از Python SDK (zinn-sdk)

بسته zinn-sdk کلاینت رسمی Python ما برای API مربوط به Zinn Digital® است که در PyPI منتشر شده و با نام zinn_sdk وارد (import) می‌شود. این بسته از همان مشخصات 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 گروه‌بندی شده‌اند و بر اساس شناسه عملیات خود با فرمت snake case نام‌گذاری شده‌اند. فهرست کردن سایت‌ها zinn_sdk.api.hosting.list_sites است؛ دامنه‌ها و DNS تحت zinn_sdk.api.domains هستند؛ صورت‌حساب تحت zinn_sdk.api.billing است. مرجع API شناسه هر عملیات را نشان می‌دهد.

همگام، ناهمگام و پاسخ کامل

هر ماژول عملیات دارای چهار تابع است:

• تابع 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())

هنگامی که نیاز دارید خطای 403 (کلید فاقد مجوز است) را از 404 تشخیص دهید، از متغیرهای _detailed استفاده کنید.

مقصد بعدی

• راهنمای موجود در وب‌سایت ما: zinndigital.com/developers/sdk-python
• هر نقطه پایانی، پارامترهای آن و مجوز آن: zinndigital.com/developers/api
• بسته در PyPI: pypi.org/project/zinn-sdk