Kết nối một trang web với CMS API
API của CMS cho phép trang web của bạn truy xuất và kết xuất nội dung đã xuất bản từ Profound CMS. Bạn có thể dùng nó để vận hành các trang tài liệu, trang marketing, blog, trung tâm trợ giúp hoặc bất kỳ trải nghiệm dựa trên nội dung nào khác.
Tích hợp điển hình gồm ba phần:
Để kết nối ứng dụng của bạn với CMS, hãy cung cấp URL API CMS, ID trang web và khóa API.
const cmsConfig = {
cmsUrl: 'https://cms.dev.tryprofoun.com',
websiteId: 'your-website-id',
apiKey: process.env.PROFOUND_API_KEY,
};
Sử dụng các biến môi trường cho những giá trị thay đổi giữa các môi trường:
NEXT_PUBLIC_CMS_API_URL=https://cms.dev.tryprofound.com
NEXT_PUBLIC_WEBSITE_ID=your-website-id
PROFOUND_API_KEY=your-api-key
Không để lộ các khóa API riêng tư trong mã phía client. Khóa API nên được dùng trên máy chủ của bạn, trong quy trình build hoặc trong các tuyến backend.
Nội dung trong CMS được tổ chức theo schema. Ví dụ, dự án của bạn có thể có các schema như post, category, page hoặc section.
Sử dụng tên schema để truy xuất nội dung:
const posts = await cms.schema('post').fetchAll();
Để truy xuất một tài liệu bằng ID:
const post = await cms.schema('post').fetchSingleById('document-id');
Để truy xuất nội dung đã bản địa hóa, hãy yêu cầu phiên bản đã dịch của schema:
const frenchPost = await cms
.schema('post')
.translation('fr')
.fetchSingleById('document-id');
Đối với các trang web sử dụng các trang do CMS quản lý, bạn có thể truy xuất nội dung dựa trên đường dẫn URL hiện tại.
const route = await cms.route.getByPath({
websiteId: 'your-website-id',
path: '/docs/getting-started',
});
Phản hồi của tuyến xác định trang và các khối cần kết xuất. Ứng dụng của bạn sau đó có thể truy xuất các khối và kết xuất chúng bằng các thành phần của riêng bạn.
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,
};
}
Bạn có thể sử dụng các khối trả về để kết xuất trang bằng hệ thống thành phần của ứng dụng.
Nội dung CMS đã xuất bản an toàn để lưu vào bộ nhớ đệm. Đối với hầu hết các trang web, hãy lưu vào bộ nhớ đệm phản hồi API trong thời gian ngắn và tái xác thực khi nội dung thay đổi.
Một thiết lập phổ biến là:
const content = await cache(
() => cms.schema('post').fetchAll(),
{
revalidate: 60,
tags: ['cms-posts'],
}
);
Hành vi bộ nhớ đệm được khuyến nghị:
Chế độ xem trước cho phép biên tập viên xem các thay đổi chưa được xuất bản trước khi chúng được phát hành.
Một mẫu phổ biến là sử dụng một tuyến xem trước riêng, ví dụ:
/docs/getting-started
/cms-preview/docs/getting-started
Các trang production chỉ nên truy xuất nội dung đã xuất bản. Các trang xem trước có thể chấp nhận các tham số xem trước, chẳng hạn như:
?edit_mode=true
Các tuyến xem trước thường nên là động và không nên được lưu bộ nhớ đệm tĩnh.
Nội dung CMS có thể không khả dụng trong quá trình build hoặc khi có yêu cầu. Ứng dụng của bạn nên xử lý tình huống này một cách mềm mại.
Hành vi được khuyến nghị:
404 khi một tuyến không tồn tại.async function getPost(id: string) {
try {
return await cms.schema('post').fetchSingleById(id);
} catch (error) {
console.error('Không thể truy xuất bài viết CMS', error);
return null;
}
}
Giữ khóa API ở chế độ riêng tư và chỉ sử dụng chúng trên máy chủ. Không đưa thông tin xác thực riêng tư vào các gói JavaScript công khai hoặc chạy trên trình duyệt.
Chỉ sử dụng các biến môi trường công khai cho những giá trị không nhạy cảm như:
Sử dụng các biến môi trường riêng tư cho:
Sử dụng CMS API khi trang web của bạn cần truy xuất nội dung có cấu trúc, kết xuất các tuyến do CMS quản lý hoặc hỗ trợ quy trình xem trước của biên tập viên.
Một tích hợp tiêu chuẩn nên: