If you need to update an existing transformation, the simplest solution is to either create a new named transformation with a different name or to use dynamic transformations.
If you still want to keep the current transformation's name, then:
- For transformations with less than 1000 images associated with this transformation, use our management console (or Delete transformation Admin API) to delete the current transformation, including associated derived images, and create a new one under the same name.
- For transformations with more than 1000 images associated with this transformation, use our Update transformation Admin API to update the transformation, but the new settings will only be applied to newly generated images.
- Here are two examples:
-
Cloudinary::Api.update_transformation("my_named_transformation", :unsafe_update=>{"crop"=>"scale", "width"=>103}) -
Cloudinary::Api.update_transformation("my_named_transformation", :unsafe_update=>[ {"crop"=>"scale", "width"=>103}, {:overlay => "badge", :gravity => :north} ])
-
- Here are two examples:
The ":unsafe_update" parameter updates a named transformation parameter without regenerating existing images so if you choose to keep the same name, only newly transformed images will use the updated transformation.
To update the existing derived assets, you can use the regen_derived command from our CLI SDK which takes a transformation string and invalidates all derived assets using it. To use it, install the SDK or update it to the latest version and then follow the instructions in the CLI documentation.
Please note that the regen_derived command does not check if your named transformation is being used with other transformations, so it will only regenerate the derived assets for the exact name you pass it.
However, you can use the "cld admin transformations" command to search for all the relevant transformation strings and pass it to the regen_derived command which can be easily automated via bash or similar.
Alternatively, you can also find all existing transformation strings in the Transformation Log in the Console.
NOTE: This command invalidates assets based on URL patterns, so if you’re using a non-default delivery URL pattern, we may need to adjust your account settings. See invalidating cached assets docs and CDN Invalidations article for detailed information regarding this.
You can also write your custom solution based on one of the two methods described below; both of them use URL patterns for invalidation so the above invalidation note applies to them as well:
Method 1: Using the explicit upload API to eagerly overwrite and generate a new derived (recommended):
- Use the Get transformations API and find all transformations that are using the named transformation in its string and save the name field from the response. Oftentimes, a named transformation is used in combination with other dynamic transformations (e.g. t_named,f_auto) so it is essential to find the exact string so that all the relevant derived versions can be targeted. Also, ensure you are not setting the parameter named=true as we will need to search both named and dynamic transformations.
- Use Get transformations details API with the names from step 1 to get all the assets using those transformations and save the public_id, type and resource_type and the transformation string fields
- Use explicit API by specifying the public_id, type, resource_type and eager param as the transformation string from step 2. Make sure to pass eager_async=true, invalidate=true, overwrite=true and eager_notification_url (optional) as well so you get notified when the regeneration is complete
NOTE: The upload API has no rate limit but steps 1 and 2 are subject to the Admin API rate limit. Regenerating the derived assets will increase your account's transformation usage, so you may wish to spread these updates over a longer time period to avoid spikes in usage.
Method 2: Using the Admin API to delete the derived:
- Follow steps 1 and 2 from the first method
- Use Delete resources API with results from step 2 by specifying the public_id, type, resource_type, transformations and keep_original=true. You can also include multiple transformation strings in the transformations param, just separate them by a pipe character (e.g. transformations="t_one|t_two")
- Include invalidate=true to invalidate the CDN cache, this is only required if you need the derived deleted from the cache immediately. By default, the invalidate parameter does not work with Admin API so let us know if this is the case by opening a ticket and we can enable it for you
NOTE: All the APIs mentioned above are part of the Admin API which is rate-limited so ensure you are within your hourly limits or else all Admin API calls will be blocked until the top of the next hour. This method is recommended if the derived assets won't need to be re-generated because they're not actively in use.
Comments
8 comments
Could we get examples in other languages?
this doesn't seem to work:
cloudinary.api.update_transformation('name_transformation', unsafe_update={'format':'jpg'})
Here are some code references in the various client libraries:
Node.js:
https://github.com/cloudinary/cloudinary_npm/blob/fb2448e5b1bbce476d2646c42ff906aeb08a25d8/test/api.coffee#L266
Python:
https://github.com/cloudinary/pycloudinary/blob/fefb6f8a6696e0fe59670f49ad8801954bb88fc0/tests/api_test.py#L206
PHP:
https://github.com/cloudinary/cloudinary_php/blob/135eb8465cd6c37a07e6f5314ad4b125d1062840/tests/ApiTest.php#L284
.NET:
https://github.com/cloudinary/CloudinaryDotNet/blob/071a91e5f1f0fc80cdddee5b4072c8bac030e219/Cloudinary.Test/CloudinaryTest.cs#L1341
Java:
https://github.com/cloudinary/cloudinary_java/blob/87df64e10cb70a520fc0407aa97a22db8031a0ce/cloudinary-core/src/test/java/com/cloudinary/test/ApiTest.java#L328
Hi guys - clearly this demonstrates room for improvement!
To be honest, I was always under the impression, I could save a named transformation, use the named transformation in the URL for images used for instance on a Android APP, then if required, I could just edit it in the Cloudinary Management Console > Media Transformations to make changes, modifications or updates, and see those changes come through the next time the image is requested.
This is a bit of a repeat of above... But for example, we create a named transformation using 100% quality and use it in the APP. After launching the APP we decide images for the APP need to be displayed at 50% quality instead. Instead of having to dev/update the APP and release an update, notify customers, etc etc, how wonderful would it be to just be able to edit the named transformation settings (which are there to be used) in the Cloudinary Management Console > Media Transformations, and see the changes come through live?!
Having the "Invalidate - True" option in the Named Transformation settings, would probably help no?
Hi Marcos,
Thank you very much for providing this feedback!
The current limit of 1000 images when updating a named transformation is to:
Please let us know if you have any additional questions.
Regards,
Millie
Hi Mille - but what if the new transformations are necessary, such as a adding a new watermark to all images? If we created a new transformation to cover this, we would end up affecting the quote anyway, in addition having to edit/dev/release the APP. Regarding the account quota, well that really should only be an issue if it's not clear to the user, and if they do not have enough credits (in our case we are are conscious would have enough), and this would also be the case when making the derived images resources available immediately, where we would obviously expect an initial slight delay loading new images the first time.
Nevertheless, I still think having the option to purge all previous transformations for an edited named transformation, would cover the points above.
@Marcos
I definitely agree, it's something that can be improved.
In the meantime, if you do update the named transformation, I can gather a list of assets that use that named transformations and invalidate those assets specifically. If you want, you can open a ticket internally with us and we can discuss it further.
Great - I will keep that in mind when we do require any changes to named transformations.
Looking forward to seeing this improved functionality for the user.
Please sign in to leave a comment.