知识库

使用 Python SDK (zinn-sdk)

从 PyPI 安装 zinn-sdk，创建 API 密钥，并通过 Python 调用 Zinn Digital® API —— 无需密钥的公共区域，然后是您自己的站点 —— 以及每个操作在 zinn_sdk.api 下的位置，还有同步、异步和详细变体。

zinn-sdk 是我们为 Zinn Digital® API 提供的官方 Python 客户端，已发布在 PyPI 上，并通过 zinn_sdk 导入。它基于构建 API 所采用的同一 OpenAPI 规范生成，每项操作均提供同步和 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）的操作 ID 命名。列出站点为 zinn_sdk.api.hosting.list_sites；域名与 DNS 位于 zinn_sdk.api.domains 下；账单位于 zinn_sdk.api.billing 下。API 参考文档会显示每个操作的 ID。

同步、异步与完整响应

每个操作模块均包含四个函数：

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 变体。