ใช้ API เว็บไซต์ / CMS
ยืนยันตัวตน แก้ไข และเผยแพร่เนื้อหาผ่าน API v1 บนแพลตฟอร์มหรือ CMS อิสระ
ใช้ API เว็บไซต์ / CMS
API v1 เชื่อมระบบภายนอกกับข้อมูลเว็บไซต์และ CMS อ่านสัญญาของระบบที่ติดตั้ง สร้างคีย์ที่จำกัดสิทธิ์ แล้วบันทึกร่างพร้อมการป้องกันเวอร์ชัน
เลือกบริการและรูปแบบติดตั้ง
ตั้ง QOKIT_API_URL เป็น origin ของบริการ 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.json | OpenAPI 3.1: เนื้อหาคำขอ การตอบกลับ สิทธิ์ และเงื่อนไขเบื้องต้น |
GET /v1/capabilities | เวอร์ชัน API ประเภทติดตั้ง และงานที่รองรับ |
GET /v1/sdk/client.mjs | ไคลเอนต์ JavaScript ที่ไม่มี dependency |
GET /v1/sdk/client.d.mts | การประกาศ TypeScript ที่ตรงกัน |
สร้างคีย์ API
ใช้ 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 คำขอใช้ Bearer token ที่ขึ้นต้นด้วย qk_site_ อายุเริ่มต้น 90 วัน ปรับได้ 1–365 วัน และมีคีย์ใช้งานได้สูงสุด 50 คีย์ต่อโครงการ ใช้เซสชันที่มีสิทธิ์จัดการการตั้งค่าเพื่อดูรายการด้วย GET /v1/projects/{id}/api-keys และเพิกถอนด้วย DELETE /v1/projects/{id}/api-keys/{keyId}
เลือกเฉพาะสิทธิ์ที่จำเป็น ทุกคำขอตรวจสอบสิทธิ์และการเข้าถึงปัจจุบันของผู้สร้าง การหมดอายุ เพิกถอน และเปลี่ยนบทบาทมีผลในคำขอถัดไป คีย์ API จัดการคีย์อื่นไม่ได้
| 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
แพ็กเกจ workspace คือ @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);การบันทึกร่างเก็บ snapshot สาธารณะก่อนหน้าของรายการที่เผยแพร่ หลังตรวจสอบ คีย์ที่มี 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/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, 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/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, 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 ตรวจสิทธิ์และการเข้าถึงของผู้สร้าง เมื่อพบ 409 อ่านใหม่และเปรียบเทียบ เมื่อพบ 428 เพิ่มเวอร์ชัน เมื่อพบ 429 ทำตาม Retry-After จำกัด 300 คำขอต่อนาทีต่อคีย์/ที่อยู่ โดยแพลตฟอร์มมีข้อจำกัด IP และการเขียนเพิ่มเติม
ตั้งค่าการติดตั้งอิสระ
การเชื่อมเบราว์เซอร์แพลตฟอร์มใช้ CORS_ALLOWED_ORIGINS คำขออิสระที่ใช้คีย์ต้องระบุ origin ให้ตรงใน SITE_API_ALLOWED_ORIGINS การจัดการด้วย Cookie ยังใช้ origin เดียวกัน การอ่าน CMS สาธารณะใช้ CMS_ALLOWED_ORIGINS ได้ด้วย ตั้ง CMS_PUBLIC_URL สำหรับ URL สื่อ CMS-only
สำรองทั้งไดเรกทอรีข้อมูลและไฟล์อัปโหลด รวมถึงไฟล์ส่วนตัว data/api-security.json และ data/api-revisions.json รหัสผ่านและคีย์เก็บเป็น hash ในเครื่อง แต่ละไดเรกทอรีมีโปรเซส Node เขียนเพียงหนึ่งตัว
แพ็กเกจเก่าได้รับ v1 ผ่านการอัปเดต runtime แบบลงนาม หลังอัปเกรดให้ดาวน์โหลดสัญญาและไคลเอนต์ปัจจุบันผ่าน HTTP ไฟล์ในแพ็กเกจยังเป็น snapshot ขณะส่งออก
การอ่านสาธารณะโดยไม่ใช้ข้อมูลยืนยันตัวตน ดู เรียก API เนื้อหาสาธารณะ.
อัปเดตล่าสุดเมื่อ