知识库

使用 TypeScript SDK (@zinn-digital/sdk)

从 npm 安装 @zinn-digital/sdk，创建 API 密钥，并通过 TypeScript 向 Zinn Digital® API 发起您的首次类型化调用——无需密钥的公共区域，然后是您自己的站点——以及导出的架构类型和错误的返回方式。

@zinn-digital/sdk 是我们在 npm 上发布的 Zinn Digital® API 官方 TypeScript 客户端。其中的每个路径、参数和响应均由构建该 API 所依据的同一 OpenAPI 规范生成，并且每当该规范发生更改时，都会自动发布新版本。本指南将指导您完成其安装、身份验证并执行您的首次调用。

安装

npm install @zinn-digital/sdk

它适用于任何支持 fetch 的 JavaScript 运行时：Node.js、浏览器以及边缘运行时。它仅有一个运行时依赖项 openapi-fetch，并且遵循 MIT 许可协议。

创建 API 密钥

打开控制面板的 API 密钥 页面（app.zinndigital.com/api-keys），然后点击 创建密钥。为该密钥命名，并仅授予代码所需的权限 — 例如用于列出站点的 sites.view。该密钥仅显示一次；请将其保存在环境变量或机密保管库中，切勿放入源代码中。您可以随时在同一页面上撤销密钥。

托管区域和方案等公共目录端点完全不需要密钥。

您的首次调用

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

使用 ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts 运行它。第一行打印托管区域，然后每个站点各占一行。

适用于您自己代码的类型

架构类型已导出，因此您自己的函数可以使用该 API 的结构：

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

拼写错误的路径、参数或字段将导致编译错误，而不是静默执行错误操作的请求。

错误

每次调用都会返回 { data, error, response }。对于非 2xx 响应，data 为 undefined，而 error 是 API 的错误封套：error.error.code、人类可读的 error.error.message，以及针对验证失败指明各个字段的 error.error.details。403 表示密钥不具备端点所需的权限 — 请创建一个具有该权限的密钥，而不是复用具有更多权限的密钥。