استخدام Python SDK (zinn-sdk)

تُعد حزمة zinn-sdk عميل Python الرسمي الخاص بنا لواجهة برمجة تطبيقات Zinn Digital®، وهي منشورة على PyPI ويتم استيرادها باسم zinn_sdk. تم إنشاؤها من مواصفات OpenAPI نفسها التي بُنيت واجهة برمجة التطبيقات استنادًا إليها، وتتضمن كل عملية متغيرات متزامنة وأخرى غير متزامنة (asyncio)، كما يتم نشر إصدار جديد تلقائيًا كلما تغيّرت المواصفات. يوضح لكم هذا الدليل كيفية تثبيتها والمصادقة عليها وإجراء أولى استدعاءاتكم البرمجية.

التثبيت

pip install zinn-sdk

يتطلب Python 3.11 أو إصداراً أحدث وهو مرخص بموجب ترخيص MIT.

إنشاء مفتاح واجهة برمجة التطبيقات

افتح صفحة مفاتيح واجهة برمجة التطبيقات في لوحة التحكم الخاصة بك (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())

استخدم متغيرات _detailed عندما تحتاج إلى التمييز بين 403 (المفتاح يفتقر إلى الإذن) و404.

إلى أين تتجه بعد ذلك

• الدليل الموجود على موقعنا الإلكتروني: zinndigital.com/developers/sdk-python
• كل نقطة نهاية ومعلماتها وإذنها: zinndigital.com/developers/api
• الحزمة على PyPI: pypi.org/project/zinn-sdk