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.

這篇指南有幫助嗎?

最後更新於

本頁目錄