azure-storage-file 1.0.0

Sign up to get free protection for your applications and to get access to all the features.
@@ -0,0 +1,673 @@
1
+ # frozen_string_literal: true
2
+
3
+ #-------------------------------------------------------------------------
4
+ # # Copyright (c) Microsoft and contributors. All rights reserved.
5
+ #
6
+ # The MIT License(MIT)
7
+
8
+ # Permission is hereby granted, free of charge, to any person obtaining a copy
9
+ # of this software and associated documentation files(the "Software"), to deal
10
+ # in the Software without restriction, including without limitation the rights
11
+ # to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
12
+ # copies of the Software, and to permit persons to whom the Software is
13
+ # furnished to do so, subject to the following conditions :
14
+
15
+ # The above copyright notice and this permission notice shall be included in
16
+ # all copies or substantial portions of the Software.
17
+
18
+ # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
21
+ # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
24
+ # THE SOFTWARE.
25
+ #--------------------------------------------------------------------------
26
+ require "azure/storage/file/serialization"
27
+
28
+ module Azure::Storage::File
29
+ include Azure::Storage::Common::Service
30
+
31
+ class File
32
+ def initialize
33
+ @properties = {}
34
+ @metadata = {}
35
+ yield self if block_given?
36
+ end
37
+
38
+ attr_accessor :name
39
+ attr_accessor :properties
40
+ attr_accessor :metadata
41
+ end
42
+
43
+ # Public: Creates a new file or replaces a file. Note that it only initializes the file.
44
+ # To add content to a file, call the put_range operation.
45
+ #
46
+ # Updating an existing file overwrites any existing metadata on the file
47
+ # Partial updates are not supported with create_file. The content of the
48
+ # existing file is overwritten with the content of the new file. To perform a
49
+ # partial update of the content of a file, use the put_range method.
50
+ #
51
+ # Note that the default content type is application/octet-stream.
52
+ #
53
+ # ==== Attributes
54
+ #
55
+ # * +share+ - String. The name of the file share.
56
+ # * +directory_path+ - String. The path to the directory.
57
+ # * +file+ - String. The name of the file.
58
+ # * +length+ - Integer. Specifies the maximum byte value for the file, up to 1 TB.
59
+ # * +options+ - Hash. Optional parameters.
60
+ #
61
+ # ==== Options
62
+ #
63
+ # Accepted key/value pairs in options parameter are:
64
+ # * +:content_type+ - String. Content type for the file. Will be saved with file.
65
+ # * +:content_encoding+ - String. Content encoding for the file. Will be saved with file.
66
+ # * +:content_language+ - String. Content language for the file. Will be saved with file.
67
+ # * +:content_md5+ - String. Content MD5 for the file. Will be saved with file.
68
+ # * +:cache_control+ - String. Cache control for the file. Will be saved with file.
69
+ # * +:content_disposition+ - String. Conveys additional information about how to process the response payload,
70
+ # and also can be used to attach additional metadata
71
+ # * +:metadata+ - Hash. Custom metadata values to store with the file.
72
+ # * +:timeout+ - Integer. A timeout in seconds.
73
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
74
+ # in the analytics logs when storage analytics logging is enabled.
75
+ #
76
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/create-file
77
+ #
78
+ # Returns a File
79
+ def create_file(share, directory_path, file, length, options = {})
80
+ query = {}
81
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
82
+
83
+ uri = file_uri(share, directory_path, file, query)
84
+
85
+ headers = {}
86
+
87
+ # set x-ms-type to file
88
+ StorageService.with_header headers, "x-ms-type", "file"
89
+
90
+ # ensure content-length is 0 and x-ms-content-length is the file length
91
+ StorageService.with_header headers, "Content-Length", 0.to_s
92
+ StorageService.with_header headers, "x-ms-content-length", length.to_s
93
+
94
+ # set the rest of the optional headers
95
+ StorageService.with_header headers, "x-ms-content-type", options[:content_type]
96
+ StorageService.with_header headers, "x-ms-content-encoding", options[:content_encoding]
97
+ StorageService.with_header headers, "x-ms-content-language", options[:content_language]
98
+ StorageService.with_header headers, "x-ms-content-md5", options[:content_md5]
99
+ StorageService.with_header headers, "x-ms-cache-control", options[:cache_control]
100
+ StorageService.with_header headers, "x-ms-content-disposition", options[:content_disposition]
101
+
102
+ StorageService.add_metadata_to_headers options[:metadata], headers
103
+ headers["x-ms-content-type"] = Default::CONTENT_TYPE_VALUE unless headers["x-ms-content-type"]
104
+
105
+ response = call(:put, uri, nil, headers, options)
106
+
107
+ result = Serialization.file_from_headers(response.headers)
108
+ result.name = file
109
+ result.properties[:content_length] = length
110
+ result.metadata = options[:metadata] if options[:metadata]
111
+ result
112
+ end
113
+
114
+ # Public: Reads or downloads a file from the system, including its metadata and properties.
115
+ #
116
+ # ==== Attributes
117
+ #
118
+ # * +share+ - String. The name of the file share.
119
+ # * +directory_path+ - String. The path to the directory.
120
+ # * +file+ - String. The name of the file.
121
+ # * +options+ - Hash. Optional parameters.
122
+ #
123
+ # ==== Options
124
+ #
125
+ # Accepted key/value pairs in options parameter are:
126
+ # * +:start_range+ - Integer. Position of the start range. (optional)
127
+ # * +:end_range+ - Integer. Position of the end range. (optional)
128
+ # * +:get_content_md5+ - Boolean. Return the MD5 hash for the range. This option only valid if
129
+ # start_range and end_range are specified. (optional)
130
+ # * +:timeout+ - Integer. A timeout in seconds.
131
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
132
+ # in the analytics logs when storage analytics logging is enabled.
133
+ # * +:location_mode+ - LocationMode. Specifies the location mode used to decide
134
+ # which location the request should be sent to.
135
+ #
136
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file
137
+ #
138
+ # Returns a File and the file body
139
+ def get_file(share, directory_path, file, options = {})
140
+ query = {}
141
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
142
+
143
+ options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
144
+ uri = file_uri(share, directory_path, file, query, options)
145
+
146
+ headers = {}
147
+ options[:start_range] = 0 if options[:end_range] && (not options[:start_range])
148
+ if options[:start_range]
149
+ StorageService.with_header headers, "x-ms-range", "bytes=#{options[:start_range]}-#{options[:end_range]}"
150
+ StorageService.with_header headers, "x-ms-range-get-content-md5", "true" if options[:get_content_md5]
151
+ end
152
+
153
+ response = call(:get, uri, nil, headers, options)
154
+ result = Serialization.file_from_headers(response.headers)
155
+ result.name = file
156
+
157
+ return result, response.body
158
+ end
159
+
160
+ # Public: Returns all properties and metadata on the file.
161
+ #
162
+ # ==== Attributes
163
+ #
164
+ # * +share+ - String. The name of the file share.
165
+ # * +directory_path+ - String. The path to the directory.
166
+ # * +file+ - String. The name of the file.
167
+ # * +options+ - Hash. Optional parameters.
168
+ #
169
+ # ==== Options
170
+ #
171
+ # Accepted key/value pairs in options parameter are:
172
+ # * +:timeout+ - Integer. A timeout in seconds.
173
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
174
+ # in the analytics logs when storage analytics logging is enabled.
175
+ # * +:location_mode+ - LocationMode. Specifies the location mode used to decide
176
+ # which location the request should be sent to.
177
+ #
178
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file-properties
179
+ #
180
+ # Returns a File
181
+ def get_file_properties(share, directory_path, file, options = {})
182
+ query = {}
183
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
184
+
185
+ headers = {}
186
+
187
+ options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
188
+ uri = file_uri(share, directory_path, file, query, options)
189
+
190
+ response = call(:head, uri, nil, headers, options)
191
+
192
+ result = Serialization.file_from_headers(response.headers)
193
+ result.name = file
194
+ result
195
+ end
196
+
197
+ # Public: Sets system properties defined for a file.
198
+ #
199
+ # ==== Attributes
200
+ #
201
+ # * +share+ - String. The name of the file share.
202
+ # * +directory_path+ - String. The path to the directory.
203
+ # * +file+ - String. The name of the file.
204
+ # * +options+ - Hash. Optional parameters.
205
+ #
206
+ # ==== Options
207
+ #
208
+ # Accepted key/value pairs in options parameter are:
209
+ # * +:content_type+ - String. Content type for the file. Will be saved with file.
210
+ # * +:content_encoding+ - String. Content encoding for the file. Will be saved with file.
211
+ # * +:content_language+ - String. Content language for the file. Will be saved with file.
212
+ # * +:content_md5+ - String. Content MD5 for the file. Will be saved with file.
213
+ # * +:cache_control+ - String. Cache control for the file. Will be saved with file.
214
+ # * +:content_disposition+ - String. Conveys additional information about how to process the response payload,
215
+ # and also can be used to attach additional metadata
216
+ # * +:content_length+ - Integer. Resizes a file to the specified size. If the specified
217
+ # value is less than the current size of the file, then all ranges above
218
+ # the specified value are cleared.
219
+ # * +:timeout+ - Integer. A timeout in seconds.
220
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
221
+ # in the analytics logs when storage analytics logging is enabled.
222
+ #
223
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-properties
224
+ #
225
+ # Returns nil on success.
226
+ def set_file_properties(share, directory_path, file, options = {})
227
+ query = { "comp" => "properties" }
228
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
229
+ uri = file_uri(share, directory_path, file, query)
230
+
231
+ headers = {}
232
+
233
+ unless options.empty?
234
+ StorageService.with_header headers, "x-ms-content-type", options[:content_type]
235
+ StorageService.with_header headers, "x-ms-content-encoding", options[:content_encoding]
236
+ StorageService.with_header headers, "x-ms-content-language", options[:content_language]
237
+ StorageService.with_header headers, "x-ms-content-md5", options[:content_md5]
238
+ StorageService.with_header headers, "x-ms-cache-control", options[:cache_control]
239
+ StorageService.with_header headers, "x-ms-content-length", options[:content_length].to_s if options[:content_length]
240
+ StorageService.with_header headers, "x-ms-content-disposition", options[:content_disposition]
241
+ end
242
+
243
+ call(:put, uri, nil, headers, options)
244
+ nil
245
+ end
246
+
247
+ # Public: Resizes a file to the specified size.
248
+ #
249
+ # ==== Attributes
250
+ #
251
+ # * +share+ - String. The name of the file share.
252
+ # * +directory_path+ - String. The path to the directory.
253
+ # * +file+ - String. The name of the file.
254
+ # * +size+ - String. The file size. Resizes a file to the specified size.
255
+ # If the specified value is less than the current size of the file,
256
+ # then all ranges above the specified value are cleared.
257
+ # * +options+ - Hash. Optional parameters.
258
+ #
259
+ # ==== Options
260
+ #
261
+ # Accepted key/value pairs in options parameter are:
262
+ # * +:timeout+ - Integer. A timeout in seconds.
263
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
264
+ # in the analytics logs when storage analytics logging is enabled.
265
+ #
266
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-properties
267
+ #
268
+ # Returns nil on success.
269
+ def resize_file(share, directory_path, file, size, options = {})
270
+ options = { content_length: size }.merge(options)
271
+ set_file_properties share, directory_path, file, options
272
+ end
273
+
274
+ # Public: Writes a range of bytes to a file
275
+ #
276
+ # ==== Attributes
277
+ #
278
+ # * +share+ - String. The name of the file share.
279
+ # * +directory_path+ - String. The path to the directory.
280
+ # * +file+ - String. The name of the file.
281
+ # * +start_range+ - Integer. Position of first byte of the range.
282
+ # * +end_range+ - Integer. Position of last byte of of the range. The range can be up to 4 MB in size.
283
+ # * +content+ - IO or String. Content to write.
284
+ # * +options+ - Hash. A collection of options.
285
+ #
286
+ # ==== Options
287
+ #
288
+ # Accepted key/value pairs in options parameter are:
289
+ # * +:transactional_md5+ - String. An MD5 hash of the content. This hash is used to verify the integrity of the data during transport.
290
+ # When this header is specified, the storage service checks the hash that has arrived with the one that was sent.
291
+ # * +:timeout+ - Integer. A timeout in seconds.
292
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
293
+ # in the analytics logs when storage analytics logging is enabled.
294
+ #
295
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/put-range
296
+ #
297
+ # Returns a File
298
+ #
299
+ def put_file_range(share, directory_path, file, start_range, end_range = nil, content = nil, options = {})
300
+ query = { "comp" => "range" }
301
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
302
+
303
+ uri = file_uri(share, directory_path, file, query)
304
+ headers = {}
305
+ StorageService.with_header headers, "Content-MD5", options[:transactional_md5]
306
+ StorageService.with_header headers, "x-ms-range", "bytes=#{start_range}-#{end_range}"
307
+ StorageService.with_header headers, "x-ms-write", "update"
308
+
309
+ response = call(:put, uri, content, headers, options)
310
+
311
+ result = Serialization.file_from_headers(response.headers)
312
+ result.name = file
313
+ result
314
+ end
315
+
316
+ # Public: Clears a range of file.
317
+ #
318
+ # ==== Attributes
319
+ #
320
+ # * +share+ - String. The name of the file share.
321
+ # * +directory_path+ - String. The path to the directory.
322
+ # * +file+ - String. The name of the file.
323
+ # * +start_range+ - Integer. Position of first byte of the range.
324
+ # * +end_range+ - Integer. Position of last byte of of the range.
325
+ # * +options+ - Hash. A collection of options.
326
+ #
327
+ # ==== Options
328
+ #
329
+ # Accepted key/value pairs in options parameter are:
330
+ # * +:timeout+ - Integer. A timeout in seconds.
331
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
332
+ # in the analytics logs when storage analytics logging is enabled.
333
+ #
334
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/put-range
335
+ #
336
+ # Returns a File
337
+ def clear_file_range(share, directory_path, file, start_range, end_range = nil, options = {})
338
+ query = { "comp" => "range" }
339
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
340
+
341
+ uri = file_uri(share, directory_path, file, query)
342
+ start_range = 0 if !end_range.nil? && start_range.nil?
343
+
344
+ headers = {}
345
+ StorageService.with_header headers, "x-ms-range", "bytes=#{start_range}-#{end_range}"
346
+ StorageService.with_header headers, "x-ms-write", "clear"
347
+
348
+ response = call(:put, uri, nil, headers, options)
349
+
350
+ result = Serialization.file_from_headers(response.headers)
351
+ result.name = file
352
+ result
353
+ end
354
+
355
+ # Public: Returns a list of valid ranges for a file.
356
+ #
357
+ # ==== Attributes
358
+ #
359
+ # * +share+ - String. The name of the file share.
360
+ # * +directory_path+ - String. The path to the directory.
361
+ # * +file+ - String. The name of the file.
362
+ # * +options+ - Hash. Optional parameters.
363
+ #
364
+ # ==== Options
365
+ #
366
+ # Accepted key/value pairs in options parameter are:
367
+ # * +:start_range+ - Integer. Position of first byte of the range.
368
+ # * +:end_range+ - Integer. Position of last byte of of the range.
369
+ # * +:timeout+ - Integer. A timeout in seconds.
370
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
371
+ # in the analytics logs when storage analytics logging is enabled.
372
+ # * +:location_mode+ - LocationMode. Specifies the location mode used to decide
373
+ # which location the request should be sent to.
374
+ #
375
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/list-ranges
376
+ #
377
+ # Returns a tuple of a File and a list of ranges in the format [ [start, end], [start, end], ... ]
378
+ #
379
+ # eg. (File::File, [ [0, 511], [512, 1024], ... ])
380
+ #
381
+ def list_file_ranges(share, directory_path, file, options = {})
382
+ query = { "comp" => "rangelist" }
383
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
384
+
385
+ options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
386
+ uri = file_uri(share, directory_path, file, query, options)
387
+
388
+ options[:start_range] = 0 if options[:end_range] && (not options[:start_range])
389
+
390
+ headers = {}
391
+ StorageService.with_header headers, "x-ms-range", "bytes=#{options[:start_range]}-#{options[:end_range]}" if options[:start_range]
392
+
393
+ response = call(:get, uri, nil, headers, options)
394
+
395
+ result = Serialization.file_from_headers(response.headers)
396
+ result.name = file
397
+ rangelist = Serialization.range_list_from_xml(response.body)
398
+ return result, rangelist
399
+ end
400
+
401
+ # Public: Returns only user-defined metadata for the specified file.
402
+ #
403
+ # ==== Attributes
404
+ #
405
+ # * +share+ - String. The name of the file share.
406
+ # * +directory_path+ - String. The path to the directory.
407
+ # * +file+ - String. The name of the file.
408
+ # * +options+ - Hash. Optional parameters.
409
+ #
410
+ # ==== Options
411
+ #
412
+ # Accepted key/value pairs in options parameter are:
413
+ # * +:timeout+ - Integer. A timeout in seconds.
414
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
415
+ # in the analytics logs when storage analytics logging is enabled.
416
+ # * +:location_mode+ - LocationMode. Specifies the location mode used to decide
417
+ # which location the request should be sent to.
418
+ #
419
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/get-file-metadata
420
+ #
421
+ # Returns a File
422
+ def get_file_metadata(share, directory_path, file, options = {})
423
+ # Query
424
+ query = { "comp" => "metadata" }
425
+ query["timeout"] = options[:timeout].to_s if options[:timeout]
426
+
427
+ # Call
428
+ options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
429
+ response = call(:get, file_uri(share, directory_path, file, query, options), nil, {}, options)
430
+
431
+ # result
432
+ result = Serialization.file_from_headers(response.headers)
433
+ result.name = file
434
+ result
435
+ end
436
+
437
+ # Public: Sets custom metadata for the file.
438
+ #
439
+ # ==== Attributes
440
+ #
441
+ # * +share+ - String. The name of the file share.
442
+ # * +directory_path+ - String. The path to the directory.
443
+ # * +file+ - String. The name of the file.
444
+ # * +metadata+ - Hash. A Hash of the metadata values.
445
+ # * +options+ - Hash. Optional parameters.
446
+ #
447
+ # ==== Options
448
+ #
449
+ # Accepted key/value pairs in options parameter are:
450
+ # * +:timeout+ - Integer. A timeout in seconds.
451
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
452
+ # in the analytics logs when storage analytics logging is enabled.
453
+ #
454
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/set-file-metadata
455
+ #
456
+ # Returns nil on success
457
+ def set_file_metadata(share, directory_path, file, metadata, options = {})
458
+ # Query
459
+ query = { "comp" => "metadata" }
460
+ query["timeout"] = options[:timeout].to_s if options[:timeout]
461
+
462
+ # Headers
463
+ headers = {}
464
+ StorageService.add_metadata_to_headers(metadata, headers) if metadata
465
+
466
+ # Call
467
+ call(:put, file_uri(share, directory_path, file, query), nil, headers, options)
468
+
469
+ # Result
470
+ nil
471
+ end
472
+
473
+ # Public: Deletes a file.
474
+ #
475
+ # ==== Attributes
476
+ #
477
+ # * +share+ - String. The name of the file share.
478
+ # * +directory_path+ - String. The path to the directory.
479
+ # * +file+ - String. The name of the file.
480
+ # * +options+ - Hash. Optional parameters.
481
+ #
482
+ # ==== Options
483
+ #
484
+ # Accepted key/value pairs in options parameter are:
485
+ # * +:timeout+ - Integer. A timeout in seconds.
486
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
487
+ # in the analytics logs when storage analytics logging is enabled.
488
+ #
489
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/delete-file2
490
+ #
491
+ # Returns nil on success
492
+ def delete_file(share, directory_path, file, options = {})
493
+ # Query
494
+ query = {}
495
+ query["timeout"] = options[:timeout].to_s if options[:timeout]
496
+
497
+ # Call
498
+ call(:delete, file_uri(share, directory_path, file, query), nil, {}, options)
499
+
500
+ # result
501
+ nil
502
+ end
503
+
504
+ # Public: Copies a source file or file to a destination file within the storage account.
505
+ #
506
+ # ==== Attributes
507
+ #
508
+ # * +destination_share+ - String. The name of the destination file share.
509
+ # * +destination_directory_path+ - String. The path to the destination directory.
510
+ # * +destination_file+ - String. The name of the destination file.
511
+ # * +source_uri+ - String. The source file or file URI to copy from.
512
+ # * +options+ - Hash. Optional parameters.
513
+ #
514
+ # ==== Options
515
+ #
516
+ # Accepted key/value pairs in options parameter are:
517
+ # * +:metadata+ - Hash. Custom metadata values to store with the copy. If this parameter is not
518
+ # specified, the operation will copy the source file metadata to the destination
519
+ # file. If this parameter is specified, the destination file is created with the
520
+ # specified metadata, and metadata is not copied from the source file.
521
+ # * +:timeout+ - Integer. A timeout in seconds.
522
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
523
+ # in the analytics logs when storage analytics logging is enabled.
524
+ #
525
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/copy-file
526
+ #
527
+ # Returns a tuple of (copy_id, copy_status).
528
+ #
529
+ # * +copy_id+ - String identifier for this copy operation. Use with get_file or get_file_properties to check
530
+ # the status of this copy operation, or pass to abort_copy_file to abort a pending copy.
531
+ # * +copy_status+ - String. The state of the copy operation, with these values:
532
+ # "success" - The copy completed successfully.
533
+ # "pending" - The copy is in progress.
534
+ #
535
+ def copy_file_from_uri(destination_share, destination_directory_path, destination_file, source_uri, options = {})
536
+ query = {}
537
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
538
+
539
+ uri = file_uri(destination_share, destination_directory_path, destination_file, query)
540
+ headers = {}
541
+ StorageService.with_header headers, "x-ms-copy-source", source_uri
542
+ StorageService.add_metadata_to_headers options[:metadata], headers unless options.empty?
543
+
544
+ response = call(:put, uri, nil, headers, options)
545
+ return response.headers["x-ms-copy-id"], response.headers["x-ms-copy-status"]
546
+ end
547
+
548
+ # Public: Copies a source file to a destination file within the same storage account.
549
+ #
550
+ # ==== Attributes
551
+ #
552
+ # * +destination_share+ - String. The destination share name to copy to.
553
+ # * +destination_directory_path+ - String. The path to the destination directory.
554
+ # * +source_file+ - String. The destination file name to copy to.
555
+ # * +source_share+ - String. The source share name to copy from.
556
+ # * +source_directory_path+ - String. The path to the source directory.
557
+ # * +source_file+ - String. The source file name to copy from.
558
+ # * +options+ - Hash. Optional parameters.
559
+ #
560
+ # ==== Options
561
+ #
562
+ # Accepted key/value pairs in options parameter are:
563
+ # * +:metadata+ - Hash. Custom metadata values to store with the copy. If this parameter is not
564
+ # specified, the operation will copy the source file metadata to the destination
565
+ # file. If this parameter is specified, the destination file is created with the
566
+ # specified metadata, and metadata is not copied from the source file.
567
+ # * +:timeout+ - Integer. A timeout in seconds.
568
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
569
+ # in the analytics logs when storage analytics logging is enabled.
570
+ #
571
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/copy-file
572
+ #
573
+ # Returns a tuple of (copy_id, copy_status).
574
+ #
575
+ # * +copy_id+ - String identifier for this copy operation. Use with get_file or get_file_properties to check
576
+ # the status of this copy operation, or pass to abort_copy_file to abort a pending copy.
577
+ # * +copy_status+ - String. The state of the copy operation, with these values:
578
+ # "success" - The copy completed successfully.
579
+ # "pending" - The copy is in progress.
580
+ #
581
+ def copy_file(destination_share, destination_directory_path, destination_file, source_share, source_directory_path, source_file, options = {})
582
+ source_file_uri = file_uri(source_share, source_directory_path, source_file, {}).to_s
583
+
584
+ return copy_file_from_uri(destination_share, destination_directory_path, destination_file, source_file_uri, options)
585
+ end
586
+
587
+ # Public: Aborts a pending Copy File operation and leaves a destination file with zero length and full metadata.
588
+ #
589
+ # ==== Attributes
590
+ #
591
+ # * +share+ - String. The name of the destination file share.
592
+ # * +directory_path+ - String. The path to the destination directory.
593
+ # * +file+ - String. The name of the destination file.
594
+ # * +copy_id+ - String. The copy identifier returned in the copy file operation.
595
+ # * +options+ - Hash. Optional parameters.
596
+ #
597
+ # ==== Options
598
+ #
599
+ # Accepted key/value pairs in options parameter are:
600
+ # * +:timeout+ - Integer. A timeout in seconds.
601
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
602
+ # in the analytics logs when storage analytics logging is enabled.
603
+ #
604
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/abort-copy-file
605
+ #
606
+ # Returns nil on success
607
+ def abort_copy_file(share, directory_path, file, copy_id, options = {})
608
+ query = { "comp" => "copy" }
609
+ StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
610
+ StorageService.with_query query, "copyid", copy_id
611
+
612
+ uri = file_uri(share, directory_path, file, query);
613
+ headers = {}
614
+ StorageService.with_header headers, "x-ms-copy-action", "abort";
615
+
616
+ call(:put, uri, nil, headers, options)
617
+ nil
618
+ end
619
+
620
+ # Public: Creates a new file or replaces a file with content
621
+ #
622
+ # Updating an existing file overwrites any existing metadata on the file
623
+ # Partial updates are not supported with create_file. The content of the
624
+ # existing file is overwritten with the content of the new file. To perform a
625
+ # partial update of the content of a file, use the put_range method.
626
+ #
627
+ # Note that the default content type is application/octet-stream.
628
+ #
629
+ # ==== Attributes
630
+ #
631
+ # * +share+ - String. The name of the file share.
632
+ # * +directory_path+ - String. The path to the directory.
633
+ # * +file+ - String. The name of the file.
634
+ # * +length+ - Integer. Specifies the maximum byte value for the file, up to 1 TB.
635
+ # * +content+ - String or IO. The content to put in the file.
636
+ # * +options+ - Hash. Optional parameters.
637
+ #
638
+ # ==== Options
639
+ #
640
+ # Accepted key/value pairs in options parameter are:
641
+ # * +:content_type+ - String. Content type for the file. Will be saved with file.
642
+ # * +:content_encoding+ - String. Content encoding for the file. Will be saved with file.
643
+ # * +:content_language+ - String. Content language for the file. Will be saved with file.
644
+ # * +:content_md5+ - String. Content MD5 for the file. Will be saved with file.
645
+ # * +:cache_control+ - String. Cache control for the file. Will be saved with file.
646
+ # * +:content_disposition+ - String. Conveys additional information about how to process the response payload,
647
+ # and also can be used to attach additional metadata
648
+ # * +:metadata+ - Hash. Custom metadata values to store with the file.
649
+ # * +:timeout+ - Integer. A timeout in seconds.
650
+ # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded
651
+ # in the analytics logs when storage analytics logging is enabled.
652
+ #
653
+ # See https://docs.microsoft.com/en-us/rest/api/storageservices/fileservices/create-file
654
+ #
655
+ # Returns a File
656
+ def create_file_from_content(share, directory_path, file, length, content, options = {})
657
+ options[:content_type] = get_or_apply_content_type(content, options[:content_type])
658
+ create_file(share, directory_path, file, length, options)
659
+
660
+ content = StringIO.new(content) if content.is_a? String
661
+ upload_count = (Float(length) / Float(FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES)).ceil
662
+
663
+ for idx in 0...upload_count
664
+ start_range = idx * FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES
665
+ end_range = start_range + FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES - 1
666
+ end_range = (length - 1) if end_range > (length - 1)
667
+ put_file_range(share, directory_path, file, start_range, end_range, content.read(FileConstants::DEFAULT_WRITE_SIZE_IN_BYTES))
668
+ end
669
+
670
+ # Get the file properties
671
+ get_file_properties(share, directory_path, file)
672
+ end
673
+ end