はじめの設定 9 / 14

microCMS をつなぐ

microCMS で作っているサイトをつなぐと、「この案を使う」を選んだ案のタイトル・説明文・見出しを、microCMS のコンテンツにそのまま反映できます。つなぐには、get1pct 専用の API キーを 1 つ作ります。付ける権限は、つなぐ API の GET(読む)と PATCH(一部を書き換える)だけです。

必須かどうか
任意(microCMS のみ)
作業をする場所
microCMS の管理画面

始める前に

  • 必要なもの: microCMS で API キーを作れるメンバー(オーナーや管理者など)と、公開ページの URL の形(例: /blog/記事のID)です。
  • つながなくても使えます: つながない場合は、届いた案の文をコピーして、microCMS の編集画面でご自身で反映します。
  • お預かりするもの: API キーは暗号化して保管し、選んだ案の反映と取り消しにだけ使います。接続を切るときと、解約のときに消します。
  • 画面の写真について: 写真は、英語表示の microCMS です。日本語の表示では「APIキー」「デフォルト権限」「個別権限」などの名前で出ます。ボタンの場所は同じです。

付ける権限

get1pct が microCMS に対して行うのは、次の 2 つだけです。

  • GET: 公開ページの URL に当たるコンテンツを探し、項目の今の値を読みます(下書きは読みません)。
  • PATCH: 選んだ案の項目(タイトル・説明文・見出しのうち、指定したもの)だけを書き換えます。

そのため、「デフォルト権限」の GET を外し、「個別権限」で、つなぐ API にだけ GET と PATCH を付けます。デフォルト権限の GET は最初からチェックが付いていて、サービスのすべての API に効きます。そのままにしないでください。POST・PUT・DELETE、下書きや公開終了のコンテンツの全取得、マネジメント API の権限は要りません。

ご契約のプランで「個別権限」の欄が出ない場合は、デフォルト権限で GET と PATCH を付けます。このときはサービスのすべての API を読み書きできるキーになります。ただし、get1pct が書き換えるのは、管理画面で指定したエンドポイントと項目だけです。

キーの保管のしかたや、漏れたかもしれないときの止め方は、API キーの扱いと安全にまとめています。

手順

手順 1サービス ID を控え、API キーの一覧を開く

microCMS の管理画面にログインし、つなぐサービスを開きます。

microCMS の管理画面(英語表示)。左上にサービス ID、左のメニューに API キーの一覧、右上に Add のボタンがある
  1. 左上のサービス名の下に出ているのが、サービス ID です(xxx.microcms.io の xxx)。控えておきます。
  2. 左のメニューの「1 API Key」を押します(日本語の表示では「〇個のAPIキー」)。
  3. 右上の「Add」(追加)を押します。

手順 2GET と PATCH だけの API キーを作る

microCMS の API キーを作る画面(英語表示)。Default Permission の GET を外し、Custom Permission で API を選んで GET と PATCH だけを付けた状態
  1. 「API Key Name」に、分かる名前(例: get1pct)を入れます。
  2. 「Default Permission」(デフォルト権限)の GET のチェックを外します。最初から付いていて、サービスのすべての API に効くためです。
  3. 「Set custom permissions for selected API」(個別権限)を押し、「Target API」でつなぐ API を選びます。
  4. その API の「GET」にチェックを付けます。
  5. 「PATCH」にチェックを付けます。ほかの欄(下書きの全取得、POST、PUT、DELETE)は付けません。つなぐ API が複数あれば、3〜5 を API ごとに繰り返します。
  6. 右上の「Create」を押して作ります。

設定は「Content API」(コンテンツAPI)のタブで行います。「Management API」(マネジメントAPI)のタブには、何も付けません。

手順 3作ったキーをコピーする

microCMS の API キーの詳しい画面(英語表示)。API Key の欄の右にコピーのボタンがある。キーの値は例の値に差し替えてある
  1. 作ったキーを開き、「API Key」の欄の右のボタンでキーをコピーします。

手順 4エンドポイントを控える

microCMS の API 設定の「Basic Information」(英語表示)。Endpoint の欄に pages と出ている
  1. 記事の一覧を開き、右上の「API Settings」(API 設定)を押します。
  2. 「Endpoint」(エンドポイント)の欄の文字(この例では pages)を控えます。

手順 5書き換えてよい項目の ID を控える

microCMS の API 設定の「API Schema」(英語表示)。Field ID に title、description、h1 が並ぶ
  1. 左の「API Schema」(API スキーマ)を押します。
  2. 「Field ID」(フィールド ID)の列の文字が、管理画面に入れる項目 ID です。タイトル・説明文・見出しに使っている項目の ID を控えます。

指定するのは、文字だけを入れている項目(テキストフィールドなど)にします。書き換えるのは値が公開ページの文とまったく同じときだけなので、HTML を含む項目は書き換えの対象になりません。

手順 6URL の {slug} が何に当たるかを確かめる

microCMS のコンテンツの編集画面(英語表示)。上に Content ID の daily-fixture が出ている
  1. コンテンツを開くと、上に「Content ID」(コンテンツ ID)が出ます。URL のパスにコンテンツ ID を使っていれば、管理画面の「{slug} と照らし合わせる項目 ID」は空のままにします。

公開ページの URL が、コンテンツ ID ではなく slug などの別の項目の値でできているときは、「{slug} と照らし合わせる項目 ID」にその項目の ID を入れます。トップページなど、1 つのコンテンツだけに当たるページは、パスに {slug} を入れず、「コンテンツ ID」の欄に ID を入れます。

手順 7管理画面に入れて「接続する」を押す

管理画面の「サイトの接続」を開きます。「サイトの更新方法」の欄で、「Shopify・Webflow・Contentful・microCMS・その他のサービス」を選びます。

管理画面の「CMS をトークンでつなぐ」で microCMS を選んだ画面。サービス ID、API キー、ページと記事の対応の入力欄がある
  1. 「お使いの CMS」で「microCMS」を選びます。
  2. 「サービス ID」に、控えたサービス ID を入れます。
  3. 「API キー」に、コピーしたキーを貼ります。
  4. 「ページのパス」に公開ページの形(例: /blog/{slug})を、「API のエンドポイント」に控えたエンドポイントを入れます。
  5. {slug} の部分がコンテンツ ID なら空のまま、別の項目(例: slug)なら、その項目 ID を入れます。
  6. 書き換えてよい項目の ID を入れます。空にした種類は、自動では書き換えません。

つなぐ API が複数あるときは、「対応を追加」を押して行を足します(10 個まで)。入れ終わったら、いちばん下の「接続する」を押します。

つなぐときに、キーで指定のエンドポイントを読めるか、PATCH の権限があるかを確かめます。PATCH の権限が足りなければ、その場で「この API キーには書き込みの権限がありません」と出ます。指定した項目がコンテンツに見つからないときは、つないだうえで、項目 ID を確かめてほしいという注意が出ます。項目が空なだけなら、そのままで大丈夫です。

この連携の基準

この接続で案を反映するとき、get1pct は毎回次の決まりで動きます。

  • 書き換えるのは、タイトル(title タグ)・説明文(meta description)・見出し(h1)の 3 種類で、接続のときに指定した項目だけです。本文は書き換えません。
  • CMS の今の値が、案の「変更前」(公開ページの文)とそっくり同じときだけ書き換えます。少しでも違えば、別の記事か、サイト側で文を足している(「|サイト名」など)ので、書かずにコピーで使ってもらいます。
  • 案の「変更後」が変更前と同じもの、2,000 文字を超えるもの、< > [ ] や制御文字を含むものは書きません(CMS 側でタグやショートコードとして読まれることがあるため)。
  • 書く前に「どの項目を、どの値から、どの値へ」の予定を残し、書いたあとは読み直して確かめます。保存された値が違えば、元の値に書き戻して失敗とします。
  • 途中で止まったときは、次に今の値を読み、書き終わっていれば済み、元のままなら続き、どちらでもなければ失敗とします。同じ書き込みを二重にしません。
  • 取り消しは、今の値が get1pct の書いた値のままのときだけ、元の値に戻します。そのあと人が直していれば、戻しません。
  • 呼ぶ先は、その CMS の公式の API のホストだけです。転送(リダイレクト)には従わず、15 秒で打ち切り、2MB を超える応答は読みません。
  • 一度でも公開したコンテンツだけを対象にします(下書きは読みません)。status を付けずに PATCH するので、公開中の内容がその場で変わります。id・createdAt などの予約された項目は書きません。
  • リスト形式の API に加えて、オブジェクト形式の API(ID の無い 1 件だけの API)も使えます。その場合は、{slug} の無いページの対応にして、コンテンツ ID を空にします。オブジェクト形式の API では、書き込みの権限を最初の反映で確かめます。

Shopify・Webflow・Contentful・microCMS の違いは、CMS ごとにできることの表で比べられます。

つないだら確かめる

つないだら、「サイトの接続」の CMS の下にある「つながっているかを確かめる」を使います。記事やアイテムの公開ページの URL を 1 つ入れます。

  • 疎通テスト: CMS の記事を探し、タイトル・説明文・見出しのそれぞれで、CMS の値が公開ページの文とそっくり同じかを表で出します。同じ欄だけが自動で反映されます。違う欄は、表に理由が出ます。何も書き換えません。
  • 更新テスト: 自動で反映できる欄の 1 つに、今の値をそのまま書き直し、読み直します。公開ページの文は変わりません。トークンに書き込みの権限が無いときや、CMS が保存するときに文を変えるときは、その結果が出ます。

先に疎通テスト、次に更新テストの順に行ってください。更新テストで「次の反映ができません」と出たら、CMS でサイト(記事)を公開し直し、運営にお知らせください。

つないだあと

  • 書き込むのは、指定した項目の今の値が公開ページの文とまったく同じときだけです。公開中のコンテンツをその場で書き換えます。反映した案は管理画面から取り消せます。
  • 下書きの版があるコンテンツでは、公開中の版だけが変わります。その下書きをあとで公開すると、get1pct が書いた文は下書きの文に置き換わります。下書きを編集中のコンテンツに案を使うときは、下書きにも同じ文を入れてから公開してください。
  • 一度も公開していないコンテンツ、項目 ID を空にした種類の案、本文の案は、文をコピーしてご自身で反映します。
  • 公開ページを静的に書き出している(SSG)場合は、サイトを再ビルドしたあとで公開ページに出ます。

うまくいかないとき

「接続できませんでした」と出る
サービス ID(xxx.microcms.io の xxx)、エンドポイント、キーの値を確かめます。キーに、そのエンドポイントの GET が付いているかも確かめます。{slug} の無いページは、コンテンツ ID が正しいかも見ます。
案を反映すると失敗と出る
キーに、その API の PATCH が付いているかを確かめます。キーを消したり権限を外したりすると、「サイトの接続」に「つなぎ直しが必要」と出ます。microCMS の回数制限(書き込みは 1 秒に 5 回)に当たったときは、少し待ってから試し直し、それでも通らなければ失敗になります。時間をおいて、もう一度お試しください。
案が自動で反映されない
項目の値が公開ページの文と違う(サイト側で文を足している、など)と、安全のため書き換えません。反映の方法は、案の画面に出ます。

やめるとき

管理画面の「サイトの接続」で「接続を切る」を押すと、お預かりした API キーを消します。キーは microCMS の側に残るので、API キーの一覧で get1pct 用のキーを開き、削除してください。

microCMS の API キーの詳しい画面(英語表示)。右上に Delete のボタンがある
  1. API キーの一覧で get1pct 用のキーを開き、右上の「Delete」(削除)を押すと、そのキーは使えなくなります。

ほかの CMS の手順は、Shopify・Webflow・Contentfulのページにあります。

手順のとおりに進まないときは、お問い合わせから、対象のサイトの URL と、どの画面で止まったかをお知らせください。パスワードは送らないでください。