この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
画像や動画の変換や最適化、管理が簡単にできる SaaS、Cloudinary 。その配信 URL にはバージョンが含まれることがあります。
このバージョンをどうするかは、Cloudinary 導入時に決めるべき大事な構成の一つなので、きちんと理解していただきたいです。
Cloudinary の配信 URL （おさらい）
Cloudinaryの配信URLは下記のような構成です。
https://res.cloudinary.com/[クラウド名]/[リソースタイプ]/[タイプ]/[署名]/[変換パラメータ]/[バージョン]/[パブリックID].[フォーマット]
◆詳しくはこちらのブログを参照してください。
変換パラメータの後、パブリックIDの前に「バージョン」がありますね。
バージョンとは
これは何のバージョンかというと、同じ名前でファイルを更新した場合を想定して使われる、URL のバージョンです。
vと数字を組み合わせた形式で、デフォルトではファイルの更新時間のUNIXタイムスタンプの数字が続きます。
例えば以下の img1 について、最初に画像をアップロードしたのは “Created” の表示にある 2021年7月20日 ですが、別の画像に置き換えました。それが、”Last replaced” の表示にある2022年5月12日です。この Media Library 上でコピーした画像リンクは、以下のようになっています。
https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652343795/travel/img1.jpg
このうちv1652343795がバージョンで、エポック秒の1652343795を変換すると 2022年5月12日 10:23:15 、更新日時を示すことが分かります。
配信URLにおけるバージョン項目は任意です。
URLに初めてアクセスする場合、この数字の値がなんであっても、あるいはバージョン項目がなくても、配信される結果には変わりありません。
バージョンはなぜ必要？
バージョンを含めなくても配信できるなら余計な項目は入れたくないと思うでしょう。
しかし、バージョンを使用することは推奨されています。
先ほどの例で、画像を更新する前と後の画像URLはそれぞれ次のようになります。
バージョンを使う場合はこのようにURLが異なるので、ウェブサイト上のURLを差し替え、ユーザは新規URLにアクセスすることになります。
# 更新前の画像URL（既存URL）
https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652343795/travel/img1.jpg
# 更新後の画像URL（新規URL）
https://res.cloudinary.com/CLOUD-NAME/image/upload/v1626788112/travel/img1.jpg一方でバージョンを使わない場合、次のように、Cloudinary 側の画像を更新した後も配信済みのURLと全く同じものを使うことになります。
# 更新前後とも同じ画像URL
https://res.cloudinary.com/CLOUD-NAME/image/upload/travel/img1.jpgこれにより、古い画像のキャッシュが残っていると、同じURLを使う場合は更新後の画像を直ちに配信することができません。
Cloudinary CDN のキャッシュは Cloudinary から無効化することもできますが、環境によっては他にも中間キャッシュがあり、より複雑な可能性があります。
バージョンを使えば、新しいURLでキャッシュを気にせずただちに更新した画像を配信させることができるのです。
ここで勘違いしてはならないのが、古いバージョン番号のURLでその古い画像にいつまでもアクセスできるというわけではないということです。キャッシュが切れたら、古い画像はCloudinaryにはもう存在しないので、既存URLも更新後の画像を返すようになります。 1
バージョン項目は、あくまで異なるURLを発行してキャッシュを避けるためのものです。
Cloudinary で扱われるバージョンの形式
上の説明からすると、長い数字でなくても、v1、v2でいいじゃないかと思われるでしょう。
はい、それでもただちに更新画像を配信するという目的は達成されます。
ですが、やはり Cloudinary で使われるデフォルトのバージョン形式に従うべきです。
利用環境が "surrogate key invalidation” に対応していないアカウントの場合には、キャッシュ無効化の対象にも関連する（以下、レガシーと表記）ので、後述3つのオプションのいずれかで検討する必要があります。
? Surrogate key invalidation とは
API キャッシュ無効化を実行する際に、パブリックIDを指定すると関連するすべてのURLのキャッシュが無効化されます。2020年にCloudinaryで導入された機能で、2020年12月以降に作成されたアカウントでは必ず対応しています。
本機能が無効の場合は、特定形式のバージョンのURLしかキャッシュが無効化されません。
アカウントで本機能が有効かどうかは、サポートへ確認してください。
- オプション１：フォルダ配下は v1 、ルート直下はバージョンなし
- APIで画像URLを取得した場合に出力される形式
- (レガシー) この形式を使う場合、設定「Invalidate versioned URLs」に Disabled を選択（デフォルト）
- オプション２：すべてのアセットで、バージョンなし
- (レガシー) この形式を使う場合、サポートヘ依頼（設定「Invalidate versioned URLs」は無効化され、非表示となる）
- オプション３：すべてのアセットで、最新のフルバージョン（更新日時のUNIX時間）
- APIで画像アップロード時や詳細取得時のレスポンス、および Media Library で画像URLを取得した場合の形式
- (レガシー) この形式を使う場合、設定「Invalidate versioned URLs」に Enabled を選択
現時点でAPI やコンソールで出力される URL のバージョン形式は変更することができません。
以下、Python API で実行した場合の例です。
# オプション１の例：画像URLを取得（フォルダ配下）
>>> cloudinary.CloudinaryImage("samples/cloudinary-group.jpg").image(
... height=60,
... quality="auto",
... secure=True)
'<img height="60" src="https://res.cloudinary.com/mai-ito-test/image/upload/h_60,q_auto/v1/samples/cloudinary-group.jpg"/>'
# オプション１の例：画像URLを取得（ルート直下）
>>> cloudinary.CloudinaryImage("sample.jpg").image(
... height=60,
... quality="auto",
... secure=True)
'<img height="60" src="https://res.cloudinary.com/mai-ito-test/image/upload/h_60,q_auto/sample.jpg"/>'
# オプション３の例：画像アップロード
>>> cloudinary.uploader.upload(
... "image.png",
... public_id="fol1/test"
... )
{'asset_id': '1d93a06d32f8ac5980de476f783c33a6', 'public_id': 'test1/test.png', 'version': 1652729753, 'version_id': '79789f0e692211b649bf6f244eaae5f5', 'signature': 'd86f56e8e486fa306c8473be09a13430a114b01c', 'width': 128, 'height': 128, 'format': 'png', 'resource_type': 'image', 'created_at': '2022-05-16T19:35:53Z', 'tags': [], 'bytes': 6132, 'type': 'upload', 'etag': '24e299e6a25c86bff939cd09e20e700c', 'placeholder': False, 'url': 'http://res.cloudinary.com/CLOUD_NAME/image/upload/v1652729753/fol1/test.png', 'secure_url': 'https://res.cloudinary.com/CLOUD-NAME/image/upload/v1652729753/fol1/test.png', 'folder': 'fol1', 'access_mode': 'public', 'original_filename': 'image', 'api_key': '123456789012345'}
>>>補足: レガシー環境
Surrogate key invalidation が有効でないアカウントにおいては、APIでキャッシュ無効化（invalidate=true オプション、explicit）を実行した際、 Settings > Upload > 「Invalidate versioned URLs」の設定に基づいて、キャッシュ無効化されるオプションが決まります。
（Media Library での更新・削除時はすべての関連URLのキャッシュが無効化されます。）
設定が Disabled（デフォルト）の場合、以下の通りオプション１の形式のURLのみキャッシュが削除されます。
- 無効化される:
https://~/image/upload/sample.jpghttps://~/image/upload/v1/folder1/sample.jpg
- 無効化されない:
https://~/image/upload/sample.jpg(オプション２のため)https://~/image/upload/v1/sample.jpg(いずれのオプションにも該当しないため)https://~/image/upload/v1593602134/sample.jpg(オプション３のため)
また、署名付きURLのキャッシュ無効化を有効にしたい場合、サポートへの問い合わせが必要です。
FAQ
Q. バージョン情報は含めなくてもよいか？
A. バージョン値がどの数字でも、あるいはなくても、配信することは可能です。
ですが、同じファイル名で画像が更新される可能性がある場合には、バージョンを使うことが推奨されています。
（例えば、バージョンなしのURLで画像Aに一度アクセスすると、同じ名前で画像Bに差し替えても、画像Aのキャッシュが残るため、URLは古い画像Aを表示し続けます。このため、画像Bを表示させるには、アップロード日時に応じたバージョンを含む新しいURLにアクセスするか、APIでアップロード時にキャッシュ消去するオプションを付与する必要があります。）
Q. コンソールでコピーするリンクやAPIの出力結果で、バージョン項目を含めないようにすることができるか？
A. APIやコンソールで出力されるURLについては、現時点で設定でコントロールできず、バージョン値を含まないURLを出力させることはできません。
コンソールやAPIで画像URLを発行すると、前述のオプション１と３のように場合によって自動的にバージョンが含まれてしまうため、不要な場合は手動でバージョン値を取り除いてください。
おしまい
Cloudinaryに限らず、バージョンを使ってURLを更新する手法は一般的に推奨されています。
バージョン管理されたURLはキャッシュストラテジに役立ちます。バージョン管理されたURLは、キャッシュに保存された応答を簡単に無効化できるため、優れた方法です。（参考：HTTPキャッシュを使用して不要なネットワーク要求を防ぐ）
同じパブリックID（フォルダ・ファイル名）で画像を更新するというユースケースがある場合、基本的にオプション３に従うことがベストです。
また、URLを固定したい場合でも、Cloudinaryの処理を正常に行わせるために、オプション１を選択するのが無難で安全といえます。
42
