Skip to Content
เอกสารสำหรับนักพัฒนา

ใช้ 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.jsonOpenAPI 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/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 ตรวจสิทธิ์และการเข้าถึงของผู้สร้าง เมื่อพบ 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 เนื้อหาสาธารณะ.

คู่มือนี้มีประโยชน์หรือไม่?

อัปเดตล่าสุดเมื่อ

ในหน้านี้