CMS API にウェブサイトを接続する
CMS API を使用すると、ウェブサイトは Profound CMS から公開されたコンテンツを取得してレンダリングできます。ドキュメントページ、マーケティングページ、ブログ、ヘルプセンター、その他のコンテンツ重視のエクスペリエンスを構築するのに利用できます。
一般的な統合は次の3つの要素で構成されます:
アプリケーションを 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 を利用してください。
標準的な統合では次のことを行います: