Skip to Content
开发者文档

使用站点 / CMS API

通过 API v1 认证、编辑和发布平台或独立 CMS 的内容。

使用站点 / CMS API

API v1 用于外部系统接入站点和 CMS 数据。先读取当前部署的接口契约,再创建限定权限的密钥,以版本保护保存草稿。

选择服务和部署方式

将 QOKIT_API_URL 设置为 API 服务来源(本地为 http://localhost:7777)或独立安装来源。QOKIT_PROJECT_ID 使用项目 ID;导出包在 data/seed.json 的 project.id 中保存它。公开读取使用项目 slug。

部署方式能力
平台CMS 管理、导出和平台发布
cms-managed本地 CMS 管理和网站渲染
cms-only本地 CMS 管理、公开 headless 读取;不提供网站渲染
site-only静态 HTML 页面与资源;不提供运行时 API

发现接口契约

每个服务只声明自身支持的操作。不支持的操作返回 404。API 1.0 保留现有无版本路由兼容性。

路径用途
GET /v1/openapi.jsonOpenAPI 3.1:请求体、响应、权限和前置条件
GET /v1/capabilitiesAPI 版本、部署类型和支持的操作
GET /v1/sdk/client.mjs零依赖 JavaScript 客户端
GET /v1/sdk/client.d.mts配套 TypeScript 类型声明

创建 API Key

将完成平台登录后获得的 accessToken 作为 SESSION_TOKEN。账号需要站点设置管理权限;签发密钥前必须完成所需身份验证。

curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

独立 CMS 使用部署管理员邮箱和密码登录,保存会话 Cookie,然后创建密钥:

curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

创建时仅返回一次 token。将它保存为服务端环境变量 QOKIT_SITE_API_KEY;请求使用以 qk_site_ 开头的 Bearer token。密钥默认 90 天有效,可设为 1–365 天,每项目最多 50 个有效密钥。使用具备设置管理权限的登录会话,通过 GET /v1/projects/{id}/api-keys 列出密钥,通过 DELETE /v1/projects/{id}/api-keys/{keyId} 撤销密钥。

仅选择集成需要的权限范围。每次请求重新检查创建者的访问权限和角色;到期、撤销与角色变更在后续请求生效。API Key 不能管理其他密钥。

Scope用途
content:read / content:write读取 / 编辑集合和条目
content:publish显式发布,以及直接发布条目的写入
pages:read / pages:write读取 runtime / 编辑页面内容、结构、SEO 和表单
media:read / media:write读取 / 管理媒体和文件夹
settings:read / settings:write读取 / 编辑站点设置
users:read / users:write读取 / 管理 CMS 用户
leads:read / leads:write / analytics:read读取 / 更新线索、读取 CMS 仪表板
marketing:read / marketing:write读取 / 生成营销内容
deployments:read / deployments:write平台导出和发布作业
sync:write / updates:read / updates:write独立安装同步和签名更新

使用 SDK 保存草稿

工作区包为 @qokit/site-api,尚未发布到 npm。外部项目将两个客户端文件下载到 sdk;新导出包已包含这两个文件。

mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mts

本例需要 content:read 和 content:write。将 en 替换为项目已启用的语言。示例会创建一个新集合;再次运行时复用已有集合 ID,避免重复创建。

import { createSiteApiClient } from './sdk/client.mjs';

const api = createSiteApiClient({
  baseUrl: process.env.QOKIT_API_URL,
  projectId: process.env.QOKIT_PROJECT_ID,
  token: process.env.QOKIT_SITE_API_KEY
});

const collection = await api.collections.create({
  key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
  title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
  expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);

保存草稿会保留已发布条目的上一份公开快照。审阅后,拥有 content:publish 的密钥可以显式发布当前保存版本。平台页面编辑仍是草稿,网站正式上线需要完成站点发布流程。

await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });

需要恢复时,先读取 api.entries.revisions(id),再调用 api.entries.restore(id, revisionId, { expectedUpdatedAt })。其他已声明的操作使用 api.request(path, options),可传入 idempotencyKey。客户端不会自动重试写入。

管理接口

以下路径加上 /v1/projects/{id} 前缀。OpenAPI 列出所有操作、请求字段及部署差异。DELETE 对集合、条目和媒体执行归档。

路径方法
/cms/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, POST
/cms/media/{assetId}, /cms/media/folders/{folderId}PUT, DELETE
/runtime, /content/{locale}GET; PUT /content/{locale}
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, PUT
/cms/users, /cms/users/{memberId}GET / POST, PUT / DELETE
/leads, /leads/{leadId}GET, PUT

平台媒体支持 URL 注册和上传意图;独立上传使用 fileName、contentType 和 contentBase64,文件最大 10 MB,并校验文件签名。平台用户变更需要 Idempotency-Key;本地用户创建需要 12–1024 字符密码。CSV、批量写入和翻译关联属于平台扩展。

版本、分页和错误

资源更新、归档和修订恢复必须提交 expectedUpdatedAt,取自最近读取的 updatedAt。缺少版本返回 428;版本过期返回 409。

页面结构、SEO 和表单写入先读取 GET /v1/projects/{id}/runtime,将 content.updatedAt 和 siteVersion.updatedAt 分别作为 baseContentUpdatedAt 和 baseSiteVersionUpdatedAt 提交。平台仍检查 Builder 修订和正在使用的编辑租约。

分页列表默认 page=1&pageSize=24,每页最多 100 条。管理列表返回 items,公开列表返回 entries。修订和文件夹返回数组。导出内容时需读取全部分页。

{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}

响应包含 X-Request-Id 和 X-Qokit-Api-Version。错误包含稳定的错误代码和请求 ID:

{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}

遇到 401 检查密钥有效性;遇到 403 检查 scope 和创建者权限。遇到 409 重新读取并比较变更;遇到 428 补充版本。遇到 429 遵循 Retry-After。限流为每密钥 / 来源每分钟 300 次,平台另有 IP 和写入限制。

独立安装配置

平台浏览器集成使用 CORS_ALLOWED_ORIGINS。独立 API Key 的浏览器调用在 SITE_API_ALLOWED_ORIGINS 中配置精确来源;Cookie 管理会话保持同源。公开 CMS 读取也可配置 CMS_ALLOWED_ORIGINS。CMS-only 媒体 URL 使用 CMS_PUBLIC_URL。

备份完整数据目录和上传文件,包括私有的 data/api-security.json 与 data/api-revisions.json。密码和 API Key 保存为哈希并留在本地。每个数据目录由一个 Node 进程写入。

旧导出包通过签名运行时更新获得 v1。升级后通过 HTTP 下载当前契约和客户端;包内文件仍是导出时的快照。

无需凭证的公开读取见 调用公开内容 API.

这篇指南有帮助吗?

最后更新于

本页目录