Module: Azure::Storage::File

Includes:
Common::Service
Included in:
FileService
Defined in:
file/lib/azure/storage/file/file.rb,
file/lib/azure/storage/file/share.rb,
file/lib/azure/storage/file/default.rb,
file/lib/azure/storage/file/version.rb,
file/lib/azure/storage/file/autoload.rb,
file/lib/azure/storage/file/directory.rb,
file/lib/azure/storage/file/file_service.rb,
file/lib/azure/storage/file/serialization.rb

Defined Under Namespace

Modules: Default, Directory, FileConstants, FileErrorCodeStrings, Serialization, Share Classes: File, FileService, Version

Constant Summary collapse

StorageService = 
Azure::Storage::Common::Service::StorageService

Instance Method Summary collapse

Instance Method Details

#abort_copy_file(share, directory_path, file, copy_id, options = {}) ⇒ Object

Public: Aborts a pending Copy File operation and leaves a destination file with zero length and full metadata.

Attributes

  • share - String. The name of the destination file share.

  • directory_path - String. The path to the destination directory.

  • file - String. The name of the destination file.

  • copy_id - String. The copy identifier returned in the copy file operation.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/abort-copy-file

Returns nil on success



607
608
609
610
611
612
613
614
615
616
617
618
 
# File 'file/lib/azure/storage/file/file.rb', line 607

def abort_copy_file(share, directory_path, file, copy_id, options = {})
  query = { "comp" => "copy" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
  StorageService.with_query query, "copyid", copy_id

  uri = file_uri(share, directory_path, file, query);
  headers = {}
  StorageService.with_header headers, "x-ms-copy-action", "abort";

  call(:put, uri, nil, headers, options)
  nil
end

#clear_file_range(share, directory_path, file, start_range, end_range = nil, options = {}) ⇒ Object

Public: Clears a range of file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • start_range - Integer. Position of first byte of the range.

  • end_range - Integer. Position of last byte of of the range.

  • options - Hash. A collection of options.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/put-range

Returns a File



337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
 
# File 'file/lib/azure/storage/file/file.rb', line 337

def clear_file_range(share, directory_path, file, start_range, end_range = nil, options = {})
  query = { "comp" => "range" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = file_uri(share, directory_path, file, query)
  start_range = 0 if !end_range.nil? && start_range.nil?

  headers = {}
  StorageService.with_header headers, "x-ms-range", "bytes=#{start_range}-#{end_range}"
  StorageService.with_header headers, "x-ms-write", "clear"

  response = call(:put, uri, nil, headers, options)

  result = Serialization.file_from_headers(response.headers)
  result.name = file
  result
end

#copy_file(destination_share, destination_directory_path, destination_file, source_share, source_directory_path, source_file, options = {}) ⇒ Object

Public: Copies a source file to a destination file within the same storage account.

Attributes

  • destination_share - String. The destination share name to copy to.

  • destination_directory_path - String. The path to the destination directory.

  • source_file - String. The destination file name to copy to.

  • source_share - String. The source share name to copy from.

  • source_directory_path - String. The path to the source directory.

  • source_file - String. The source file name to copy from.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :metadata - Hash. Custom metadata values to store with the copy. If this parameter is not

    specified, the operation will copy the source file metadata to the destination
file. If this parameter is specified, the destination file is created with the
specified metadata, and metadata is not copied from the source file.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/copy-file

Returns a tuple of (copy_id, copy_status).

  • copy_id - String identifier for this copy operation. Use with get_file or get_file_properties to check

    the status of this copy operation, or pass to abort_copy_file to abort a pending copy.

  • copy_status - String. The state of the copy operation, with these values:

    "success" - The copy completed successfully.
"pending" - The copy is in progress.


581
582
583
584
585
 
# File 'file/lib/azure/storage/file/file.rb', line 581

def copy_file(destination_share, destination_directory_path, destination_file, source_share, source_directory_path, source_file, options = {})
  source_file_uri = file_uri(source_share, source_directory_path, source_file, {}).to_s

  return copy_file_from_uri(destination_share, destination_directory_path, destination_file, source_file_uri, options)
end

#copy_file_from_uri(destination_share, destination_directory_path, destination_file, source_uri, options = {}) ⇒ Object

Public: Copies a source file or file to a destination file within the storage account.

Attributes

  • destination_share - String. The name of the destination file share.

  • destination_directory_path - String. The path to the destination directory.

  • destination_file - String. The name of the destination file.

  • source_uri - String. The source file or file URI to copy from.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :metadata - Hash. Custom metadata values to store with the copy. If this parameter is not

    specified, the operation will copy the source file metadata to the destination
file. If this parameter is specified, the destination file is created with the
specified metadata, and metadata is not copied from the source file.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/copy-file

Returns a tuple of (copy_id, copy_status).

  • copy_id - String identifier for this copy operation. Use with get_file or get_file_properties to check

    the status of this copy operation, or pass to abort_copy_file to abort a pending copy.

  • copy_status - String. The state of the copy operation, with these values:

    "success" - The copy completed successfully.
"pending" - The copy is in progress.


535
536
537
538
539
540
541
542
543
544
545
546
 
# File 'file/lib/azure/storage/file/file.rb', line 535

def copy_file_from_uri(destination_share, destination_directory_path, destination_file, source_uri, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = file_uri(destination_share, destination_directory_path, destination_file, query)
  headers = {}
  StorageService.with_header headers, "x-ms-copy-source", source_uri
  StorageService.add_metadata_to_headers options[:metadata], headers unless options.empty?

  response = call(:put, uri, nil, headers, options)
  return response.headers["x-ms-copy-id"], response.headers["x-ms-copy-status"]
end

#create_directory(share, directory_path, options = {}) ⇒ Object

Public: Create a new directory

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :metadata - Hash. User defined metadata for the share (optional).

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/create-directory

Returns a Directory



126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'file/lib/azure/storage/file/directory.rb', line 126

def create_directory(share, directory_path, options = {})
  # Query
  query = {}
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Scheme + path
  uri = directory_uri(share, directory_path, query)

  # Headers
  headers = {}
  StorageService.add_metadata_to_headers(options[:metadata], headers) if options[:metadata]

  # Call
  response = call(:put, uri, nil, headers, options)

  # result
  directory = Serialization.directory_from_headers(response.headers)
  directory.name = directory_path
  directory.metadata = options[:metadata] if options[:metadata]
  directory
end

#create_file(share, directory_path, file, length, options = {}) ⇒ Object

Public: Creates a new file or replaces a file. Note that it only initializes the file.

To add content to a file, call the put_range operation.

Updating an existing file overwrites any existing metadata on the file Partial updates are not supported with create_file. The content of the existing file is overwritten with the content of the new file. To perform a partial update of the content of a file, use the put_range method.

Note that the default content type is application/octet-stream.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • length - Integer. Specifies the maximum byte value for the file, up to 1 TB.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :content_type - String. Content type for the file. Will be saved with file.

  • :content_encoding - String. Content encoding for the file. Will be saved with file.

  • :content_language - String. Content language for the file. Will be saved with file.

  • :content_md5 - String. Content MD5 for the file. Will be saved with file.

  • :cache_control - String. Cache control for the file. Will be saved with file.

  • :content_disposition - String. Conveys additional information about how to process the response payload,

    and also can be used to attach additional metadata

  • :metadata - Hash. Custom metadata values to store with the file.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/create-file

Returns a File



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'file/lib/azure/storage/file/file.rb', line 79

def create_file(share, directory_path, file, length, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = file_uri(share, directory_path, file, query)

  headers = {}

  # set x-ms-type to file
  StorageService.with_header headers, "x-ms-type", "file"

  # ensure content-length is 0 and x-ms-content-length is the file length
  StorageService.with_header headers, "Content-Length", 0.to_s
  StorageService.with_header headers, "x-ms-content-length", length.to_s

  # set the rest of the optional headers
  StorageService.with_header headers, "x-ms-content-type", options[:content_type]
  StorageService.with_header headers, "x-ms-content-encoding", options[:content_encoding]
  StorageService.with_header headers, "x-ms-content-language", options[:content_language]
  StorageService.with_header headers, "x-ms-content-md5", options[:content_md5]
  StorageService.with_header headers, "x-ms-cache-control", options[:cache_control]
  StorageService.with_header headers, "x-ms-content-disposition", options[:content_disposition]

  StorageService.add_metadata_to_headers options[:metadata], headers
  headers["x-ms-content-type"] = Default::CONTENT_TYPE_VALUE unless headers["x-ms-content-type"]

  response = call(:put, uri, nil, headers, options)

  result = Serialization.file_from_headers(response.headers)
  result.name = file
  result.properties[:content_length] = length
  result.metadata = options[:metadata] if options[:metadata]
  result
end

#create_file_from_content(share, directory_path, file, length, content, options = {}) ⇒ Object

Public: Creates a new file or replaces a file with content

Updating an existing file overwrites any existing metadata on the file Partial updates are not supported with create_file. The content of the existing file is overwritten with the content of the new file. To perform a partial update of the content of a file, use the put_range method.

Note that the default content type is application/octet-stream.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • length - Integer. Specifies the maximum byte value for the file, up to 1 TB.

  • content - String or IO. The content to put in the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :content_type - String. Content type for the file. Will be saved with file.

  • :content_encoding - String. Content encoding for the file. Will be saved with file.

  • :content_language - String. Content language for the file. Will be saved with file.

  • :content_md5 - String. Content MD5 for the file. Will be saved with file.

  • :cache_control - String. Cache control for the file. Will be saved with file.

  • :content_disposition - String. Conveys additional information about how to process the response payload,

    and also can be used to attach additional metadata

  • :metadata - Hash. Custom metadata values to store with the file.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/create-file

Returns a File



656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
 
# File 'file/lib/azure/storage/file/file.rb', line 656

def create_file_from_content(share, directory_path, file, length, content, options = {})
  options[:content_type] = get_or_apply_content_type(content, options[:content_type])
  create_file(share, directory_path, file, length, options)

  content = StringIO.new(content) if content.is_a? String
  upload_count = (Float(length) / Float(FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES)).ceil

  for idx in 0...upload_count
    start_range = idx * FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES
    end_range = start_range + FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES - 1
    end_range = (length - 1) if end_range > (length - 1)
    put_file_range(share, directory_path, file, start_range, end_range, content.read(FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES))
  end

  # Get the file properties
  get_file_properties(share, directory_path, file)
end

#delete_directory(share, directory_path, options = {}) ⇒ Object

Public: Deletes a directory.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/delete-directory

Returns nil on success



203
204
205
206
207
208
209
210
211
212
213
 
# File 'file/lib/azure/storage/file/directory.rb', line 203

def delete_directory(share, directory_path, options = {})
  # Query
  query = {}
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Call
  call(:delete, directory_uri(share, directory_path, query), nil, {}, options)

  # result
  nil
end

#delete_file(share, directory_path, file, options = {}) ⇒ Object

Public: Deletes a file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/delete-file2

Returns nil on success



492
493
494
495
496
497
498
499
500
501
502
 
# File 'file/lib/azure/storage/file/file.rb', line 492

def delete_file(share, directory_path, file, options = {})
  # Query
  query = {}
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Call
  call(:delete, file_uri(share, directory_path, file, query), nil, {}, options)

  # result
  nil
end

#get_directory_metadata(share, directory_path, options = {}) ⇒ Object

Public: Returns only user-defined metadata for the specified directory.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-directory-metadata

Returns a Directory



235
236
237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'file/lib/azure/storage/file/directory.rb', line 235

def get_directory_metadata(share, directory_path, options = {})
  # Query
  query = { "comp" => "metadata" }
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Call
  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  response = call(:get, directory_uri(share, directory_path, query, options), nil, {}, options)

  # result
  directory = Serialization.directory_from_headers(response.headers)
  directory.name = directory_path
  directory
end

#get_directory_properties(share, directory_path, options = {}) ⇒ Object

Public: Returns all system properties for the specified directory,

and can also be used to check the existence of a directory.
The data returned does not include the files in the directory or any subdirectories.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-directory-properties

Returns a Directory



170
171
172
173
174
175
176
177
178
179
180
181
182
183
 
# File 'file/lib/azure/storage/file/directory.rb', line 170

def get_directory_properties(share, directory_path, options = {})
  # Query
  query = {}
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Call
  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  response = call(:get, directory_uri(share, directory_path, query, options), nil, {}, options)

  # result
  directory = Serialization.directory_from_headers(response.headers)
  directory.name = directory_path
  directory
end

#get_file(share, directory_path, file, options = {}) ⇒ Object

Public: Reads or downloads a file from the system, including its metadata and properties.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :start_range - Integer. Position of the start range. (optional)

  • :end_range - Integer. Position of the end range. (optional)

  • :get_content_md5 - Boolean. Return the MD5 hash for the range. This option only valid if

    start_range and end_range are specified. (optional)

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file

Returns a File and the file body



139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'file/lib/azure/storage/file/file.rb', line 139

def get_file(share, directory_path, file, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = file_uri(share, directory_path, file, query, options)

  headers = {}
  options[:start_range] = 0 if options[:end_range] && (not options[:start_range])
  if options[:start_range]
    StorageService.with_header headers, "x-ms-range", "bytes=#{options[:start_range]}-#{options[:end_range]}"
    StorageService.with_header headers, "x-ms-range-get-content-md5", "true" if options[:get_content_md5]
  end

  response = call(:get, uri, nil, headers, options)
  result = Serialization.file_from_headers(response.headers)
  result.name = file

  return result, response.body
end

#get_file_metadata(share, directory_path, file, options = {}) ⇒ Object

Public: Returns only user-defined metadata for the specified file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file-metadata

Returns a File



422
423
424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'file/lib/azure/storage/file/file.rb', line 422

def get_file_metadata(share, directory_path, file, options = {})
  # Query
  query = { "comp" => "metadata" }
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Call
  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  response = call(:get, file_uri(share, directory_path, file, query, options), nil, {}, options)

  # result
  result = Serialization.file_from_headers(response.headers)
  result.name = file
  result
end

#get_file_properties(share, directory_path, file, options = {}) ⇒ Object

Public: Returns all properties and metadata on the file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file-properties

Returns a File



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'file/lib/azure/storage/file/file.rb', line 181

def get_file_properties(share, directory_path, file, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  headers = {}

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = file_uri(share, directory_path, file, query, options)

  response = call(:head, uri, nil, headers, options)

  result = Serialization.file_from_headers(response.headers)
  result.name = file
  result
end

#list_directories_and_files(share, directory_path, options = {}) ⇒ Object

Public: Get a list of files or directories under the specified share or directory.

It lists the contents only for a single level of the directory hierarchy.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :prefix - String. Filters the results to return only directories and files

    whose name begins with the specified prefix. (optional)

  • :marker - String. An identifier the specifies the portion of the

    list to be returned. This value comes from the property
Azure::Storage::Common::EnumerationResults.continuation_token when there
are more shares available than were returned. The
marker value may then be used here to request the next set
of list items. (optional)

  • :max_results - Integer. Specifies the maximum number of shares to return.

    If max_results is not specified, or is a value greater than
5,000, the server will return up to 5,000 items. If it is set
to a value less than or equal to zero, the server will return
status code 400 (Bad Request). (optional)

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See: docs.microsoft.com/en-us/rest/api/storageservices/fileservices/list-directories-and-files

Returns an Azure::Storage::Common::EnumerationResults



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
 
# File 'file/lib/azure/storage/file/directory.rb', line 86

def list_directories_and_files(share, directory_path, options = {})
  query = { "comp" => "list" }
  unless options.nil?
    StorageService.with_query query, "marker", options[:marker]
    StorageService.with_query query, "maxresults", options[:max_results].to_s if options[:max_results]
    StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
    StorageService.with_query query, "prefix", options[:prefix].to_s if options[:prefix]
  end

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = directory_uri(share, directory_path, query, options)
  response = call(:get, uri, nil, {}, options)

  # Result
  if response.success?
    Serialization.directories_and_files_enumeration_results_from_xml(response.body)
  else
    response.exception
  end
end

#list_file_ranges(share, directory_path, file, options = {}) ⇒ Object

Public: Returns a list of valid ranges for a file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :start_range - Integer. Position of first byte of the range.

  • :end_range - Integer. Position of last byte of of the range.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

  • :location_mode - LocationMode. Specifies the location mode used to decide

    which location the request should be sent to.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/list-ranges

Returns a tuple of a File and a list of ranges in the format [ [start, end], [start, end], … ]

eg. (File::File, [ [0, 511], [512, 1024], ... ])


381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'file/lib/azure/storage/file/file.rb', line 381

def list_file_ranges(share, directory_path, file, options = {})
  query = { "comp" => "rangelist" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = file_uri(share, directory_path, file, query, options)

  options[:start_range] = 0 if options[:end_range] && (not options[:start_range])

  headers = {}
  StorageService.with_header headers, "x-ms-range", "bytes=#{options[:start_range]}-#{options[:end_range]}" if options[:start_range]

  response = call(:get, uri, nil, headers, options)

  result = Serialization.file_from_headers(response.headers)
  result.name = file
  rangelist = Serialization.range_list_from_xml(response.body)
  return result, rangelist
end

#put_file_range(share, directory_path, file, start_range, end_range = nil, content = nil, options = {}) ⇒ Object

Public: Writes a range of bytes to a file

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • start_range - Integer. Position of first byte of the range.

  • end_range - Integer. Position of last byte of of the range. The range can be up to 4 MB in size.

  • content - IO or String. Content to write.

  • options - Hash. A collection of options.

Options

Accepted key/value pairs in options parameter are:

  • :transactional_md5 - String. An MD5 hash of the content. This hash is used to verify the integrity of the data during transport.

    When this header is specified, the storage service checks the hash that has arrived with the one that was sent.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/put-range

Returns a File



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'file/lib/azure/storage/file/file.rb', line 299

def put_file_range(share, directory_path, file, start_range, end_range = nil, content = nil, options = {})
  query = { "comp" => "range" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = file_uri(share, directory_path, file, query)
  headers = {}
  StorageService.with_header headers, "Content-MD5", options[:transactional_md5]
  StorageService.with_header headers, "x-ms-range", "bytes=#{start_range}-#{end_range}"
  StorageService.with_header headers, "x-ms-write", "update"

  response = call(:put, uri, content, headers, options)

  result = Serialization.file_from_headers(response.headers)
  result.name = file
  result
end

#resize_file(share, directory_path, file, size, options = {}) ⇒ Object

Public: Resizes a file to the specified size.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • size - String. The file size. Resizes a file to the specified size.

    If the specified value is less than the current size of the file,
then all ranges above the specified value are cleared.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-properties

Returns nil on success.



269
270
271
272
 
# File 'file/lib/azure/storage/file/file.rb', line 269

def resize_file(share, directory_path, file, size, options = {})
  options = { content_length: size }.merge(options)
  set_file_properties share, directory_path, file, options
end

#set_directory_metadata(share, directory_path, metadata, options = {}) ⇒ Object

Public: Sets custom metadata for the directory.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • metadata - Hash. A Hash of the metadata values.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-directory-metadata

Returns nil on success



269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'file/lib/azure/storage/file/directory.rb', line 269

def set_directory_metadata(share, directory_path, metadata, options = {})
  # Query
  query = { "comp" => "metadata" }
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Headers
  headers = {}
  StorageService.add_metadata_to_headers(metadata, headers) if metadata

  # Call
  call(:put, directory_uri(share, directory_path, query), nil, headers, options)

  # Result
  nil
end

#set_file_metadata(share, directory_path, file, metadata, options = {}) ⇒ Object

Public: Sets custom metadata for the file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • metadata - Hash. A Hash of the metadata values.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-metadata

Returns nil on success



457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
 
# File 'file/lib/azure/storage/file/file.rb', line 457

def set_file_metadata(share, directory_path, file, metadata, options = {})
  # Query
  query = { "comp" => "metadata" }
  query["timeout"] = options[:timeout].to_s if options[:timeout]

  # Headers
  headers = {}
  StorageService.add_metadata_to_headers(metadata, headers) if metadata

  # Call
  call(:put, file_uri(share, directory_path, file, query), nil, headers, options)

  # Result
  nil
end

#set_file_properties(share, directory_path, file, options = {}) ⇒ Object

Public: Sets system properties defined for a file.

Attributes

  • share - String. The name of the file share.

  • directory_path - String. The path to the directory.

  • file - String. The name of the file.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :content_type - String. Content type for the file. Will be saved with file.

  • :content_encoding - String. Content encoding for the file. Will be saved with file.

  • :content_language - String. Content language for the file. Will be saved with file.

  • :content_md5 - String. Content MD5 for the file. Will be saved with file.

  • :cache_control - String. Cache control for the file. Will be saved with file.

  • :content_disposition - String. Conveys additional information about how to process the response payload,

    and also can be used to attach additional metadata

  • :content_length - Integer. Resizes a file to the specified size. If the specified

    value is less than the current size of the file, then all ranges above
the specified value are cleared.

  • :timeout - Integer. A timeout in seconds.

  • :request_id - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded

    in the analytics logs when storage analytics logging is enabled.

See docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-properties

Returns nil on success.



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'file/lib/azure/storage/file/file.rb', line 226

def set_file_properties(share, directory_path, file, options = {})
  query = { "comp" => "properties" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
  uri = file_uri(share, directory_path, file, query)

  headers = {}

  unless options.empty?
    StorageService.with_header headers, "x-ms-content-type", options[:content_type]
    StorageService.with_header headers, "x-ms-content-encoding", options[:content_encoding]
    StorageService.with_header headers, "x-ms-content-language", options[:content_language]
    StorageService.with_header headers, "x-ms-content-md5", options[:content_md5]
    StorageService.with_header headers, "x-ms-cache-control", options[:cache_control]
    StorageService.with_header headers, "x-ms-content-length", options[:content_length].to_s if options[:content_length]
    StorageService.with_header headers, "x-ms-content-disposition", options[:content_disposition]
  end

  call(:put, uri, nil, headers, options)
  nil
end