目次

Contentfulの画像を操作するImages APIの使い方

本サイトはアフィリエイトプログラムを利用した広告を表示しています

Contentfulにアップロードした画像を取得する方法が分からないかもしれません。この記事では、ContentfulのImages APIでできることを一覧で示しつつ、それぞれの概要と使い方をコードで示します。

本ブログはContentfulを用いていて、Images APIも使っています。このときに調べたことを、備忘録的にまとめたのがこの記事となります。よかったら参考にしてください。

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

テクニカルライティングを学ぶ

わかりやすい文章の書き方が学べる入門をnoteで公開しました。ブログやドキュメントなどを書くときにお役立てください。

動作環境

まずはじめに、この記事の内容を検証した環境を示します。この記事はJavaScriptのコードを示しているので、JavaScript用のクライアントのバージョンを示します。

ライブラリバージョンリリース日
contentful8.2.12021-3-29

curlなど他のコード例は、公式ドキュメントをご確認ください。

ContentfulのImages APIとは

ContentfulのImages APIとは、「画像ファイルを取得して操作するためのAPI」です。たとえば、次のようなコードがあるとします。

const contentful = require('contentful')

const client = contentful.createClient({
  space: '<space_id>',
  accessToken: '<content_delivery_api_key>',
})

const asset = client.getAsset('<asset_id>').then((asset) => {
  // ここで画像を操作すると仮定する
})

このgetAsset()の返り値assetを用いると、画像の取得は次のようになります。

asset.fields.file.url

この記事で示すすべてのコード例は、上記のようにassetオブジェクトを元に操作するものとします。

スポンサーリンク

ContentfulのImages APIの操作一覧

それでは、ContentfulのImages APIでできる操作の一覧をまとめていきます。

公式ドキュメントをご確認ください

この記事の内容は、執筆時点のものとなっています。Contentful側のアップデートにより、内容が古くなっている可能性があります。APIを使うときは、公式ドキュメントを確認するようにしてください。

1. フォーマットを変更する

画像のフォーマットを変更します。変更可能なフォーマットは次の通りです。

フォーマット
JPEGjpg
PNGpng
WEBPwebp

デフォルトは元の画像のフォーマットです。たとえば、PNGとしてアップロードした画像を取得時にJPEGに変更するには、次のようになります。

`${asset.fields.file.url}?fm=jpg`

2. プログレッシブJPEGに変換する

プログレッシブJPEGとは何?」によると、プログレッシブJPEGについて次のように説明されています。

コンピューターにダウンロードして表示する際、画像の上辺から下辺に向かって表示するのではなく、はじめに大まかなモザイク状の画像を表示し、次第に鮮明になるため、ダウンロードの途中でもおよその画像内容を把握できる。

つまり、画像を最初に粗く表示し、徐々に鮮明な画像として表示していくフォーマットです。早い段階で画像を表示できるため、レイアウトの崩れなどを防ぐことができます。画像をプログレッシブJPEGに変換するには、次のように取得します。

`${asset.fields.file.url}?fm=jpg&fl=progressive`

3. 8ビットPNGに変換する

8ビットPNGは、PNGとして標準の24ビットよりも軽量なフォーマットです。アイコンやロゴのようなシンプルな画像に適しています。画像を8ビットPNGに変換するには、次のように取得します。

`${asset.fields.file.url}?fm=png&fl=png8`

4. リサイズする

画像のサイズ、つまり幅と高さを変更します。最大値は4,000ピクセルです。画像をリサイズするには、次のように取得します。

`${asset.fields.file.url}?w=100&h=100`
スポンサーリンク

5. リサイズ時の動作を変更する

画像のサイズを変更したときの動作を指定できます。デフォルトではそのまま拡大・縮小しますが、次の値を指定できます。

内容
pad必要に応じて画像の周りを埋める
fill必要に応じて画像をトリミングする
scale必要に応じてアスペクト比を変更する
crop一部をトリミングしてサイズを合わせる
thumbサムネイルを作成する

padを指定すると、画像の周りを単色で埋めることになります。この色は「9. 背景色を指定する」で指定できます。画像をリサイズするには、次のように取得します。

`${asset.fields.file.url}?fit=pad`

6. 焦点を指定する

リサイズ時の動作を変更したときに、値としてpadまたはfillcropthumbを指定した場合、どこに焦点を置くかを次の中から指定できます。

内容
center, top, right, left, bottom-
top_right, top_left, bottom_right, bottom_left-
face検出された顔の中で一番大きいもの
faces検出されたすべての顔

焦点を指定するには、次のように画像を取得します。

`${asset.fields.file.url}?f=face&fit=thumb`

7. 角丸・円を指定する

画像の角を丸くしたり、円や楕円にトリミングできます。デフォルトは指定なしです。設定可能な値は次のとおりです。

内容
(角の半径)ピクセルで指定する
max完全な円もしくは楕円にする

角の半径を0以外として指定した場合、「9. 背景色を指定する」で背景色を指定できます。デフォルトは白です。画像に角丸や円を指定するには、次のように取得します。

`${asset.fields.file.url}?r=20`

8. 品質を指定する

画像の品質を1〜100で指定できます。画像のフォーマットが8ビットPNGのときは無視されます。画像の品質を指定するには、次のように取得します。

`${asset.fields.file.url}?fm=jpg&q=50`

9. 背景色を指定する

リサイズ時の動作がpadのとき、あるいは角丸や円を指定したときに背景色を指定できます。値としてはRGB値を受け入れます。デフォルト値は、画像のフォーマットがJPEGのときは白、PNGまたはWEBPのときは透明になります。背景色を指定するには、次のように取得します。

`${asset.fields.file.url}?bg=rgb:ffffff`

あわせて読みたい

著者
Hiroki Zenigami

テクニカルライター。元エンジニア。共著で「現場で使えるRuby on Rails 5」を書きました。プログラミング教室を作るのが目標です。

スポンサーリンク

ブログをはじめよう

技術ブログの始め方を、たくさんの画像で分かりやすく解説しました。これまでブログをやったことがない人でも、エンジニアにとって重要なブログを今日から始められます。

ブログをはじめる