Cloudinary は、画像や動画、その他のデジタルアセットを管理、変換・最適化、そして配信まですべてできる SaaS です。
今回はそのユーザ定義変数という機能を使ってみたのでご紹介します。
現在 Cloudinary で Named Transformation (t_) を使っている方は、一緒に活用することで可能性が広がるかもしれませんのでぜひご参考ください。
ユーザ定義変数とは？
User-defined variables (ユーザ定義変数) とは、名前の通りユーザが定義できる変数で、変換パラメータと同様に配信URLの中で指定して即座に適用させることができます。
変換でユーザー定義変数を使用するには、まず使用したい変数を宣言して値を代入します。連鎖変換の後のコンポーネントで、変数を変換パラメータの値として使用できます。 (ドキュメントより、DeepL 機械翻訳)
例えば、ある画像を横幅 270px にリサイズして配信する場合、Cloudinaryでは以下のようなパラメータ指定で即座に変換することができますが
https://res.cloudinary.com/demo/image/upload/w_270/path/to/file.jpg
これにユーザ定義変数を導入しても、同じ結果を取得することができます。
https://res.cloudinary.com/demo/image/upload/$imgwidth_270/w_$imgwidth/path/to/file.jpg
ここでは、imgwidth という名の変数を値 270 で宣言して、その後に変数を w_ 変換パラメータに指定しています。
https://res.cloudinary.com/demo/image/upload
/$imgwidth_270 ← 変数 imgwidth を 270 で宣言
/w_$imgwidth ← 横幅を指定する変換パラメータに変数を代入
/path/to/file.jpg ← アセットのパス動作はご理解いただけましたか？
これだけでは何が嬉しいかピンと来ないと思いますので、具体的な例を見てみましょう。
どんな時に必要？
ユーザ定義変数は、Named Transformation と一緒に使う際に本領を発揮します。
Named Transformation とは、変換パラメータの組み合わせに名前を付けて事前に登録しておくことで、複雑で長い変換もシンプルな名前で呼び出すことができる機能です。
例えば画像にウォーターマークを差し込む Named Transformation を t_wm と登録しておくとします。
設定した変換パラメータ：l_text:Arial_36:©Itoma,g_south_east,x_0.05,y_0.05,fl_relative
適用例：
https://res.cloudinary.com/demo/image/upload
/w_400,e_improve ← 横幅400pxへスケール、色彩調整
/t_wm ← 右下にウォーターマーク "©Itoma"
/mallorca.jpg
ここで、このウォーターマーク設定を生かしつつ、表示するテキストを事前設定した「Itoma」ではなく任意のものにしたい場合に、ユーザ定義変数が活用できます。
t_wm に変数 $name を導入して以下のように設定を変更します。そしてURL内で $name の値を宣言すると…
設定した変換パラメータ：l_text:Arial_36:©$(name),g_south_east,x_0.05,y_0.05,fl_relative
適用例：
https://res.cloudinary.com/demo/image/upload
/w_400,e_improve ← 横幅400pxへスケール、色彩調整
/$name_!CM%20Europe! ← 変数 name を "CM Europe" で宣言
/t_wm ← 設定した変数で右下にウォーターマーク
/mallorca.jpg
このように、Named Transformation を使いながら、その設定内容を都度変更しなくてもURLで即座に任意の値を指定できるのです。
具体的な仕様
利用イメージがついたところで、ここから具体的な使い方を説明します。
基本構文
変数の宣言はドルマーク $ で始まり、変数は任意のアルファベットから始まる英数字で、次にいわゆるイコールの役割を果たすアンダースコア _ が続き、その後に代入する値を指定します。
- 値が数字の場合：$var1_1234
- 値が文字列の場合：$var2_!text!（エクスクラメーション ! で囲む）
宣言した変数の利用は、ドルマークと変数名を通常の値の代わりに指定するだけです。
- 数字を指定する変換パラメータ：横幅 w、縦幅 h、座標値 x, y 、品質 q、アスペクト比 ar、透過 o、回転 a、角丸 r、枠瀬 bo の太さ、エフェクト e の適用度、if 構文内
- 例1: h_400 → $size_400/h_$size
- 例2: e_improve:50 → $strength_50/e_improve:$strength
- 文字列を指定する変換パラメータ：枠線 bo や背景 b の色、エフェクト e の名称、画像・テキストオーバーレイ l, u 、if 構文内
- 例1: e_improve → $effect_!improve!/e_$effect
- 例2: b_rgb:3e2222 → $color_!rgb:3e2222!/b_$color
- 例3: l_text:arial_10:hello world → $greeting_!hello!/l_text:arial_10:$(greeting) world（文字列の途中に入れる場合はカッコ $() で囲む）
その他の高度な機能
軽く触れますが、説明が長くなるので詳しくは各リンク先ドキュメントをご覧ください。
- 複数の文字列を値に宣言するにはセミコロン : で区切る（doc）
- ベースの画像自体を指定する値 “current“（doc）
- ベース画像の初期特性を示す初期縦横幅 iw, ih や顔の数 fc 等も値として利用可能（doc）
- さらに数式計算を組み合わせることも可能（doc）
URLで指定する際の注意点
- スラッシュ内でカンマ区切りで複数パラメータを指定する場合は順不同です。例えば変数の宣言を
/if_w_gt_5,w_$x,$x_5/と最後に置いても、Cloudinary が if 文 → $宣言 → wと正しく判断して適用してくれます。しかし、正しい順序でスラッシュで区切ることが本来勧められていて、 この例ではif_w_gt_5/$x_5/c_scale,w_$x/if_endがベストプラクティスに沿った記述です。 - 文字列内のスペースのような特殊文字は、%を用いたUTF8エンコーディングでエスケープする必要があります。ただし、Cloudinary SDK での実行や一部ブラウザのURL実行では自動でエンコーディングが行われます。
◆ 参考：テキストオーバーレイの特殊文字
その他のユースケース
◾️ ニュースサイトで最新の2つの記事には縦横 220px、過去の記事には縦横 100px で画像を変換させる
# 最新記事の配信URL
~/image/upload/$size_220/t_news_square/group.jpg
# 過去記事の配信URL
~/image/upload/$size_100/t_news_square/partners_table.jpg
# t_news_square の設定内容
c_fill,e_improve,g_auto:faces,z_0.7,q_auto,w_$size,h_$size◾️ 写真にグッド or バッドサインの画像を重ねる
# グッドサインの配信URL
~/image/upload/$rating_!thumbs-up!/t_image_ratings/log_cabin.jpg
# バッドサインの配信URL
~/image/upload/$rating_!thumbs-down!/t_image_ratings/victorian_room.jpg
# t_image_ratings の設定内容
c_fill,h_400,w_400/l_$rating/c_scale,w_100/fl_layer_apply,g_south_east,x_20,y_20◾️ 写真コンテストで名前とランクを表示させる
# 1位の配信URL
~/image/upload/$name_!Laura%20Howard!,$award_!First!/t_photo_contest/yellow_flower_bugs.jpg
# 2位の配信URL
~/image/upload/$name_!Jonathan%20Manchester!,$award_!Second!/t_photo_contest/yellow_flower_bugs.jpgURLだけでなく、それぞれのSDKでの指定の方法も載っていますので、詳しくは公式ブログとドキュメントをご参考ください。
以上、複雑な変換を事前登録できる Named Transformation を活用しつつも、ユーザ定義変数を使うことでアセットごとに柔軟に値を指定できることが分かりました。少しでも参考になれば幸いです！
クラスメソッドはCloudinaryのパートナーとして導入のお手伝いをさせていただいています。お気軽にこちらからお問い合わせください。こちらから無料でもサインアップいただけます。
2
