※X-GLOBAL-DRAFT-KEYは廃止されました。全ての下書きコンテンツを一度に取得するにはAPIに「下書き全取得」権限を付与してください。詳しくはこちら

こんにちは、松田です。
本日の更新情報をお伝えいたします。

新たなAPIキー、X-GLOBAL-DRAFT-KEYを導入しました

本日は下書き保存されているコンテンツの取得に関する更新です。

これまで、下書き状態のコンテンツを取得するにはコンテンツ毎に生成されたdraftKeyという値を使用する必要がありました。
この値はコンテンツ毎に生成されるため以下のような問題点がありました。

• 1つの画面内に複数のコンテンツを読み込んでいる時の下書き状態の確認ができなかった
• Android / iOSなど、基本的にはURLを持たない画面遷移を行う場合に下書き状態の確認ができなかった

こうした問題点に対応するため、新たにX-GLOBAL-DRAFT-KEYというAPIキーを導入しました。
まずは使い方を確認します。

最初に管理画面で「サービス設定」→「APIキー」と進み、X-GLOBAL-DRAFT-KEYを作成します。

作成するとAPIキーが表示されますので、クリップボードにコピーしておきます。

次に下書き状態のコンテンツを含んだAPIを呼び出します。
ここではわかりやすいようにcurlコマンドにて説明いたします。

通常、コンテンツを取得する際には以下のようなGETリクエストを発行します。

$ curl "https://YOUR-SERVICE.microcms.io/api/v1/YOUR-API" -H "X-API-KEY: XXXXXXX-XXXX-XXXX-XXXXX-XXXXXXXXXXXX"

リクエスト先の情報としてサブドメインやパス、APIキーとしてX-API-KEYを設定しています。
この状態では下書き状態のコンテンツはレスポンスに含まれません。

次にX-GLOBAL-DRAFT-KEYを利用する場合です。
curlコマンドには以下のようにX-GLOBAL-DRAFT-KEYヘッダを追加します。

$ curl "https://YOUR-SERVICE.microcms.io/api/v1/YOUR-API" -H "X-API-KEY: XXXXXXX-XXXX-XXXX-XXXXX-XXXXXXXXXXXX" -H "X-GLOBAL-DRAFT-KEY: YYYYYYY-YYYY-YYYY-YYYYY-YYYYYYYYYYYY"

このように指定するだけで、レスポンスには下書き状態のコンテンツが全て含まれます。
今回はcurlを例に示しましたがヘッダに値を追加しているだけですので、あらゆるプラットフォームで同様のリクエストが可能です。

X-GLOBAL-DRAFT-KEYは漏洩してはいけない

上記のようにX-GLOBAL-DRAFT-KEYは利用方法はとても簡単です。
一方でこの値はクライアントに漏洩しないよう気をつける必要があります。
仮にこの値が漏洩してしまうと、下書き状態のコンテンツを取得できてしまうためです。
情報管理を正しく行うため、X-GLOBAL-DRAFT-KEYは漏洩しないよう気をつけて取り扱いましょう。

draftKeyとの違いや使い分け

microCMSの既存の仕組みとしてdraftKeyというものがあります。
これはコンテンツ毎に作成される値であり、以下のような形でリクエストすることで下書き状態のコンテンツを取得できます。

$ curl "https://YOUR-SERVICE.microcms.io/api/v1/YOUR-API?draftKey=ZZZZZZZZZ" -H "X-API-KEY: XXXXXXX-XXXX-XXXX-XXXXX-XXXXXXXXXXXX"

今回導入したX-GLOBAL-DRAFT-KEYヘッダも用途としては「下書き状態のコンテンツを取得する」ということで一致しています。
これら2つをどのように使い分ければ良いでしょうか？

まずは2つの値の違いです。

draftKeyはコンテンツ毎に生成される一方、X-GLOBAL-DRAFT-KEYはサービス内で共通の値です。
そのため利用時に取得できる下書きコンテンツもdraftKeyは1つに対してX-GLOBAL-DRAFT-KEYには制限がありません（全ての下書きコンテンツを一度に取得可能）。

また、draftKeyは管理画面の「画面プレビュー」機能と連動しており指定したURLに値を引き渡すことができますが、X-GLOBAL-DRAFT-KEYにはそういった連携はありません。
X-GLOBAL-DRAFT-KEYを利用するには他のAPIキーと同じくクライアント側であらかじめ値を組み込んでおく必要があります。

こうした違いから例えば以下のような使い分けが考えられるでしょう。

• 【ウェブページ】本番環境上に表示確認URLを用意しておいてdraftKeyを使った下書き確認ができるようにしておく
• 【画面にURLを持たないプラットフォーム（Android / iOSなど）】表示確認用のビルドではX-GLOBAL-DRAFT-KEYを含める形にしておきいつでも表示の確認ができるようにしておく

実際にはウェブであっても同一画面内に複数のAPIのコンテンツを参照しているためdraftKeyが適切でない場合や、モバイルアプリであってもディープリンクが設定してあるため下書きリンク（draftKey）による運用でも良いなど、ケースは様々でしょう。
それぞれの案件の環境にて適切な方法をご選択いただければと思います。（困ったらいつでもご相談ください！）

いずれにせよ今回の更新によって、下書きに関してこれまでより遥かに柔軟にコントロールできる様になったことは確実です。
便利にお使いいただけましたら幸いです！

-----

microCMSは日々改善を進めています。
ご意見・ご要望は管理画面右下のチャット、公式Twitter、メールからお気軽にご連絡ください！
引き続きmicroCMSをよろしくお願いいたします！