下書きを取る（プレビュー）

公開する前のエントリーを、サイトの本番と同じ見た目で確かめたいときは、preview=true を付けて下書きを取り出します。下書きを読めるのは、［プレビュー］の権限のある API キーだけです。

前提

［読み取り］と［プレビュー］の権限のある API キー。権限の決め方は API キーを作る、権限を決めるにあります
このキーは、サイトのサーバーの中だけで使います。ブラウザに渡さないでください。 渡すと、誰でも下書きを読めます

下の例では、<ホスト名> をあなたの環境のホスト名に、<プレビューの API キー> を［プレビュー］の権限のあるキーに置き換えてください。

下書きを取り出す

URL に preview=true を付けます。一覧、1 件、シングルのどれにも使えます。

curl -G https://<ホスト名>.hakocms.net/api/v1/content/posts/hello \
  -H "Authorization: Bearer <プレビューの API キー>" \
  -d preview=true

次のように返ります（日時の一部は省いています）。一度も公開していないエントリーなので、publishedAt と firstPublishedAt は null です。

{
  "sys": {
    "id": "hello",
    "contentType": "posts",
    "publishedAt": null,
    "firstPublishedAt": null,
    "version": 2
  },
  "title": "書きかけのタイトル"
}

preview=true を付けると、次のように返ります。

下書きがあるエントリーは、下書きの値が返ります。下書きがなければ、公開中の値が返ります
一度も公開していないエントリーも返ります
公開をやめたエントリーは返りません
where、order、q も、返す値（下書きの値）で絞り込み、並べます
参照先も同じ決まりで、下書きを読みます

sys.version は、返した値の版の番号です。下書きがあれば下書きの版です。

preview=true は、true か false で書きます。1 や 0 では 400 になります。

サイトで下書きを見せる

下書きを守っているのは API キーの権限で、preview=true ではありません。同じキーでも、preview=true を付けなければ公開中のものだけが返ります。そのため、［プレビュー］の権限のあるキー 1 本で、公開中のページと下書きのプレビューの両方をまかなえます。

何が	決めること
API キー（［プレビュー］の権限）	下書きを読んでよいか。サイトのサーバーの中にだけ置く
`preview=true`	この呼び出しで下書きを返すか
サイトの側の認証	見ている人に下書きを見せてよいか。サイトが自分で決める

サイトの URL に ?preview=true があったら、そのまま付けて呼ぶ、という作りにしないでください。 誰でも下書きを見られてしまいます。

サイトのサーバーで、見せてよい人かを確かめてから preview=true を付けます。たとえば Next.js の Draft Mode のように、サイトだけが知る秘密を確かめた人に署名付きの Cookie を渡し、その Cookie があるときだけ preview=true を付けます。

サイトのサーバーで、見ている人によって preview=true を付けるかどうかを変える例です。isDraftViewer は、サイトで確かめた結果（Cookie があるかなど）です。HAKOCMS_API_KEY には、［プレビュー］の権限のあるキーを入れておきます。

const base = "https://<ホスト名>.hakocms.net/api/v1/content";
const headers = {
  Authorization: `Bearer ${process.env.HAKOCMS_API_KEY}`,
};

async function getPost(id, isDraftViewer) {
  const params = new URLSearchParams();
  if (isDraftViewer) params.set("preview", "true");
  const url = `${base}/posts/${encodeURIComponent(id)}?${params}`;
  const res = await fetch(url, { headers });
  if (res.status === 404) return null;
  return res.json();
}

管理画面のエントリーの編集画面では、右の［情報］の［下書きを取得する URL（プレビュー）］に、そのエントリーの下書きを取り出す URL が出ています。

確かめる

管理画面でエントリーを変えて保存し、公開はしないでおきます。preview=true を付けて取り出し、変えた値が返れば、下書きを取り出せています。preview=true を付けずに取り出すと、公開中の値が返ります。

返ってきたもの	原因	直し方
`403` `forbidden`	キーに［プレビュー］の権限がない	［API キー］の画面で、キーの［プレビュー］にチェックを入れます。［読み取り］も要ります
`404` `not_found`	公開をやめたエントリー、またはないエントリー	公開をやめたエントリーは、`preview=true` でも返りません
`400` `bad_request`	`preview` の値が `true` か `false` でない	`preview=true` と書きます

下書きを取る（プレビュー）

前提

下書きを取り出す

サイトで下書きを見せる

確かめる

関連