呼叫公開內容 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.
最後更新於