Class: Uploadcare::Resources::File

Inherits:
BaseResource
  • Object
show all
Defined in:
lib/uploadcare/resources/file.rb

Overview

File resource representing an uploaded file in Uploadcare.

Provides both class methods (find, list, upload, batch operations, copy) and instance methods (store, delete, reload, convert) for working with files.

Examples:

Finding a file

client = Uploadcare.client
file = client.files.find(uuid: "file-uuid")
file.original_filename  # => "photo.jpg"

Uploading

client = Uploadcare.client
file = client.files.upload(::File.open("photo.jpg"), store: true)

See Also:

Constant Summary collapse

ATTRIBUTES =

API fields assigned onto file resources.

%i[
  datetime_removed datetime_stored datetime_uploaded is_image is_ready mime_type original_file_url
  original_filename size url uuid variations content_info metadata appdata source
].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#appdata ⇒ Object

Returns the value of attribute appdata.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def appdata
  @appdata
end

#content_info ⇒ Object

Returns the value of attribute content_info.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def content_info
  @content_info
end

#datetime_removed ⇒ Object

Returns the value of attribute datetime_removed.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def datetime_removed
  @datetime_removed
end

#datetime_stored ⇒ Object

Returns the value of attribute datetime_stored.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def datetime_stored
  @datetime_stored
end

#datetime_uploaded ⇒ Object

Returns the value of attribute datetime_uploaded.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def datetime_uploaded
  @datetime_uploaded
end

#is_image ⇒ Object

Returns the value of attribute is_image.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def is_image
  @is_image
end

#is_ready ⇒ Object

Returns the value of attribute is_ready.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def is_ready
  @is_ready
end

#metadata ⇒ Object

Returns the value of attribute metadata.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def metadata
  @metadata
end

#mime_type ⇒ Object

Returns the value of attribute mime_type.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def mime_type
  @mime_type
end

#original_file_url ⇒ Object

Returns the value of attribute original_file_url.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def original_file_url
  @original_file_url
end

#original_filename ⇒ Object

Returns the value of attribute original_filename.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def original_filename
  @original_filename
end

#size ⇒ Object

Returns the value of attribute size.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def size
  @size
end

#source ⇒ Object

Returns the value of attribute source.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def source
  @source
end

#url ⇒ Object

Returns the value of attribute url.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def url
  @url
end

#uuid ⇒ String?

Returns the file UUID, extracting from URL if needed.

Returns:

  • (String, nil) 


291
292
293
294
295
296
297
298
299
300
301
302
303
 
# File 'lib/uploadcare/resources/file.rb', line 291

def uuid
  return @uuid if @uuid

  source =
    if @url
      @url
    elsif uploadcare_cdn_url?(@original_file_url)
      @original_file_url
    end
  return @uuid unless source

  @uuid = source[/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/]
end

#variations ⇒ Object

Returns the value of attribute variations.



26
27
28
 
# File 'lib/uploadcare/resources/file.rb', line 26

def variations
  @variations
end

Class Method Details

.batch_delete(uuids:, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ Uploadcare::Collections::BatchResult

Batch delete files.

Parameters:

  • uuids (Array<String>) —

    File UUIDs to delete

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/uploadcare/resources/file.rb', line 150

def self.batch_delete(uuids:, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.batch_delete(uuids: uuids, request_options: request_options)
  )
  normalized = response.transform_keys(&:to_s)

  Uploadcare::Collections::BatchResult.new(
    status: normalized['status'],
    result: normalized['result'],
    problems: normalized['problems'] || {},
    client: resolved_client
  )
end

.batch_store(uuids:, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ Uploadcare::Collections::BatchResult

Batch store files.

Parameters:

  • uuids (Array<String>) —

    File UUIDs to store

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



128
129
130
131
132
133
134
135
136
137
138
139
140
141
 
# File 'lib/uploadcare/resources/file.rb', line 128

def self.batch_store(uuids:, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.batch_store(uuids: uuids, request_options: request_options)
  )
  normalized = response.transform_keys(&:to_s)

  Uploadcare::Collections::BatchResult.new(
    status: normalized['status'],
    result: normalized['result'],
    problems: normalized['problems'] || {},
    client: resolved_client
  )
end

.find(uuid:, params: {}, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ Uploadcare::Resources::File Also known as: retrieve, info

Find a file by UUID.

Parameters:

  • uuid (String) —

    File UUID

  • params (Hash) (defaults to: {}) —

    Optional parameters (e.g., include: "appdata")

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



40
41
42
43
44
45
46
 
# File 'lib/uploadcare/resources/file.rb', line 40

def self.find(uuid:, params: {}, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.info(uuid: uuid, params: params, request_options: request_options)
  )
  new(response, resolved_client)
end

.list(options: {}, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ Uploadcare::Collections::Paginated

List files with optional filtering and pagination.

Parameters:

  • options (Hash) (defaults to: {}) —

    Query parameters (limit, ordering, etc.)

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/uploadcare/resources/file.rb', line 60

def self.list(options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.list(params: options, request_options: request_options)
  )

  files = response['results'].map { |data| new(data, resolved_client) }

  Uploadcare::Collections::Paginated.new(
    resources: files,
    next_page: response['next'],
    previous_page: response['previous'],
    per_page: response['per_page'],
    total: response['total'],
    api_client: resolved_client.api.rest.files,
    resource_class: self,
    client: resolved_client,
    request_options: request_options
  )
end

.local_copy(source:, options: {}, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ Uploadcare::Resources::File Also known as: copy_to_local

Copy a file to local storage (class method).

Parameters:

  • source (String) —

    CDN URL or UUID

  • options (Hash) (defaults to: {}) —

    Optional parameters

Returns:



170
171
172
173
174
175
176
 
# File 'lib/uploadcare/resources/file.rb', line 170

def self.local_copy(source:, options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.local_copy(source: source, options: options, request_options: request_options)
  )
  new(response['result'], resolved_client)
end

.remote_copy(source:, target:, options: {}, client: nil, config: Uploadcare.configuration, request_options: {}) ⇒ String Also known as: copy_to_remote

Copy a file to remote storage (class method).

Parameters:

  • source (String) —

    CDN URL or UUID

  • target (String) —

    Custom storage name

  • options (Hash) (defaults to: {}) —

    Optional parameters

Returns:

  • (String) —

    URL of the copied file



188
189
190
191
192
193
194
195
196
197
 
# File 'lib/uploadcare/resources/file.rb', line 188

def self.remote_copy(source:, target:, options: {}, client: nil, config: Uploadcare.configuration,
                     request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  response = Uploadcare::Result.unwrap(
    resolved_client.api.rest.files.remote_copy(
      source: source, target: target, options: options, request_options: request_options
    )
  )
  response['result']
end

.upload(file, client: nil, config: Uploadcare.configuration, request_options: {}, **options) ⇒ Uploadcare::Resources::File

Upload a single file.

Parameters:

  • file (File, IO) —

    File to upload

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • options (Hash) —

    Upload options

Returns:



88
89
90
91
 
# File 'lib/uploadcare/resources/file.rb', line 88

def self.upload(file, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
  resolved_client = resolve_client(client: client, config: config)
  resolved_client.uploads.upload_file(file: file, request_options: request_options, **options)
end

.upload_many(files, client: nil, config: Uploadcare.configuration, request_options: {}, **options) ⇒ Array<Uploadcare::Resources::File>

Upload multiple files.

Parameters:

  • files (Array<File, IO>) —

    Files to upload

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • options (Hash) —

    Upload options

Returns:



100
101
102
103
 
# File 'lib/uploadcare/resources/file.rb', line 100

def self.upload_many(files, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
  resolved_client = resolve_client(client: client, config: config)
  resolved_client.uploads.upload_files(files: files, request_options: request_options, **options)
end

.upload_url(url, client: nil, config: Uploadcare.configuration, request_options: {}, **options) ⇒ Uploadcare::Resources::File Also known as: upload_from_url

Upload a file from URL.

Parameters:

  • url (String) —

    Source URL

  • client (Uploadcare::Client, nil) (defaults to: nil) —

    Client instance

  • config (Uploadcare::Configuration) (defaults to: Uploadcare.configuration) —

    Configuration fallback

  • options (Hash) —

    Upload options

Returns:



112
113
114
115
 
# File 'lib/uploadcare/resources/file.rb', line 112

def self.upload_url(url, client: nil, config: Uploadcare.configuration, request_options: {}, **options)
  resolved_client = resolve_client(client: client, config: config)
  resolved_client.uploads.upload_from_url(url: url, request_options: request_options, **options)
end

Instance Method Details

#cdn_url ⇒ String

Returns the CDN URL for this file.

Returns:

  • (String) 


308
309
310
311
312
313
314
 
# File 'lib/uploadcare/resources/file.rb', line 308

def cdn_url
  return @url if uploadcare_cdn_url?(@url)
  return @original_file_url if uploadcare_cdn_url?(@original_file_url)
  return nil unless uuid

  "#{config.cdn_base}#{uuid}/"
end

#convert_to_document(params: {}, options: {}, request_options: {}) ⇒ Uploadcare::Resources::File

Convert this file to a document format.

Parameters:

  • params (Hash) (defaults to: {}) —

    Conversion parameters (:format, etc.)

  • options (Hash) (defaults to: {}) —

    Optional parameters (:store, etc.)

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



274
275
276
 
# File 'lib/uploadcare/resources/file.rb', line 274

def convert_to_document(params: {}, options: {}, request_options: {})
  convert_file(params, Uploadcare::Resources::DocumentConversion, options, request_options: request_options)
end

#convert_to_video(params: {}, options: {}, request_options: {}) ⇒ Uploadcare::Resources::File

Convert this file to a video format.

Parameters:

  • params (Hash) (defaults to: {}) —

    Conversion parameters (:format, :quality, etc.)

  • options (Hash) (defaults to: {}) —

    Optional parameters (:store, etc.)

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



284
285
286
 
# File 'lib/uploadcare/resources/file.rb', line 284

def convert_to_video(params: {}, options: {}, request_options: {})
  convert_file(params, Uploadcare::Resources::VideoConversion, options, request_options: request_options)
end

#copy_to_local(options: {}, request_options: {}) ⇒ Uploadcare::Resources::File Also known as: local_copy

Copy this file to local storage.

Parameters:

  • options (Hash) (defaults to: {}) —

    Optional parameters

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:



244
245
246
247
248
249
 
# File 'lib/uploadcare/resources/file.rb', line 244

def copy_to_local(options: {}, request_options: {})
  response = Uploadcare::Result.unwrap(
    client.api.rest.files.local_copy(source: uuid, options: options, request_options: request_options)
  )
  self.class.new(response['result'], client)
end

#copy_to_remote(target:, options: {}, request_options: {}) ⇒ String Also known as: remote_copy

Copy this file to remote storage.

Parameters:

  • target (String) —

    Custom storage name

  • options (Hash) (defaults to: {}) —

    Optional parameters

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:

  • (String) —

    URL of the copied file



258
259
260
261
262
263
264
265
 
# File 'lib/uploadcare/resources/file.rb', line 258

def copy_to_remote(target:, options: {}, request_options: {})
  response = Uploadcare::Result.unwrap(
    client.api.rest.files.remote_copy(
      source: uuid, target: target, options: options, request_options: request_options
    )
  )
  response['result']
end

#delete(request_options: {}) ⇒ self

Delete this file.

Parameters:

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:

  • (self) 


219
220
221
222
223
 
# File 'lib/uploadcare/resources/file.rb', line 219

def delete(request_options: {})
  response = Uploadcare::Result.unwrap(client.api.rest.files.delete(uuid: uuid, request_options: request_options))
  assign_attributes(response)
  self
end

#reload(params: {}, request_options: {}) ⇒ self Also known as: load

Reload file information from the API.

Parameters:

  • params (Hash) (defaults to: {}) —

    Optional parameters

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:

  • (self) 


230
231
232
233
234
235
236
 
# File 'lib/uploadcare/resources/file.rb', line 230

def reload(params: {}, request_options: {})
  response = Uploadcare::Result.unwrap(
    client.api.rest.files.info(uuid: uuid, params: params, request_options: request_options)
  )
  assign_attributes(response)
  self
end

#store(request_options: {}) ⇒ self

Store this file, making it permanently available.

Parameters:

  • request_options (Hash) (defaults to: {}) —

    Request options

Returns:

  • (self) 


209
210
211
212
213
 
# File 'lib/uploadcare/resources/file.rb', line 209

def store(request_options: {})
  response = Uploadcare::Result.unwrap(client.api.rest.files.store(uuid: uuid, request_options: request_options))
  assign_attributes(response)
  self
end