プロダクト開発

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

こんにちは、ぜに(@zenizh)です。今回は、Contentfulについての次のような疑問:

読者のイメージ

Contentfulにアップロードした画像を取得するときに操作したいから、使い方を教えてね。

について、記事でまとめていきますね。

この記事では、ContentfulのImages APIでできることを一覧で示しつつ、それぞれの概要と使い方をコードで示します

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

目次

動作環境

まずはじめに、この記事の内容を検証した環境を示します。この記事は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

Webエンジニア&プロダクトマネージャ←プログラミング教育で起業←東大院←熊本高専。 共著に「現場で使えるRuby on Rails 5」。

関連記事関連書籍人気記事
applis
エンジニアとしてのんびり暮らす
お問い合わせ
ご意見・ご質問やお仕事のご依頼などは下記よりお願いいたします
お問い合わせ
© applis