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 tags appdata source highlight
].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

#highlight ⇒ Object

Returns the value of attribute highlight.



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

def highlight
  @highlight
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

#tags ⇒ Object

Returns the value of attribute tags.



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

def tags
  @tags
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) 


299
300
301
302
303
304
305
306
307
308
309
310
311
 
# File 'lib/uploadcare/resources/file.rb', line 299

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:



158
159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/uploadcare/resources/file.rb', line 158

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:



136
137
138
139
140
141
142
143
144
145
146
147
148
149
 
# File 'lib/uploadcare/resources/file.rb', line 136

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:

  • (Uploadcare::Resources::File) 


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:



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/uploadcare/resources/file.rb', line 55

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:

  • (Uploadcare::Resources::File) 


178
179
180
181
182
183
184
 
# File 'lib/uploadcare/resources/file.rb', line 178

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



192
193
194
195
196
197
198
199
200
201
 
# File 'lib/uploadcare/resources/file.rb', line 192

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

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

Search files with full-text criteria and structured filters.

limit, offset, and include are sent as query parameters. All other options are sent in the JSON request body as search criteria.

Parameters:

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

    Search criteria plus pagination/expansion options

  • 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:



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

def self.search(options: {}, client: nil, config: Uploadcare.configuration, request_options: {})
  resolved_client = resolve_client(client: client, config: config)
  Uploadcare::Operations::FileSearch.call(
    options: options, client: resolved_client, resource_class: self, request_options: request_options
  )
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:

  • (Uploadcare::Resources::File) 


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

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:

  • (Array<Uploadcare::Resources::File>) 


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

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:

  • (Uploadcare::Resources::File) 


124
125
126
127
 
# File 'lib/uploadcare/resources/file.rb', line 124

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) 


316
317
318
319
320
321
322
 
# File 'lib/uploadcare/resources/file.rb', line 316

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:

  • (Uploadcare::Resources::File) —

    The converted file



282
283
284
 
# File 'lib/uploadcare/resources/file.rb', line 282

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:

  • (Uploadcare::Resources::File) —

    The converted file



292
293
294
 
# File 'lib/uploadcare/resources/file.rb', line 292

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:

  • (Uploadcare::Resources::File) —

    The copied file



252
253
254
255
256
257
 
# File 'lib/uploadcare/resources/file.rb', line 252

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



266
267
268
269
270
271
272
273
 
# File 'lib/uploadcare/resources/file.rb', line 266

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) 


227
228
229
230
231
 
# File 'lib/uploadcare/resources/file.rb', line 227

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) 


238
239
240
241
242
243
244
 
# File 'lib/uploadcare/resources/file.rb', line 238

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) 


217
218
219
220
221
 
# File 'lib/uploadcare/resources/file.rb', line 217

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