Skip to Content
开发者文档

调用公开内容 API

使用 API v1 读取已发布内容,处理分页、语言回退和 headless 部署。

调用公开内容 API

外部前端或内容消费系统使用公开 API。已发布条目无需 API Key;草稿和归档条目不可见,已发布条目的后续编辑在再次发布前保持私有。

选择标识和接口

将 QOKIT_API_URL 设置为 API 或安装来源,将 QOKIT_PROJECT_SLUG 设置为项目 slug,将 QOKIT_COLLECTION_KEY 设置为集合 key。这些接口使用 slug 和 key,管理接口使用资源 ID。

GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries?locale=en&page=1&pageSize=24
GET /v1/projects/slug/{slug}/cms/collections/{collectionKey}/entries/{entrySlug}?locale=en
GET /v1/projects/slug/{slug}/runtime?locale=en

读取全部分页和条目详情

客户端的下载步骤见 使用站点 / CMS API.

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

const api = createSiteApiClient({ baseUrl: process.env.QOKIT_API_URL });
const projectSlug = process.env.QOKIT_PROJECT_SLUG;
const collectionKey = process.env.QOKIT_COLLECTION_KEY;
const entries = [];
let page = 1;
let result;
do {
  result = await api.publicEntries(projectSlug, collectionKey, {
    locale: 'en', page, pageSize: 24
  });
  entries.push(...result.entries);
  page++;
} while (page <= result.totalPages);

if (entries.length) {
  const detail = await api.publicEntry(projectSlug, collectionKey, entries[0].slug, {
    locale: result.locale
  });
  console.log(detail.entry.title);
}
console.log(entries.length, result.locale, result.localeFallback);

理解响应

列表返回 entries、page、pageSize、total 和 totalPages;详情响应返回 entry。默认每页 24 条,最多 100 条。只读取第一页不能获得整个集合。

链接条目时使用响应中的 locale。localeFallback 包含 requestedLocale、resolvedLocale 和 usedFallback。回退链为区域语言、基础语言、项目默认语言、英文。顶层 requestedLocale 是否存在取决于部署。

查看服务契约中的 search、category、brand、minPrice、maxPrice、featured 和 sort;适用性取决于集合。经校验的 fieldQuery 是平台扩展,独立安装收到它会返回 400。

部署、来源和兼容性

平台公开 runtime 读取已发布站点版本。CMS-managed 和 CMS-only 支持实时读取公开 CMS 内容;site-only 只包含静态 HTML 与资源,没有内容 API。CMS-only 不包含网站渲染器。管理密钥不得放入前端代码。

现有平台 /projects/slug/{slug} 路由继续可用。独立 /api/content/collections/{collectionKey}/entries 路由继续可用,其分页元数据位于 pagination 中。新集成使用 v1 及其 OpenAPI 契约。

找不到已发布内容时处理 404;筛选参数无效返回 400。遇到 429 遵循 Retry-After。按管理指南配置允许的前端来源。

认证、CORS、写入和部署差异见 使用站点 / CMS API.

这篇指南有帮助吗?

最后更新于

本页目录