การใช้งาน Python SDK (zinn-sdk)

zinn-sdk คือไคลเอนต์ Python อย่างเป็นทางการของเราสำหรับ Zinn Digital® API ซึ่งเผยแพร่บน 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 และตั้งชื่อตาม operation id ในรูปแบบ snake case ตัวอย่างเช่น การแสดงรายการเว็บไซต์คือ zinn_sdk.api.hosting.list_sites ส่วนโดเมนและ DNS จะอยู่ภายใต้ zinn_sdk.api.domains และการเรียกเก็บเงินจะอยู่ภายใต้ zinn_sdk.api.billing ข้อมูลอ้างอิง API จะแสดง id ของแต่ละการดำเนินการ

แบบซิงโครนัส แบบอะซิงโครนัส และการตอบกลับฉบับเต็ม

โมดูลการดำเนินการทุกโมดูลมี 4 ฟังก์ชัน:

• 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