웹사이트를 CMS API에 연결하세요
CMS API를 사용하면 웹사이트가 Profound CMS에서 게시된 콘텐츠를 가져오고 렌더링할 수 있습니다. 이를 활용하여 문서 페이지, 마케팅 페이지, 블로그, 도움말 센터 등 콘텐츠 중심의 다양한 경험을 구현할 수 있습니다.
일반적인 통합은 세 부분으로 구성됩니다:
애플리케이션을 CMS에 연결하려면 CMS API URL, 웹사이트 ID, 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를 반환하세요.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에 비공개 자격 증명을 포함하지 마세요.
다음과 같은 민감하지 않은 값에만 공개 환경 변수를 사용하세요:
다음 항목에는 비공개 환경 변수를 사용하세요:
웹사이트에서 구조화된 콘텐츠를 가져오거나, CMS에서 관리하는 라우트를 렌더링하거나, 편집자 미리보기 워크플로를 지원해야 할 때 CMS API를 사용하세요.
표준 통합은 다음을 수행해야 합니다: