When uploading assets to your account, you can addoverwrite=false as part of the upload options, and this will perform the upload only if the asset doesn't exist, otherwise, the asset will not be re-uploaded and existing: true will be included in the upload response.
If you'd still like to check whether an asset exists on your account, here are a few options:
1. Perform a HEAD request for the resource.
Pros: Fast, not rate-limited.
Cons: May receive a cached version (the asset may actually not really exist in your account anymore).
To get an idea of how this works, here's a sample Ruby code for images:
def self.exists?(public_id, options={})
cloudinary_url = Cloudinary::Utils.cloudinary_url(public_id, options)
begin
code = RestClient::Request.execute(:method => :head, :url => cloudinary_url, :timeout => 5).code
code >= 200 && code < 300
rescue RestClient::ResourceNotFound
return false
end
end
Please note that when making a HEAD request for a resource, the bytes sent from the headers will count towards your bandwidth quota.
As for whether HEAD requests are counted towards transformation quotas:
- If the resource exists, then a HEAD request to that resource will not be counted as a transformation
- If the resource doesn't exist and the request returns a 404, a transformation will not be charged.
- If the resource didn't exist at first, and by the head request that resource "becomes" existent (e.g., in cases of fetch or auto-upload), then a transformation is counted exactly as any other first-time upload would. However all subsequent HEAD requests for that URL will not count as additional transformations.
2. Use the explicit method in the Upload API [documentation].
Pros: Not rate-limited, a definitive result (no chance of cached response).
Cons: Slower.
When calling the explicit method, all you have to pass in are the public_id , the type and the resource_type. If the asset exists, you will receive a result with the asset's data. If the asset doesn't exist, an exception will be thrown (when using one of our SDKs). Typically, the explicit method is used to apply actions to existing assets such as eagerly generating transformed versions of the assets, however here we are using it to check for the existence of an asset. Please refer to the example below using the Node.js SDK:
cloudinary.v2.uploader.explicit(public_id, {type: 'upload', resource_type: 'image'}).then((result, error) => console.log(result, error));3. Use the resource method in the Admin API [documentation].
Pros: Definitive result (no chance of cached response).
Cons: Slower, rate-limited.
This method behaves similarly to the explicit one in that it returns data if the asset exists and throws an exception if it doesn't (when using one of our SDKs). The only difference is that this method is rate-limited.
Comments
6 comments
An exception is not thrown by explicit() to a deleted image.
How to determine deleted or not?
Hi,
Thanks for reaching out.
In case the resource has a backup, the deleted image (i.e., the placeholder) will indeed come up in the explicit call. I went ahead and opened a feature request to handle this situation (return a placeholder=>true to indicate a deleted resource).
Please note that a HEAD request or using our Admin API's resource will give the correct result.
Hope it helps!
Best,
Maor
Hey all,
Happy to update that we now return the placeholder parameter when executing Explicit on a resource (similar to the way we return it in the upload response), as requested in this thread:)
Best regards,
Maor
While this is looking like a good solution it is actually harmful in some situations. One must not do this check right before uploading as it CACHES A 404 ERROR. One has to either skip such a check or make sure to delay the next call to the resourse, else the exponential error cache will lead to unexpected errors.
First of all: I am currently getting started with Cloudinary and everything seems very impressive so far.
But all these ways seem unsatisfying to me. I want to batch-upload files to Cloudinary and check if they have already been uploaded before but #1 seems unreliable and seems to cause a transformation (I guess partly because the just uploaded file has not been retrieved at all yet - although I don't intend to retrieve any actual binary data), #2 is meant for something completely different and #3 counts against my rate limit.
I didn't expect any hassle like this at all for such a basic action.
Hi Alexandar,
I'll be happy to assist with some clarifications.
Could you give more details on how you are uploading the files to Cloudinary? Specifically, are you using the Upload method and are you using one of the SDKs? Once we have the information, we can guide you on the exact steps with examples that will work for you.
Generally speaking, here are a few things that you can check:
* Ensure that the resource will have an exact unique public ID, either by specifying one (by setting the `public_id` parameter as part of the upload params, or by setting `use_filename=true`, and `unique_filename=false`. This will ensure that the file name on Cloudinary is the same as the file name you are uploading. If not, we'll create a random name/append random characters to make the file unique.
* While running the bulk upload script, set `overwrite=false`. This way, if the resource already exists, the file will not be re-uploaded.
Regarding HEAD requests and whether they'd be counted as a transformation:
I hope this helps
Please sign in to leave a comment.