Python SDK (zinn-sdk) کا استعمال

zinn-sdk Zinn Digital® API کے لیے ہمارا باضابطہ Python کلائنٹ ہے، جو PyPI پر شائع کیا گیا ہے اور zinn_sdk کے طور پر امپورٹ کیا جاتا ہے۔ یہ اسی OpenAPI کی تفصیلات سے تیار کیا گیا ہے جس سے API بنی ہے، ہر آپریشن کے ہم وقت ساز اور asyncio متغیرات موجود ہیں، اور جب بھی تفصیلات میں تبدیلی ہوتی ہے تو نیا ورژن خودکار طور پر شائع ہو جاتا ہے۔ یہ گائیڈ اسے انسٹال کرتی ہے، تصدیق کرتی ہے اور آپ کی پہلی کالز کرتی ہے۔

انسٹال کریں

pip install zinn-sdk

اس کے لیے Python 3.11 یا بعد کا ورژن درکار ہے اور یہ MIT کے تحت لائسنس یافتہ ہے۔

API کلید بنائیں

اپنے ڈیش بورڈ کا API کلیدیں والا صفحہ کھولیں (app.zinndigital.com/api-keys) اور کلید بنائیں دبائیں۔ کلید کو ایک نام دیں اور صرف وہی اجازتیں دیں جن کی آپ کے کوڈ کو ضرورت ہے — مثال کے طور پر سائٹس کی فہرست کے لیے sites.view۔ کلید صرف ایک بار دکھائی جاتی ہے؛ اسے کسی ماحولیاتی متغیر (environment variable) یا اپنے خفیہ اسٹور میں محفوظ کریں، سورس کوڈ میں کبھی نہیں۔ آپ اسی صفحے پر کسی بھی وقت کلید کو منسوخ کر سکتے ہیں۔

عوامی کیٹلاگ اینڈ پوائنٹس، جیسے ہوسٹنگ کے خطے اور منصوبے، کو کسی کلید کی بالکل ضرورت نہیں ہوتی ہے۔

آپ کی پہلی کالز

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)

آپریشن تلاش کرنا

آپریشنز کو zinn_sdk.api کے تحت API کے شعبے کے لحاظ سے گروپ کیا گیا ہے اور ان کا نام ان کے operation 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(...) status_code، headers اور parsed کے ساتھ ایک Response واپس کرتا ہے۔
• 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