Sử dụng Python SDK (zinn-sdk)

zinn-sdk là ứng dụng khách Python chính thức của chúng tôi dành cho Zinn Digital® API, được xuất bản trên PyPI và được nhập dưới dạng zinn_sdk. Thư viện này được tạo từ cùng thông số kỹ thuật OpenAPI dùng để xây dựng API, mỗi thao tác đều có các biến thể đồng bộ và asyncio, đồng thời phiên bản mới sẽ tự động được phát hành mỗi khi thông số kỹ thuật có sự thay đổi. Hướng dẫn này sẽ cài đặt, xác thực và thực hiện các lệnh gọi đầu tiên của quý vị.

Cài đặt

pip install zinn-sdk

Yêu cầu Python 3.11 trở lên và được cấp phép theo giấy phép MIT.

Tạo khóa API

Mở trang Khóa API trên bảng điều khiển của quý vị (app.zinndigital.com/api-keys) và nhấn Tạo khóa. Đặt tên cho khóa và chỉ cấp các quyền mà mã của quý vị cần — ví dụ: sites.view để liệt kê các trang web. Khóa chỉ được hiển thị một lần; hãy lưu trữ khóa trong biến môi trường hoặc kho lưu trữ bí mật của quý vị, tuyệt đối không lưu trong mã nguồn. Quý vị có thể thu hồi khóa bất cứ lúc nào trên cùng một trang.

Các điểm cuối danh mục công khai, chẳng hạn như khu vực lưu trữ và các gói dịch vụ, hoàn toàn không cần khóa.

Các lệnh gọi đầu tiên của quý vị

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)

Tìm một thao tác

Các thao tác được nhóm theo khu vực API trong zinn_sdk.api và được đặt tên theo mã định danh thao tác (operation id) ở dạng snake case. Việc liệt kê các trang web là zinn_sdk.api.hosting.list_sites; tên miền và DNS nằm trong zinn_sdk.api.domains; thanh toán nằm trong zinn_sdk.api.billing. Tài liệu tham khảo API sẽ hiển thị mã định danh của từng thao tác.

Đồng bộ, không đồng bộ và phản hồi đầy đủ

Mỗi mô-đun thao tác có bốn hàm:

• sync(...) trả về mô hình đã phân tích cú pháp, hoặc None khi gặp trạng thái không mong muốn.
• sync_detailed(...) trả về một Response cùng với status_code, headers và parsed.
• asyncio(...) và asyncio_detailed(...) cũng tương tự, có thể chờ đợi (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())

Hãy sử dụng các biến thể _detailed khi quý vị cần phân biệt mã 403 (khóa thiếu quyền hạn) với mã 404.

Bước tiếp theo

• Hướng dẫn trên trang web của chúng tôi: zinndigital.com/developers/sdk-python
• Mọi điểm cuối, tham số và quyền hạn tương ứng: zinndigital.com/developers/api
• Gói trên PyPI: pypi.org/project/zinn-sdk