Python SDK (zinn-sdk) の使用

zinn-sdk は、PyPI で公開され、zinn_sdk としてインポートされる、Zinn Digital® API 向けの公式 Python クライアントです。API の構築に使用されたものと同じ OpenAPI 仕様から生成されており、すべての操作に 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)

オペレーションの検索

オペレーションは zinn_sdk.api の下で API 領域ごとにグループ化され、スネークケースのオペレーション id にちなんで命名されています。サイトの一覧表示は zinn_sdk.api.hosting.list_sites、ドメインと DNS は zinn_sdk.api.domains 配下、請求は zinn_sdk.api.billing 配下にあります。API リファレンスには各オペレーションの id が示されています。

同期、非同期、および完全なレスポンス

各オペレーションモジュールには 4 つの関数があります。

• sync(...) はパースされたモデルを返します。予期しないステータスの場合は None を返します。
• sync_detailed(...) は status_code、headers、および parsed を含む Response を返します。
• asyncio(...) および asyncio_detailed(...) も同様で、await 可能です。

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