Contentfulチートシート

ContentfulのSDKの使い方をまとめる。 職場でもContentfulは使ってるからほぼ自分用

対応ブラウザーとNode

Supported browsers and Node.js versions

• Chrome
• Firefox
• Edge
• IE11
• Safari
• node.js (LTS)

モダーンブラウザーは対応していて、IE11以上は対応している。 他のブラウザーや古いNode.jsでも一応対応しているようだが、厳密なテストはしてなく、自動テストは通る程度のメンテーをしているようなのでもしかするとちゃんと動かないかも。

インストール

npmやyarnなどのパターン

npm install contentful

直接差し込むパターン。 特定のバージョンを使う場合は、 @latest の代わりに @8.2.0 のようなバージョンを指定するだけ。 Contentful Realase

<script src="https://cdn.jsdelivr.net/npm/contentful@latest/dist/contentful.browser.min.js"></script>

IE11や、古いブラウザーの対応が必要な場合は、 contentful.browser.min.js の代わりに、 contentful.legacy.min.js を指定する。

CDAを使おう

CDA(Content Delivery API)は、ContentfulのAPIの一つで、内容を取得する際に使うAPI。 記事を読み込んだり、Contentfulから何かをとってくるAPIなのでもっともメインとなる。 Preview API というDraftまで扱えるAPIがあるが、基本ベースはCDAと同じで、APIのエンドポイントとアクセストークンだけが変わるので必要によって簡単に使える。

とりあえず、CDAを使うためのClientを作る。 clientを作るには space と accessToken は必須。

const client = require("contentful").createClient({
  space: "spaceId",
  accessToken: "accessToken",
});

createClient で指定できるオプション一覧。

長くて書ききれなかったが、 header には以下の２つが追加される。

- Content-Type: application/vnd.contentful.management.v1+json
- X-Contentful-User-Agent: sdk contentful.js/1.2.3; platform node.js/1.2.3; os macOS/1.2.3 (Automatically generated)

Clientからデータを取ってみる

entryIDを指定する方法

client.getEntry('<entry_id>')

content_typeを指定して、複数のentryを取得

client.getEntries({
  content_type: "content_type"
})

Order

特定のフィールドでsortする。

client.getEntries({
  order: 'sys.createdAt'
})

複数指定もできる

client.getEntries({
  order: 'sys.createdAt,sys.id'
})

降順のsort

client.getEntries({
  order: '-fields.publishedDate'
})

orderに指定できるフィールドは String , Date , Integer , Boolean

limit, skip

DBのoffet, limitと同じようなパラメータ ページネーションなどでよく使われる。

client.getEntries({
  skip: 100,
  limit: 200,
  order: 'sys.createdAt'
})

limit はデフォルトで100, 上限は1000まで。

select

取得するフィールドを絞る。 カンマ区切りで取得するフィールドを指定できる。

client.getEntries({
  select: "fields.slug,sys.createdAt",
});

search

あるフィールドの値を完全一致で取得する。

client.getEntries({
  "sys.id": "id"
});

[ne] をつけると不一致な物を取得できる。

client.getEntries({
  "sys.id[ne]": "id",
});

上記の２つはテキストフィールドではサポートされてない。 テキストフィールドで扱いたい場合は content_type と組み合わせる必要がある。

指定したフィールドが配列の場合、配列の中で、一つでも一致するEntryを取得できる。 配列の [ne] は、複数の中で一つでも一致しないものだけを返す。 検索対象が fields の場合は、 content_type を指定する必要がある。

複数指定した中で、全部一致したEntryだけを返すのは [all] を使う

client.getEntries({
  "content_type": "post",
  "fields.tags[all]": "flowers,accessories",
});

複数指定した中で、一つでも一致したEntryだけを返す

client.getEntries({
  "content_type": "post",
  "fields.tags[in]": "flowers,accessories",
});

複数指定してフィルタリングする

client.getEntries({
  "content_type": "post",
  "fields.tags[nin]": "flowers,accessories",
});

指定したフィールドに何かが入っているか否かでフィルタリングする。 何かの値が入っていたら true 、 何も入ってないまたはフィールドが定義されてない場合は false になる。

ちなみに True False などの大文字で入れるとダメみたい。

client.getEntries({
  "content_type": "post",
  "fields.tags[exists]": true,
});

Ranges

範囲の指定は以下の４つ。 検索対象のフィールドは Date や Number 型で指定する。

• [lt] : より小さい
• [lte] : 以下
• [gt] : より大きい
• [gte] : 以上

text query

queryで指定すると、全フィールドを対象に検索をかけられる。 グローバルな全文検索は全てのロケールからテキストや記号の検索ができる。 テキスト検索は大文字と小文字の区分をしないので、予想以上のEntryがくるかも知れない。 指定できる文字列は２文字以上。

client.getEntries({
  query: "design",
});

[match] を使うと、特定のフィールドで文字列検索ができる。

client.getEntries({
  "fields.website[match]": "design",
});

まとめ

チートシートって書いてあるが、全ての仕様を網羅してるわけではなくなった。 でもよく使うのはCDAで、その中で自分でよく使えそうな機能だけはまとめてみた。 追加で必要になったりするとアップデートしていく予定。