Cloudinary MO の Mapping Function を使ってカスタムパラメータで画像を変換してみた

先日、Cloudinaryの新しいサービスである Media Optimizer (MO) に関する記事をご紹介しました。

Cloudinary MO でもっと手軽に画像最適化を導入できるように！

そちらでは省いた、MOの高度な機能 Mapping Function について、今回の記事でご紹介します。

Mapping Function とは

Cloudinaryには画像や動画を最適化させるための変換パラメータがあります。

ざっくり言うと、Mapping Functionによって、URL内で追加の変換パラメータを指定して動的に適用させたり、URLに独自のカスタムパラメータを指定してそれに応じた変換を適用させたりすることが可能となります。

この、「指定されたURL内のパラメータに対してどのように変換を適用させるか」というマッピングを Mapping Function で定義します。

Mapping Function は、Delivery Profiles の設定内で指定する項目の一つです。

おさらいとなりますが、MOにおける配信URLは、下記のように構成されており、この Path Prefix ごとにオリジンソースと変換セットの組み合わせを定義します。

https://[MOのクラウド名].mo.cloudinary.net/[Path Prefix]/[アセットのパス]

冒頭の記事内でも記載しているように、あるパスに対してある変換を適用する、という通常の変換適用を利用するだけであれば、Mapping Functionは関係ありません。なので、デフォルトで選択されている「Media Optimizer」のままでOKです。

一方、URLの追加パラメータで特定の変換を適用させる場合にMapping Functionを正しく設定する必要があります。

例えば、 以下のような設定の場合に、URL内で追加パラメータを指定して、最終的にf_auto,q_auto,w_300を適用させることができます。

• Path Prefix: cm
  • ベース変換: f_auto,q_auto
• アセットのパス: ito-test/Reichstag.jpg

# 例1
https://[ドメイン]/cm/ito-test/Reichstag.jpg?tx=w_300
# 例2
https://[ドメイン]/cm/w_300/ito-test/Reichstag.jpg
# 例3
https://[ドメイン]/cm/ito-test/Reichstag.jpg?width=300

上記例のように異なる形式で指定するためには、それぞれに適切なMapping Functionを設定するのです。

3つのパターン

大きく分けて3つ、デフォルトで作成されている2つと、それ以外に自分で作成する方法があります。（デフォルトの2つは削除することはできません。）

• Media Optimizer：末尾の?tx=に続けて変換パラメータを指定（例1）
• Programmable Media：通常のCloudinaryのURLと同様に変換パラメータを指定（例2）
• カスタム：末尾の?に続くクエリをJavascriptコードで自由に定義（例3）

最終的に適用できるのはMOでサポートされる変換のみで、MOにおいてはウォーターマークやエフェクトの多くは使用することができませんのでご注意ください。

Media Optimizer

Mapping Function のデフォルト値です。

このオプションを選択した場合、先ほどの「例1」のように、URLの末尾で?tx=に続けてCloudinaryの変換パラメータを指定することで、ベース変換に加えて追加の変換を適用させることができます。

• 追加パラメータなし（ベース: f_auto,q_auto）
  • ~/cm/trip/hb1.jpg
• 追加で400x400のサイズとする場合
  • ~/cm/trip/hb1.jpg?tx=c_fill,w_400,h_400

Programmable Media

オリジンソースが Cloudinary の場合、「Media Optimizer」も利用可能ですが、機能を最大限活用できるようこのオプションを選択することが推奨されています。

この場合、MOのドメインと「Path Prefix」に続くURL形式が通常のCloudinaryの配信URLと似ており、[リソースタイプ]/[タイプ]/[追加の変換パラメータ]/[パブリックID] を指定することで、ベース変換に加えて追加の変換を適用させることができます。

リソースタイプとタイプは画像であればimage/uploadで、これはデフォルト値のため、先ほどの「例2」のように省略することも可能です。

• 追加パラメータなし（ベース: f_auto,q_auto）
  • ~/cm/ito-test/bike.jpg
• 追加で横幅を200pxにスケールする場合
  • ~/cm/image/upload/c_scale,w_200/ito-test/bike.jpg
• image/uploadを省略した場合
  • ~/cm/c_scale,w_200/ito-test/bike.jpg
• 通常のCloudinaryのURL
  • https://res.cloudinary.com/[CLOUD-NAME]/image/upload/c_scale,f_auto,q_auto,w_200/ito-test/bike.jpg

リソースタイプには、動画の場合はvideo、それ以外はrawを指定します。

• 動画の場合（追加で横幅を200pxにスケール）
  • ~/cm/video/upload/c_scale,w_200/ito-test/video.mp4
• CSVファイルの場合
  • ~/cm/raw/upload/ito-test/sample.csv

その他にもこちらの記事で紹介しているような動的SEOサフィックスの機能を使用することも可能です。

なお、Cloudinary 以外のオリジンソースの場合には、このオプションを選択するとエラーとなるので注意しましょう。

逆にこのオプションを選択している限り、Media Optimizerのように~/image.jpg?tx=w_300などと指定しても、?以降のクエリは無視されて変換は適用されません。

カスタム

新しい Mapping Function を作成し、JavascriptのコードでURL末尾の?以降のクエリをどのように処理するか定義することができます。

例えば、次のようなことが可能となります。

• size=smallと指定した場合、追加で150x100にフィットするよう変換させる
  • ~/cm/trip/hb2.jpg?size=small
• Cloudinaryのものではない形式のパラメータを指定しても変換できるようにする
  • ~/cm/trip/hb2.jpg?filter=w407
• trn=noneと指定した場合、ベース変換を適用させない
  • ~/cm/trip/hb2.jpg?trn=none

今回は試しにドキュメントのコード例に載っている Example 1 を元にやってみました。

MOのコンソールの Configuration > Media Sources > Add new より新しい Mapping Function を作成します。名前を付与し、コードを入力します。

コード

function map(request, environment) {
  let transformation = environment.defaultTransformation + '/';

  // width と height のクエリがあれば変換に追加する
  if (request.query.width && request.query.height) {
    transformation += `c_limit,h_${request.query.height},w_${request.query.width}/`;
  } 
  // size のクエリがあればそれぞれ特定の変換を追加する
  else if (request.query.size) {
    switch(request.query.size) {
      case 'small':
        transformation += "c_fit,h_100,w_150/";
        break;
      case 'medium':
        transformation += "c_fit,h_240,w_360/";
        break;
      case 'large':
        transformation += "c_fit,h_480,w_720/";
        break;
    }
  }
  let path = request.path;

  // fwd_key 用に Path Prefix を除去する
  if (environment.pathPrefix.length > 0) {
      path = path.slice(`/${environment.pathPrefix}/`.length);
  }

  return {
    fwd_key: path,
    media_key: request.path,
    transformation,
    resource_type: 'image',
  };
}

パラメータ

ここで使用されているパラメータは次の通りです。

レスポンス

期待されるレスポンスは次の通りです。

確認結果

Delivery Profile に、作成した Mapping Function を使用するように設定しました。

パラメータを指定してみると、それぞれ正しくリサイズされた画像に変換されました！ファイルフォーマットがAVIFになっているので、ベース変換も効いていることが分かります。

• ?size=mediumの場合、w360xh240にフィットで 180x240 に変換

• ?width=400&height=400の場合、w400xh400にフィットで 300x400 に変換

以上、Cloudinary Media Optimizer の Mapping Function についてご紹介しました！特殊なパラメータ形式で変換を適用させたい場合にもこれで対応することができますね。

クラスメソッドはCloudinaryのパートナーとして導入のお手伝いをさせていただいています。お気軽にこちらからお問い合わせください。こちらから無料でもサインアップいただけます。

参考

• Cloudinary ドキュメント