Cloudinary の Named Transformation の派生アセット数を調べるには

Cloudinary の Named Transformation の派生アセット数を調べるには

Cloudinary にて、特定の Named Transformation に紐づくすべての派生アセット（derived assets）を確認する方法をご紹介します。
#Cloudinary
#SaaS
Ito maIto ma
facebookのロゴhatenaのロゴtwitterのロゴ
2024.03.04

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

今回のブログでは、特定の Named Transformation を使う派生アセット（すでに生成された変換画像/動画）の件数や対象を調べる方法をご紹介します。

なぜ派生アセット数を調べる必要があるのか？

Named Transformationの定義を更新する際、紐づく派生アセットが1000件以上かどうかで更新方法が大きく変わります。

  • 1000件未満：コンソールでの更新が可能、自動で派生アセット削除
  • 1000件以上：APIでの更新のみ、手動で派生アセット削除が必要

そのため、更新前に派生アセット数を正確に把握することが重要です。

▼ Named Transformation の更新について詳しくは： https://support.cloudinary.com/hc/en-us/articles/202521272-How-can-I-update-a-named-transformation

その他、検証環境や何か不具合があった場合に紐づくアセットを調べたい場合にも、今回のスクリプトが活用できます。

単純な API コマンド実行では不十分な理由

以前のブログの「特定変換を使う派生画像」でやっているように Admin APIのtransformationメソッドを使えば、特定の Named Transformation の派生アセットを取得できます。

res = cloudinary.api.transformation("t_cm_wm_colors", max_results=500)
dvs = res['derived']

# [{'bytes': 68971,
#   'format': 'jpg',
#   'id': '7b11e699fbb0a291d052646969bbe001',
#   'public_id': 'ito-test/travel/img4',
#   'resource_type': 'image',
#   'secure_url': 'https://res.cloudinary.com/CLOUD-NAME/image/upload/t_cm_wm_colors/v1626788147/ito-test/travel/img4.jpg',
#   'type': 'upload',
#   'url': 'http://res.cloudinary.com/CLOUD-NAME/image/upload/t_cm_wm_colors/v1626788147/ito-test/travel/img4.jpg'}]

しかし、この方法には大きな制限があります：指定した変換そのものしか検索できないため、例えば以下のような複合変換は対象外になってしまいます：

  • t_cm_wm_colors,q_auto,f_auto
  • w_200,t_cm_wm_colors
  • t_cm_wm_colors/f_auto

つまり、実際の運用で使われている派生アセットの一部しか把握できません。

完全な派生アセット数を調査する3ステップ

特定の変換を使うすべての派生アセットを調べるには、次のように工夫する必要があります。

  1. 環境内でこれまでに使われたすべての変換パラメータを取得する（例「f_auto,q_auto」「t_cm_wm_colors」「t_cm_wm_colors,q_auto,f_auto」等々）
  2. 1のうち、特定の変換およびそれを含むものだけを抽出する（例「t_cm_wm_colors」「t_cm_wm_colors,q_auto,f_auto」等）
  3. 抽出した変換パラメータそれぞれに対して、派生アセットを取得（前述の transformation メソッドを使う）し、リストにまとめる

STEP1: 環境内のすべての変換パラメータを取得

# 環境内で使われたすべての変換パラメータを取得
res = cloudinary.api.transformations(named=False, max_results=500)
params = [t['name'] for t in res['transformations']]

# ページネーション処理
while res.get("next_cursor"):
    res = cloudinary.api.transformations(max_results=500, next_cursor=res['next_cursor'])
    params += [t['name'] for t in res['transformations']]

ポイント：

  • named=False：Named Transformationではない変換パラメータのみを取得（例:「t_cm_wm_colors」は該当せず「t_cm_wm_colors,q_auto,f_auto」は結果に該当）
  • max_results + next_cursor：Cloudinary の API で一般的に使われる大量データ取得用のページネーション処理

⚠️ 注意： 大規模環境では、ループ数が増えるため Admin APIのレートリミットに達する可能性があります。

STEP2: 対象のNamed Transformationを含む変換のみを抽出

named_transformation = "t_cm_wm_colors"

# 正規表現で精密にフィルタリング
filtered_params = [param for param in params if re.search(r'(,|/|^)' + re.escape(trn_name) + r'($|,|/)', param)]

# 対象の Named Transformation 自体も追加
filtered_params.append(named_transformation)

なぜ正規表現を使うのか？ 単純な文字列検索だと、t_cm_wm_colors_hogeのような部分一致で別の変換も誤って抽出してしまうためです。

💡 抽出結果の例：

>>> print(filtered_params)
['w_200,t_cm_wm_colors', 't_cm_wm_colors,w_200', 't_cm_wm_colors']

STEP3: 各変換パラメータの派生アセットを取得・集計

dvs_list = {}

for trn_param in filtered_params:
    # 取得した変換それぞれの派生アセットを取得
    res = cloudinary.api.transformation(trn_param, max_results=500)
    dvs = res['derived']

    # ページネーション処理
    while res.get("next_cursor"):
        res = cloudinary.api.transformation(named_transformation, max_results=500, next_cursor=res['next_cursor'])
        dvs += res['derived']

    # リストに格納
    dvs_list[trn_param] = dvs

ここでようやく 、冒頭の transformationメソッドを実行します。

結果の確認

今回の例では、3つのパラメータに計5件の派生アセットがあることが分かります。

# Named Transformation を使う変換パラメータの数
>>> len(dvs_list)
3

# 派生アセットの総数
>>> sum(len(dvs) for dvs in dvs_list.values())
5

# 派生アセットの内容抜粋
>>> pprint(dvs_list)
{'t_cm_wm_colors': [{'bytes': 68971,
                     'format': 'jpg',
                     'id': '7b11e699fbb0a291d052646969bbe001',
                     'public_id': 'ito-test/travel/img4',
                     'resource_type': 'image',
                     'secure_url': 'https://res.cloudinary.com/demo/image/upload/t_cm_wm_colors/v1626788147/ito-test/travel/img4.jpg',
                     'type': 'upload',
                     'url': 'http://res.cloudinary.com/demo/image/upload/t_cm_wm_colors/v1626788147/ito-test/travel/img4.jpg'},
                    {'bytes': 372403,
                     'format': 'jpg',
                     'id': '77420cd56903954bc3525db0fe8424f3',
                     'public_id': 'ito-test/bikee',
                     'resource_type': 'image',
                     'secure_url': 'https://res.cloudinary.com/demo/image/upload/t_cm_wm_colors/v1622648607/ito-test/bikee.jpg',
                     'type': 'upload',
                     'url': 'http://res.cloudinary.com/demo/image/upload/t_cm_wm_colors/v1622648607/ito-test/bikee.jpg'},
                    {...(中略)...}],
 't_cm_wm_colors,w_200': [{'bytes': 5662,
                           'format': 'jpg',
                           'id': '03c23d8ca7511d5e3c60487cdc700173',
                           'public_id': 'ito-test/travel/img4',
                           'resource_type': 'image',
                           'secure_url': 'https://res.cloudinary.com/demo/image/upload/t_cm_wm_colors,w_200/v1626788147/ito-test/travel/img4.jpg',
                           'type': 'upload',
                           'url': 'http://res.cloudinary.com/demo/image/upload/t_cm_wm_colors,w_200/v1626788147/ito-test/travel/img4.jpg'}],
 'w_200,t_cm_wm_colors': [{...中略...}]}

完全なスクリプト例

まとめると、以下の通りです。

# STEP1: 全変換パラメータを取得
res = cloudinary.api.transformations(named=False, max_results=500)
params = [t['name'] for t in res['transformations']]

while res.get("next_cursor"):
    res = cloudinary.api.transformations(max_results=500, next_cursor=res['next_cursor'])
    params += [t['name'] for t in res['transformations']]

# STEP2: 対象のNamed Transformationを含む変換を抽出
named_transformation = "t_cm_wm_colors"
filtered_params = [param for param in params
                  if re.search(r'(,|/|^)' + re.escape(trn_name) + r'($|,|/)', param)]
filtered_params.append(named_transformation)

# STEP3: 各変換の派生アセットを取得・集計
dvs_list = {}
for trn_param in filtered_params:
    res = cloudinary.api.transformation(trn_param, max_results=500)
    dvs = res['derived']
    while res.get("next_cursor"):
        res = cloudinary.api.transformation(named_transformation, max_results=500, next_cursor=res['next_cursor'])
        dvs += res['derived']
    dvs_list[trn_param] = dvs


以上、ご参考になれば幸いです！

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

この記事をシェアする

facebookのロゴhatenaのロゴtwitterのロゴ

関連記事

Cloudinary MCP Server発表！ DevIOブログのアイキャッチを自然言語で作ってみたCloudinary MCP Server発表！ DevIOブログのアイキャッチを自然言語で作ってみた
小西諒
2025.07.02
これから始める Cloudinary：画像アップロードから URL 加工までノーコードで体験これから始める Cloudinary：画像アップロードから URL 加工までノーコードで体験
CloudinaryのデータをAmazon S3に自動バックアップするCloudinaryのデータをAmazon S3に自動バックアップする
小西諒
2025.01.29
Cloudinaryが何を解決するのかCloudinaryが何を解決するのか
クラスメソッドの白いロゴ
Facebookのロゴ
Xのロゴ
YouTubeのロゴ

© Classmethod, Inc. All rights reserved.