เชื่อมต่อเว็บไซต์กับ CMS API

API ของ CMS ช่วยให้เว็บไซต์ของคุณดึงและเรนเดอร์เนื้อหาที่เผยแพร่จาก Profound CMS คุณสามารถใช้มันเพื่อขับเคลื่อนหน้าเอกสาร หน้าเว็บไซต์การตลาด บล็อก ศูนย์ช่วยเหลือ หรือประสบการณ์อื่น ๆ ที่ขับเคลื่อนด้วยเนื้อหา

การผสานรวมทั่วไปประกอบด้วยสามส่วน:

1. กำหนดค่าการเชื่อมต่อ CMS ของคุณ
2. ดึงเนื้อหาที่เผยแพร่
3. เรนเดอร์เนื้อหาในแอปพลิเคชันของคุณ

การกำหนดค่า

ในการเชื่อมต่อแอปพลิเคชันของคุณกับ CMS ให้ระบุ URL ของ CMS API ไอดีเว็บไซต์ และคีย์ API ของคุณ

const cmsConfig = {
  cmsUrl: 'https://cms.dev.tryprofoun.com',
  websiteId: 'your-website-id',
  apiKey: process.env.PROFOUND_API_KEY,
};

ใช้ตัวแปรสภาพแวดล้อมสำหรับค่าที่เปลี่ยนไปตามสภาพแวดล้อม:

NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key

อย่าเปิดเผยคีย์ API ส่วนตัวในโค้ดฝั่งไคลเอนต์ คีย์ API ควรถูกใช้บนเซิร์ฟเวอร์ของคุณ ในกระบวนการบิลด์ หรือในเส้นทางแบ็กเอนด์ของคุณ

ดึงเนื้อหา

เนื้อหาใน CMS ถูกจัดตามสคีมา ตัวอย่างเช่น โปรเจ็กต์ของคุณอาจมีสคีมาอย่าง post, category, page หรือ section

ใช้ชื่อสคีมาเพื่อดึงเนื้อหา:

const posts = await cms.schema('post').fetchAll();

เมื่อต้องการดึงเอกสารเดี่ยวด้วย ID:

const post = await cms.schema('post').fetchSingleById('document-id');

เมื่อต้องการดึงเนื้อหาที่แปลแล้ว ให้เรียกสคีมาฉบับแปล:

const frenchPost = await cms
  .schema('post')
  .translation('fr')
  .fetchSingleById('document-id');

เรนเดอร์เส้นทาง

สำหรับเว็บไซต์ที่ใช้หน้าเพจที่จัดการโดย CMS คุณสามารถดึงเนื้อหาตามเส้นทาง URL ปัจจุบันได้

const route = await cms.route.getByPath({
  websiteId: 'your-website-id',
  path: '/docs/getting-started',
});

การตอบกลับของเส้นทางจะระบุหน้าและบล็อกที่ต้องเรนเดอร์ จากนั้นแอปพลิเคชันของคุณสามารถดึงบล็อกเหล่านั้นและเรนเดอร์ด้วยคอมโพเนนต์ของคุณเองได้

const blocks = await cms.block.getByIds({
  websiteId: 'your-website-id',
  ids: route.blockIds,
});

ตัวอย่าง: เรนเดอร์หน้าเอกสารประกอบ

async function getDocsPage(path: string) {
  const route = await cms.route.getByPath({
    websiteId: process.env.WEBSITE_ID,
    path,
  });

  const blocks = await cms.block.getByIds({
    websiteId: process.env.WEBSITE_ID,
    ids: route.blockIds,
  });

  return {
    title: route.label,
    path: route.path,
    blocks,
  };
}

คุณสามารถใช้บล็อกที่ส่งกลับมาเพื่อเรนเดอร์หน้าด้วยระบบคอมโพเนนต์ของแอปพลิเคชันของคุณ

การแคช

เนื้อหาที่เผยแพร่จาก CMS สามารถแคชได้อย่างปลอดภัย สำหรับเว็บไซต์ส่วนใหญ่ ให้แคชการตอบกลับ API ในระยะเวลาสั้น ๆ และตรวจสอบความถูกต้องใหม่เมื่อเนื้อหาเปลี่ยนแปลง

การตั้งค่าที่พบได้บ่อยคือ:

const content = await cache(
  () => cms.schema('post').fetchAll(),
  {
    revalidate: 60,
    tags: ['cms-posts'],
  }
);

พฤติกรรมการแคชที่แนะนำ:

• แคชการอ่านที่เผยแพร่แล้ว
• ใช้หน้าต่างการแคชที่สั้นลงสำหรับเนื้อหาที่อัปเดตบ่อย
• ใช้แท็กแคชหากเฟรมเวิร์กของคุณรองรับการทำให้เป็นโมฆะตามต้องการ
• หลีกเลี่ยงการแคชเนื้อหาแบบพรีวิวหรือฉบับร่าง

โหมดพรีวิว

โหมดพรีวิวช่วยให้นักแก้ไขเห็นการเปลี่ยนแปลงที่ยังไม่เผยแพร่ก่อนที่จะเผยแพร่จริง

รูปแบบที่พบได้ทั่วไปคือใช้เส้นทางพรีวิวแยกต่างหาก ตัวอย่างเช่น:

/docs/getting-started
/cms-preview/docs/getting-started

หน้าผลิตจริงควรดึงเฉพาะเนื้อหาที่เผยแพร่แล้ว หน้าพรีวิวสามารถรับพารามิเตอร์พรีวิว เช่น:

?edit_mode=true

เส้นทางพรีวิวโดยทั่วไปควรเป็นแบบไดนามิกและไม่ควรถูกแคชแบบสแตติก

การจัดการข้อผิดพลาด

เนื้อหา CMS อาจไม่พร้อมใช้งานระหว่างการบิลด์หรือการร้องขอ แอปพลิเคชันของคุณควรจัดการสิ่งนี้อย่างราบรื่น

พฤติกรรมที่แนะนำ:

• ส่งกลับ 404 เมื่อเส้นทางไม่มีอยู่จริง
• ส่งกลับรายการว่างเมื่อไม่สามารถโหลดเนื้อหาการนำทางที่เป็นตัวเลือกได้
• บันทึกข้อผิดพลาดในการดึงข้อมูลฝั่งเซิร์ฟเวอร์
• หลีกเลี่ยงการเปิดเผยข้อผิดพลาดของ API ภายในให้ผู้เยี่ยมชมเห็น

ตัวอย่าง:

async function getPost(id: string) {
  try {
    return await cms.schema('post').fetchSingleById(id);
  } catch (error) {
    console.error('Failed to fetch CMS post', error);
    return null;
  }
}

ความปลอดภัย

เก็บคีย์ API ไว้เป็นความลับและใช้เฉพาะบนเซิร์ฟเวอร์ อย่าใส่ข้อมูลรับรองส่วนตัวในบันเดิลสำหรับเบราว์เซอร์หรือ JavaScript สาธารณะ

ใช้ตัวแปรสภาพแวดล้อมแบบสาธารณะเฉพาะสำหรับค่าที่ไม่ละเอียดอ่อน เช่น:

• URL สาธารณะของ CMS
• ไอดีเว็บไซต์
• การกำหนดค่าภาษาและภูมิภาค

ใช้ตัวแปรสภาพแวดล้อมแบบส่วนตัวสำหรับ:

• คีย์ API
• โทเค็นพรีวิว
• ข้อมูลรับรองผู้ดูแลระบบ
• ความลับสำหรับการดีพลอย

สรุป

ใช้ CMS API เมื่อเว็บไซต์ของคุณต้องดึงเนื้อหาเชิงโครงสร้าง เรนเดอร์เส้นทางที่จัดการโดย CMS หรือรองรับเวิร์กโฟลว์พรีวิวสำหรับบรรณาธิการ

การผสานระบบมาตรฐานควร:

• กำหนดค่า CMS URL ไอดีเว็บไซต์ และคีย์ API
• ดึงเอกสารตามสคีมา
• ดึงหน้าตามเส้นทาง
• เรนเดอร์บล็อกของ CMS ด้วยคอมโพเนนต์ของคุณเอง
• แคชเนื้อหาที่เผยแพร่แล้ว
• ทำให้เนื้อหาพรีวิวคงความไดนามิก
• เก็บข้อมูลรับรองส่วนตัวไว้บนเซิร์ฟเวอร์