azure-storage-file 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -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