Module: Azure::Storage::Blob

Includes:
Common::Service
Included in:
BlobService
Defined in:
blob/lib/azure/storage/blob/container.rb,
blob/lib/azure/storage/blob/version.rb,
blob/lib/azure/storage/blob/autoload.rb,
blob/lib/azure/storage/blob/blob_service.rb,
blob/lib/azure/storage/blob/serialization.rb,
blob/lib/azure/storage/blob/default.rb,
blob/lib/azure/storage/blob/append.rb,
blob/lib/azure/storage/blob/block.rb,
blob/lib/azure/storage/blob/page.rb,
blob/lib/azure/storage/blob/blob.rb

Overview

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Defined Under Namespace

Modules: BlobConstants, BlobErrorCodeStrings, Container, Default, Serialization Classes: Blob, BlobService, Block, Version

Instance Method Summary collapse

Instance Method Details

#abort_copy_blob(container, blob, copy_id, options = {}) ⇒ Object

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

Attributes

  • container - String. The destination container name.

  • blob - String. The destination blob name.

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

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :lease_id - String. The lease id if the destination blob has an active infinite lease

  • :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 msdn.microsoft.com/en-us/library/azure/jj159098.aspx

Returns nil on success



855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 855

def abort_copy_blob(container, blob, 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 = blob_uri(container, blob, query);
  headers = {}
  StorageService.with_header headers, "x-ms-copy-action", "abort";

  unless options.empty?
    StorageService.with_header headers, "x-ms-lease-id", options[:lease_id]
  end

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

#acquire_blob_lease(container, blob, options = {}) ⇒ Object

Public: Establishes an exclusive write lock on a blob. The lock duration can be 15 to 60 seconds, or can be infinite. To write to a locked blob, a client must provide a lease ID.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :duration - Integer. Default -1. Specifies the duration of the lease, in seconds, or negative one (-1)

    for a lease that never expires. A non-infinite lease can be between 15 and 60 seconds. (optional)

  • :proposed_lease_id - String. Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request)

    if the proposed lease ID is not in the correct format. (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.

  • :if_modified_since - String. A DateTime value. Specify this conditional header to acquire the lease

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to acquire the lease

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to acquire the lease

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to acquire the lease

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :origin - String. Optional. Specifies the origin from which the request is issued. The presence of this header results

    in cross-origin resource sharing headers on the response.

See msdn.microsoft.com/en-us/library/azure/ee691972.aspx

Returns a String of the new unique lease id. While the lease is active, you must include the lease ID with any request to write to the blob, or to renew, change, or release the lease.



460
461
462
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 460

def acquire_blob_lease(container, blob, options = {})
  acquire_lease container, blob, options
end

#append_blob_block(container, blob, content, options = {}) ⇒ Object

Public: Commits a new block of data to the end of an existing append blob. This operation is permitted only on blobs created with the create_append_blob API.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • content - IO or String. The content of the blob.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :content_md5 - String. Content MD5 for the request contents.

  • :max_size - Integer. The max length in bytes permitted for the append blob

  • :append_position - Integer. A number indicating the byte offset to compare. It will succeed only if the append position is equal to this number

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to append a block only if

    the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to append a block only if

    the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to append a block only if

    the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to append a block only if

    the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an

    active lease, specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/mt427365.aspx

Returns a Blob



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'blob/lib/azure/storage/blob/append.rb', line 144

def append_blob_block(container, blob, content, options = {})
  query = { "comp" => "appendblock" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}
  StorageService.with_header headers, "Content-MD5", options[:content_md5]
  StorageService.with_header headers, "x-ms-lease-id", options[:lease_id]
  StorageService.with_header headers, "x-ms-blob-condition-maxsize", options[:max_size]
  StorageService.with_header headers, "x-ms-blob-condition-appendpos", options[:append_position]

  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

  response = call(:put, uri, content, headers, options)
  result = Serialization.blob_from_headers(response.headers)
  result.name = blob

  result
end

#break_blob_lease(container, blob, options = {}) ⇒ Object

Public: Breaks the lease, if the blob has an active lease. Once a lease is broken, it cannot be renewed. Any authorized request can break the lease; the request is not required to specify a matching lease ID. When a lease is broken, the lease break period is allowed to elapse, during which time no lease operation except break and release can be performed on the blob. When a lease is successfully broken, the response indicates the interval in seconds until a new lease can be acquired.

A lease that has been broken can also be released, in which case another client may immediately acquire the lease on the blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :break_period - Integer. The proposed duration of seconds that the lease should continue before it is

    broken, between 0 and 60 seconds. This break period is only used if it is shorter than
the time remaining on the lease. If longer, the time remaining on the lease is used. A
new lease will not be available before the break period has expired, but the lease may
be held for longer than the break period.

If this option is not used, a fixed-duration lease breaks after the remaining lease
period elapses, and an infinite lease breaks immediately.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to break the lease

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to break the lease

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to break the lease

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to break the lease

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :origin - String. Optional. Specifies the origin from which the request is issued. The presence of this header results

    in cross-origin resource sharing headers on the response.

See msdn.microsoft.com/en-us/library/azure/ee691972.aspx

Returns an Integer of the remaining lease time. This value is the approximate time remaining in the lease period, in seconds. This header is returned only for a successful request to break the lease. If the break is immediate, 0 is returned.



627
628
629
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 627

def break_blob_lease(container, blob, options = {})
  break_lease container, blob, options
end

#change_blob_lease(container, blob, lease, proposed_lease, options = {}) ⇒ Object

Public: Change the lease ID.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • lease - String. The existing lease id.

  • proposed_lease - String. Proposed lease ID, in a GUID string format. The Blob service returns 400 (Invalid request)

    if the proposed lease ID is not in the correct format. (optional).

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to change the lease

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to change the lease

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to change the lease

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to change the lease

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :origin - String. Optional. Specifies the origin from which the request is issued. The presence of this header results

    in cross-origin resource sharing headers on the response.

See msdn.microsoft.com/en-us/library/azure/ee691972.aspx

Returns the changed lease id



537
538
539
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 537

def change_blob_lease(container, blob, lease, proposed_lease, options = {})
  change_lease container, blob, lease, proposed_lease, options
end

#clear_blob_pages(container, blob, start_range, end_range, options = {}) ⇒ Object

Public: Clears a range of pages from the blob.

Attributes

  • container - String. Name of container.

  • blob - String. Name of blob.

  • start_range - Integer. Position of first byte of first page.

  • end_range - Integer. Position of last byte of of last page.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to clear the page only if

    the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to clear the page only if

    the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to clear the page only if

    the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to clear the page only if

    the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/ee691975.aspx

Returns Blob



220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'blob/lib/azure/storage/blob/page.rb', line 220

def clear_blob_pages(container, blob, start_range, end_range, options = {})
  query = { "comp" => "page" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

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

  # clear default content type
  StorageService.with_header headers, "Content-Type", ""

  # set optional headers
  unless options.empty?
    add_blob_conditional_headers options, headers
  end

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

  result = Serialization.blob_from_headers(response.headers)
  result.name = blob

  result
end

#commit_blob_blocks(container, blob, block_list, options = {}) ⇒ Object

Public: Commits existing blob blocks to a blob.

This method writes a blob by specifying the list of block IDs that make up the blob. In order to be written as part of a blob, a block must have been successfully written to the server in a prior put_blob_block method.

You can call Put Block List to update a blob by uploading only those blocks that have changed, then committing the new and existing blocks together. You can do this by specifying whether to commit a block from the committed block list or from the uncommitted block list, or to commit the most recently uploaded version of the block, whichever list it may belong to.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • block_list - Array. A ordered list of lists in the following format:

    [“block_id1”, :committed], [“block_id2”, :uncommitted], [“block_id3”], [“block_id4”, :committed]…

    The first element of the inner list is the block_id, the second is optional and can be either :committed or :uncommitted to indicate in which group of blocks the id should be looked for. If it is omitted, the latest of either group will be used.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :transactional_md5 - String. Content MD5 for the request contents (not the blob contents!)

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

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

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

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

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

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

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

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an

    active lease, specify the valid lease ID for this header.

This operation also supports the use of conditional headers to commit the block list if a specified condition is met. For more information, see msdn.microsoft.com/en-us/library/azure/dd179371.aspx

See msdn.microsoft.com/en-us/library/azure/dd179467.aspx

Returns nil on success



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
 
# File 'blob/lib/azure/storage/blob/block.rb', line 200

def commit_blob_blocks(container, blob, block_list, options = {})
  query = { "comp" => "blocklist" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}
  unless options.empty?
    StorageService.with_header headers, "Content-MD5", options[:transactional_md5]
    StorageService.with_header headers, "x-ms-blob-content-type", options[:content_type]
    StorageService.with_header headers, "x-ms-blob-content-encoding", options[:content_encoding]
    StorageService.with_header headers, "x-ms-blob-content-language", options[:content_language]
    StorageService.with_header headers, "x-ms-blob-content-md5", options[:content_md5]
    StorageService.with_header headers, "x-ms-blob-cache-control", options[:cache_control]
    StorageService.with_header headers, "x-ms-blob-content-disposition", options[:content_disposition]

    StorageService.add_metadata_to_headers(options[:metadata], headers)
    add_blob_conditional_headers(options, headers)
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end
  headers["x-ms-blob-content-type"] = Default::CONTENT_TYPE_VALUE unless headers["x-ms-blob-content-type"]
  body = Serialization.block_list_to_xml(block_list)
  call(:put, uri, body, headers, options)
  nil
end

#copy_blob(destination_container, destination_blob, source_container, source_blob, options = {}) ⇒ Object

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

Attributes

  • destination_container - String. The destination container name to copy to.

  • destination_blob - String. The destination blob name to copy to.

  • source_container - String. The source container name to copy from.

  • source_blob - String. The source blob name to copy from.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :source_snapshot - String. A snapshot id for the source blob

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

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

  • :source_if_modified_since - String. A DateTime value. Specify this option to write the page only if the source blob

    has been modified since the specified date/time. If the blob has not been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :source_if_unmodified_since - String. A DateTime value. Specify this option to write the page only if the source blob

    has not been modified since the specified date/time. If the blob has been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :source_if_match - String. An ETag value. Specify an ETag value to write the page only if the source blob's

    ETag value matches the value specified. If the values do not match, the Blob
service returns status code 412 (Precondition Failed).

  • :source_if_none_match - String. An ETag value. Specify an ETag value to write the page only if the source blob's

    ETag value does not match the value specified. If the values are identical, the
Blob service returns status code 412 (Precondition Failed).

  • :dest_if_modified_since - String. A DateTime value. Specify this option to write the page only if the destination

    blob has been modified since the specified date/time. If the blob has not been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :dest_if_unmodified_since - String. A DateTime value. Specify this option to write the page only if the destination

    blob has not been modified since the specified date/time. If the blob has been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :dest_if_match - String. An ETag value. Specify an ETag value to write the page only if the destination

    blob's ETag value matches the value specified. If the values do not match, the
Blob service returns status code 412 (Precondition Failed).

  • :dest_if_none_match - String. An ETag value. Specify an ETag value to write the page only if the destination

    blob's ETag value does not match the value specified. If the values are
identical, the Blob service returns status code 412 (Precondition Failed).

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

  • :lease_id - String. Required if the destination blob has an active lease. The lease ID specified for

    this header must match the lease ID of the destination blob. If the request does not include
the lease ID or it is not valid, the operation fails with status code 412 (Precondition Failed).
If this header is specified and the destination blob does not currently have an active lease,
the operation will also fail with status code 412 (Precondition Failed).
In version 2012-02-12 and newer, this value must specify an active, infinite lease for a
leased blob. A finite-duration lease ID fails with 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd894037.aspx

Returns a tuple of (copy_id, copy_status).

  • copy_id - String identifier for this copy operation. Use with get_blob or get_blob_properties to check

    the status of this copy operation, or pass to abort_copy_blob 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.


829
830
831
832
833
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 829

def copy_blob(destination_container, destination_blob, source_container, source_blob, options = {})
  source_blob_uri = blob_uri(source_container, source_blob, options[:source_snapshot] ? { "snapshot" => options[:source_snapshot] } : {}).to_s

  return copy_blob_from_uri(destination_container, destination_blob, source_blob_uri, options)
end

#copy_blob_from_uri(destination_container, destination_blob, source_uri, options = {}) ⇒ Object

Public: Copies a source blob or file to a destination blob.

Attributes

  • destination_container - String. The destination container name to copy to.

  • destination_blob - String. The destination blob name to copy to.

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

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :source_snapshot - String. A snapshot id for the source blob

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

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

  • :source_if_modified_since - String. A DateTime value. Specify this option to write the page only if the source blob

    has been modified since the specified date/time. If the blob has not been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :source_if_unmodified_since - String. A DateTime value. Specify this option to write the page only if the source blob

    has not been modified since the specified date/time. If the blob has been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :source_if_match - String. An ETag value. Specify an ETag value to write the page only if the source blob's

    ETag value matches the value specified. If the values do not match, the Blob
service returns status code 412 (Precondition Failed).

  • :source_if_none_match - String. An ETag value. Specify an ETag value to write the page only if the source blob's

    ETag value does not match the value specified. If the values are identical, the
Blob service returns status code 412 (Precondition Failed).

  • :dest_if_modified_since - String. A DateTime value. Specify this option to write the page only if the destination

    blob has been modified since the specified date/time. If the blob has not been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :dest_if_unmodified_since - String. A DateTime value. Specify this option to write the page only if the destination

    blob has not been modified since the specified date/time. If the blob has been
modified, the Blob service returns status code 412 (Precondition Failed).

  • :dest_if_match - String. An ETag value. Specify an ETag value to write the page only if the destination

    blob's ETag value matches the value specified. If the values do not match, the
Blob service returns status code 412 (Precondition Failed).

  • :dest_if_none_match - String. An ETag value. Specify an ETag value to write the page only if the destination

    blob's ETag value does not match the value specified. If the values are
identical, the Blob service returns status code 412 (Precondition Failed).

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

  • :lease_id - String. Required if the destination blob has an active lease. The lease ID specified for

    this header must match the lease ID of the destination blob. If the request does not include
the lease ID or it is not valid, the operation fails with status code 412 (Precondition Failed).
If this header is specified and the destination blob does not currently have an active lease,
the operation will also fail with status code 412 (Precondition Failed).
In version 2012-02-12 and newer, this value must specify an active, infinite lease for a
leased blob. A finite-duration lease ID fails with 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd894037.aspx

Returns a tuple of (copy_id, copy_status).

  • copy_id - String identifier for this copy operation. Use with get_blob or get_blob_properties to check

    the status of this copy operation, or pass to abort_copy_blob 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.


748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 748

def copy_blob_from_uri(destination_container, destination_blob, source_uri, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(destination_container, destination_blob, query)
  headers = {}
  StorageService.with_header headers, "x-ms-copy-source", source_uri

  unless options.empty?
    add_blob_conditional_headers options, headers
    StorageService.add_metadata_to_headers options[:metadata], headers
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end

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

#create_append_blob(container, blob, options = {}) ⇒ Object

Public: Creates a new append blob. Note that calling create_append_blob to create an append blob only initializes the blob. To add content to an append blob, call append_blob_blocks method.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

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

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

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

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

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

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179451.aspx

Returns a Blob



70
71
72
73
74
75
76
77
78
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
 
# File 'blob/lib/azure/storage/blob/append.rb', line 70

def create_append_blob(container, blob, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout] if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}

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

  # ensure content-length is 0
  StorageService.with_header headers, "Content-Length", 0

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

  StorageService.add_metadata_to_headers options[:metadata], headers
  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  headers["x-ms-blob-content-type"] = Default::CONTENT_TYPE_VALUE unless headers["x-ms-blob-content-type"]

  # call PutBlob with empty body
  response = call(:put, uri, nil, headers, options)

  result = Serialization.blob_from_headers(response.headers)
  result.name = blob
  result.metadata = options[:metadata] if options[:metadata]

  result
end

#create_append_blob_from_content(container, blob, content, options = {}) ⇒ Object

Public: Creates a new append blob with given content

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • content - IO or String. Content to write.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

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

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

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

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

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

    and also can be used to attach additional metadata

  • :max_size - Integer. The max length in bytes permitted for the append blob.

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

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179451.aspx

Returns a Blob



208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'blob/lib/azure/storage/blob/append.rb', line 208

def create_append_blob_from_content(container, blob, content, options = {})
  # Fail fast if content has larger size than max_size
  max_size = options.delete :max_size
  if max_size
    if content.respond_to?(:size) && max_size < content.size
      raise Azure::Storage::Common::Core::StorageError.new("Given content has exceeded the specified maximum size for the blob.")
    end
  end
  options[:content_type] = get_or_apply_content_type(content, options[:content_type])
  create_append_blob(container, blob, options)
  content = StringIO.new(content) if content.is_a? String
  # initialize the append block options.
  append_block_options = {}
  append_block_options[:if_modified_since] = options[:if_modified_since] if options[:if_modified_since]
  append_block_options[:if_unmodified_since] = options[:if_unmodified_since] if options[:if_unmodified_since]
  append_block_options[:if_match] = options[:if_match] if options[:if_match]
  append_block_options[:if_none_match] = options[:if_none_match] if options[:if_none_match]
  append_block_options[:lease_id] = options[:lease_id] if options[:lease_id]
  append_block_options[:max_size] = max_size if max_size
  position = 0
  while !content.eof?
    payload = content.read(BlobConstants::DEFAULT_WRITE_BLOCK_SIZE_IN_BYTES)
    # set the append position to make sure that each append is going to the correct offset.
    append_block_options[:append_position] = position
    append_blob_block(container, blob, payload, append_block_options)
    # calculate the position after the append.
    position += payload.size
  end

  get_properties_options = {}
  get_properties_options[:lease_id] = options[:lease_id] if options[:lease_id]

  # Get the blob properties
  get_blob_properties(container, blob, get_properties_options)
end

#create_blob_snapshot(container, blob, options = {}) ⇒ Object

Public: Creates a snapshot of a blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create the blob snapshot

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create the blob snapshot

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create the blob snapshot

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create the blob snapshot

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:
 - The blob's lease is currently active.
 - The lease ID specified in the request matches that of the blob.
If this header is specified and both of these conditions are not met, the request will fail
and the Snapshot Blob operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/ee691971.aspx

Returns the snapshot DateTime value



668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 668

def create_blob_snapshot(container, blob, options = {})
  query = { "comp" => "snapshot" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}
  unless options.empty?
    StorageService.add_metadata_to_headers(options[:metadata], headers)
    add_blob_conditional_headers(options, headers)
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end

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

  response.headers["x-ms-snapshot"]
end

#create_block_blob(container, blob, content, options = {}) ⇒ Object Also known as: create_block_blob_from_content

Public: Creates a new block blob or updates the content of an existing block blob.

Updating an existing block blob overwrites any existing metadata on the blob Partial updates are not supported with create_block_blob the content of the existing blob is overwritten with the content of the new blob. To perform a partial update of the content of a block blob, use the create_block_list method.

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

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • content - IO or String. The content of the blob.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

    When this header is specified, the storage service checks the hash that has arrived with the one that was sent.
If the two hashes do not match, the operation will fail with error code 400 (Bad Request).

  • :single_upload_threshold - Integer. Threshold in bytes for single upload, must be lower than 256MB or 256MB will be used.

  • :content_length - Integer. Length of the content to upload, must be specified if 'content' does not implement 'size'.

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

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

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

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

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

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

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179451.aspx

Returns a Blob



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'blob/lib/azure/storage/blob/block.rb', line 98

def create_block_blob(container, blob, content, options = {})
  size = if content.respond_to? :size
    content.size
  elsif options[:content_length]
    options[:content_length]
  else
    raise ArgumentError, "Either optional parameter 'content_length' should be set or 'content' should implement 'size' method to get payload's size."
  end

  threshold = get_single_upload_threshold(options[:single_upload_threshold])
  if size > threshold
    create_block_blob_multiple_put(container, blob, content, size, options)
  else
    create_block_blob_single_put(container, blob, content, options)
  end
end

#create_page_blob(container, blob, length, options = {}) ⇒ Object

Public: Creates a new page blob. Note that calling create_page_blob to create a page blob only initializes the blob. To add content to a page blob, call put_blob_pages method.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • length - Integer. Specifies the maximum size for the page blob, up to 1 TB.

    The page blob size must be aligned to a 512-byte boundary.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

    When this header is specified, the storage service checks the hash that has arrived with the one that was sent.
If the two hashes do not match, the operation will fail with error code 400 (Bad Request).

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

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

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

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

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

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

  • :sequence_number - Integer. The sequence number is a user-controlled value that you can use to track requests.

    The value of the sequence number must be between 0 and 2^63 - 1.The default value is 0.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179451.aspx

Returns a Blob



76
77
78
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
113
114
115
116
 
# File 'blob/lib/azure/storage/blob/page.rb', line 76

def create_page_blob(container, blob, length, options = {})
  query = {}
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}

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

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

  # set x-ms-sequence-number from options (or default to 0)
  StorageService.with_header headers, "x-ms-sequence-number", (options[:sequence_number] || 0).to_s

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

  StorageService.add_metadata_to_headers options[:metadata], headers
  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  headers["x-ms-blob-content-type"] = Default::CONTENT_TYPE_VALUE unless headers["x-ms-blob-content-type"]

  # call PutBlob with empty body
  response = call(:put, uri, nil, headers, options)

  result = Serialization.blob_from_headers(response.headers)
  result.name = blob
  result.metadata = options[:metadata] if options[:metadata]

  result
end

#create_page_blob_from_content(container, blob, length, content, options = {}) ⇒ Object

Public: Creates a new page blob filled with given content.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • length - Integer. Specifies the maximum size for the page blob, up to 1 TB.

    The page blob size must be aligned to a 512-byte boundary.

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

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

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

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

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

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

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

  • :sequence_number - Integer. The sequence number is a user-controlled value that you can use to track requests.

    The value of the sequence number must be between 0 and 2^63 - 1.The default value is 0.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create a new blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create a new blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179451.aspx

Returns a Blob



546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
 
# File 'blob/lib/azure/storage/blob/page.rb', line 546

def create_page_blob_from_content(container, blob, length, content, options = {})
  options[:content_type] = get_or_apply_content_type(content, options[:content_type])
  create_page_blob(container, blob, length, options)

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

  for idx in 0...upload_count
    start_range = idx * BlobConstants::DEFAULT_WRITE_PAGE_SIZE_IN_BYTES
    end_range = start_range + BlobConstants::DEFAULT_WRITE_PAGE_SIZE_IN_BYTES - 1
    end_range = (length - 1) if end_range > (length - 1)
    put_blob_pages(container, blob, start_range, end_range, content.read(BlobConstants::DEFAULT_WRITE_PAGE_SIZE_IN_BYTES), lease_id: options[:lease_id])
  end

  get_properties_options = {}
  get_properties_options[:lease_id] = options[:lease_id] if options[:lease_id]
  # Get the blob properties
  get_blob_properties(container, blob, get_properties_options)
end

#delete_blob(container, blob, options = {}) ⇒ Object

Public: Deletes a blob or blob snapshot.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from. (optional)

  • :delete_snapshots - Symbol. Used to specify the scope of the delete operation for snapshots.

    This parameter is ignored if a blob does not have snapshots, or if a
snapshot is specified in the snapshot parameter. (optional)

Possible values include:
  * +:only+     - Deletes only the snapshots for the blob, but leaves the blob
  * +:include+  - Deletes the blob and all of the snapshots for the blob

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to create the blob snapshot

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to create the blob snapshot

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to create the blob snapshot

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to create the blob snapshot

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an

    active lease, specify the valid lease ID for this header. If a valid lease ID is not specified
on the request, the operation will fail with status code 403 (Forbidden).

See msdn.microsoft.com/en-us/library/azure/dd179440.aspx

Returns nil on success



914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 914

def delete_blob(container, blob, options = {})
  query = {}
  StorageService.with_query query, "snapshot", options[:snapshot]
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  options[:delete_snapshots] = :include unless options[:delete_snapshots]

  headers = {}
  StorageService.with_header headers, "x-ms-delete-snapshots", options[:delete_snapshots].to_s if options[:delete_snapshots] && options[:snapshot] == nil
  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

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

#get_blob(container, blob, options = {}) ⇒ Object

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

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :start_range - Integer. Position of first byte of first page. (optional)

  • :end_range - Integer. Position of last byte of of last page. (optional)

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from. (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.

  • :if_modified_since - String. A DateTime value. Specify this conditional header to get the blob

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to get the blob

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:
 - The blob's lease is currently active.
 - The lease ID specified in the request matches that of the blob.
If this header is specified and both of these conditions are not met, the request will fail
and the Get Blob operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd179440.aspx

Returns a blob and the blob body



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 89

def get_blob(container, blob, options = {})
  query = {}
  StorageService.with_query query, "snapshot", options[:snapshot]
  StorageService.with_query query, "timeout", options[:timeout] if options[:timeout]

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = blob_uri(container, blob, 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
  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

  response = call(:get, uri, nil, headers, options)
  result = Serialization.blob_from_headers(response.headers)
  result.name = blob unless result.name

  return result, response.body
end

#get_blob_metadata(container, blob, options = {}) ⇒ Object

Public: Returns metadata on the blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to get the blob metadata

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to get the blob metadata

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob metadata

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob metadata

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:

 - The blob's lease is currently active.
 - The lease ID specified in the request matches that of the blob.

If this header is specified and both of these conditions are not met, the request will fail
and the Get Blob Metadata operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd179350.aspx

Returns a Blob



349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 349

def get_blob_metadata(container, blob, options = {})
  query = { "comp" => "metadata" }
  StorageService.with_query query, "snapshot", options[:snapshot]
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  headers = {}
  unless options.empty?
    add_blob_conditional_headers options, headers
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = blob_uri(container, blob, query, options)
  response = call(:get, uri, nil, headers, options)
  result = Serialization.blob_from_headers(response.headers)

  result.name = blob
  result.snapshot = options[:snapshot]

  result
end

#get_blob_properties(container, blob, options = {}) ⇒ Object

Public: Returns all properties and metadata on the blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to get the blob properties

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to get the blob properties

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob properties

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to get the blob properties

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:

 - The blob's lease is currently active.
 - The lease ID specified in the request matches that of the blob.

If this header is specified and both of these conditions are not met, the request will fail
and the Get Blob Properties operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd179394.aspx

Returns the blob properties with a Blob instance



155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 155

def get_blob_properties(container, blob, options = {})
  query = {}
  StorageService.with_query query, "snapshot", options[:snapshot]
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  headers = {}
  unless options.empty?
    add_blob_conditional_headers options, headers
  end
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = blob_uri(container, blob, query, options)

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

  result = Serialization.blob_from_headers(response.headers)

  result.name = blob
  result.snapshot = options[:snapshot]

  result
end

#incremental_copy_blob(destination_container, destination_blob, source_uri, options = {}) ⇒ Object

Public: Copies a snapshot of the source page blob to a destination page blob. The snapshot is copied such that only the differential changes between the previously copied snapshot are transferred to the destination. The copied snapshots are complete copies of the original snapshot and can be read or copied from as usual.The destination of an incremental copy must either not exist, or must have been created with a previous incremental copy from the same source blob. Once created, the destination blob is permanently associated with the source and may only be used for incremental copies. The Get Blob Properties and List Blobs APIs indicate whether the blob is an incremental copy blob created in this way. Incremental copy blobs may not be downloaded directly. The only supported operations are Get Blob Properties, Incremental Copy Blob, and Delete Blob. The copied snapshots may be read and deleted as usual.

Attributes

  • destination_container - String. The destination container name to copy to.

  • destination_blob - String. The destination blob name to copy to.

  • source_uri - String. Specifies the URI of the source page blob snapshot.

    This value is a URL of up to 2 KB in length that specifies a page blob snapshot. The
value should be URL-encoded as it would appear in a request URI. The source blob must
either be public or must be authenticated via a shared access signature. Here is an
example of a source blob URL:
  https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>

  • 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 blob metadata to the destination
blob. If this parameter is specified, the destination blob is created with the
specified metadata, and metadata is not copied from the source blob.

  • :if_modified_since - String. A DateTime value. Specify this conditional header to copy the blob only if the

    destination blob has been modified since the specified date/time. If the destination blob
has not been modified, the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to copy the blob only if the

    destination blob has not been modified since the specified date/time. If the destination
blob has been modified, the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to copy the blob

    only if the specified ETag value matches the ETag value for an existing destination blob.
If the ETag for the destination blob does not match the ETag specified for If-Match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value, or the wildcard character (*). Specify an ETag value for this

    conditional header to copy the blob only if the specified ETag value does not match the
ETag value for the destination blob. Specify the wildcard character (*) to perform the
operation only if the destination blob does not exist. If the specified condition isn't met,
the Blob service returns status code 412 (Precondition Failed).

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

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:
  - The blob's lease is currently active.
  - The lease ID specified in the request matches that of the blob.
If this header is specified and both of these conditions are not met, the request will fail
and the Snapshot Blob operation will fail with status code 412 (Precondition Failed).

See docs.microsoft.com/en-us/rest/api/storageservices/incremental-copy-blob

Returns a tuple of (copy_id, copy_status).

  • copy_id - String. String identifier for this copy operation. Use with Get Blob Properties to check

    the status of this copy operation, or pass to Abort Copy Blob to abort a pending copy.

  • copy_status - String. State of the copy operation. This is always pending to indicate that the copy has

    started and is in progress.


418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
 
# File 'blob/lib/azure/storage/blob/page.rb', line 418

def incremental_copy_blob(destination_container, destination_blob, source_uri, options = {})
  # query parameters
  query = { Azure::Storage::Common::QueryStringConstants::COMP => Azure::Storage::Common::QueryStringConstants::INCREMENTAL_COPY }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  # URI
  uri = blob_uri(destination_container, destination_blob, query)

  # headers
  headers = {}
  StorageService.with_header headers, "x-ms-copy-source", source_uri
  unless options.empty?
    add_blob_conditional_headers options, headers
    StorageService.add_metadata_to_headers options[:metadata], headers
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end

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

#list_blob_blocks(container, blob, options = {}) ⇒ Object

Public: Retrieves the list of blocks that have been uploaded as part of a block blob.

There are two block lists maintained for a blob: 1) Committed Block List: The list of blocks that have been successfully

committed to a given blob with commitBlobBlocks.

2) Uncommitted Block List: The list of blocks that have been uploaded for a

blob using Put Block (REST API), but that have not yet been committed.
These blocks are stored in Microsoft Azure in association with a blob, but do
not yet form part of the blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :blocklist_type - Symbol. One of :all, :committed, :uncommitted. Defaults to :all (optional)

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from. (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.

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:
  - The blob's lease is currently active.
  - The lease ID specified in the request matches that of the blob.
If this header is specified and both of these conditions are not met, the request will fail
and the operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/dd179400.aspx

Returns a list of Azure::Storage::Entity::Blob::Block instances



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'blob/lib/azure/storage/blob/block.rb', line 263

def list_blob_blocks(container, blob, options = {})
  options[:blocklist_type] = options[:blocklist_type] || :all

  query = { "comp" => "blocklist" }
  StorageService.with_query query, "snapshot", options[:snapshot]
  StorageService.with_query query, "blocklisttype", options[:blocklist_type].to_s if options[:blocklist_type]
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {}

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = blob_uri(container, blob, query, options)

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

  Serialization.block_list_from_xml(response.body)
end

#list_page_blob_ranges(container, blob, options = {}) ⇒ Object

Public: Returns a list of active page ranges for a page blob. Active page ranges are those that have been populated with data.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :start_range - Integer. Position of first byte of first page. (optional)

  • :end_range - Integer. Position of last byte of of last page. (optional)

  • :snapshot - String. An opaque DateTime value that specifies the blob snapshot to

    retrieve information from. (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.

  • :if_modified_since - String. A DateTime value. Specify this conditional header to list the pages only if

    the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to list the pages only if

    the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to list the pages only if

    the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to list the pages only if

    the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :previous_snapshot - String. An opaque DateTime value that specifies that the response will contain only pages that

    were changed between target blob and previous snapshot. Changed pages include both updated and
cleared pages. The target blob may be a snapshot, as long as the snapshot specified by this
is the older of the two.

  • :lease_id - String. If this header is specified, the operation will be performed only if both of the

    following conditions are met:
 - The blob's lease is currently active.
 - The lease ID specified in the request matches that of the blob.
If this header is specified and both of these conditions are not met, the request will fail
and the Get Blob operation will fail with status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/ee691973.aspx

Returns a list of page ranges in the format [ [start, end], [start, end], … ]

e.g. [ [0, 511], [512, 1024], ... ]


296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'blob/lib/azure/storage/blob/page.rb', line 296

def list_page_blob_ranges(container, blob, options = {})
  query = { "comp" => "pagelist" }
  query.update("snapshot" => options[:snapshot]) if options[:snapshot]
  query.update("prevsnapshot" => options[:previous_snapshot]) if options[:previous_snapshot]
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY
  uri = blob_uri(container, blob, 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]
  add_blob_conditional_headers options, headers
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

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

  pagelist = Serialization.page_list_from_xml(response.body)
  pagelist
end

#put_blob_block(container, blob, block_id, content, options = {}) ⇒ Object

Public: Creates a new block to be committed as part of a block blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • block_id - String. The block id. Note: this should be the raw block id, not Base64 encoded.

  • content - IO or String. The content of the blob.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :content_md5 - String. Content MD5 for the request contents.

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

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an

    active lease, specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd135726.aspx

Returns response of the operation



138
139
140
141
142
143
144
145
146
147
148
149
150
151
 
# File 'blob/lib/azure/storage/blob/block.rb', line 138

def put_blob_block(container, blob, block_id, content, options = {})
  query = { "comp" => "block" }
  StorageService.with_query query, "blockid", Base64.strict_encode64(block_id)
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}
  StorageService.with_header headers, "Content-MD5", options[:content_md5]
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

  response = call(:put, uri, content, headers, options)
  response.headers["Content-MD5"]
end

#put_blob_pages(container, blob, start_range, end_range, content, options = {}) ⇒ Object

Public: Creates a range of pages in a page blob.

Attributes

  • container - String. Name of container

  • blob - String. Name of blob

  • start_range - Integer. Position of first byte of first page

  • end_range - Integer. Position of last byte of of last page

  • content - IO or String. Content to write. Length in bytes should equal end_range - start_range + 1

  • options - Hash. A collection of options.

Options

Accepted key/value pairs in options parameter are:

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

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

  • :if_sequence_number_le - Integer. If the blob's sequence number is less than or equal to the specified value, the request proceeds;

    otherwise it fails with the SequenceNumberConditionNotMet error (HTTP status code 412 - Precondition Failed).

  • :if_sequence_number_lt - Integer. If the blob's sequence number is less than the specified value, the request proceeds;

    otherwise it fails with SequenceNumberConditionNotMet error (HTTP status code 412 - Precondition Failed).

  • :if_sequence_number_eq - Integer. If the blob's sequence number is equal to the specified value, the request proceeds;

    otherwise it fails with SequenceNumberConditionNotMet error (HTTP status code 412 - Precondition Failed).

  • :if_modified_since - String. A DateTime value. Specify this conditional header to write the page only if

    the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to write the page only if

    the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to write the page only if

    the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to write the page only if

    the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

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

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active lease,

    specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/ee691975.aspx

Returns Blob



161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'blob/lib/azure/storage/blob/page.rb', line 161

def put_blob_pages(container, blob, start_range, end_range, content, options = {})
  query = { "comp" => "page" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, 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-page-write", "update"

  # clear default content type
  StorageService.with_header headers, "Content-Type", ""
  headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]

  # set optional headers
  unless options.empty?
    add_blob_conditional_headers options, headers
  end

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

  result = Serialization.blob_from_headers(response.headers)
  result.name = blob

  result
end

#release_blob_lease(container, blob, lease, options = {}) ⇒ Object

Public: Releases the lease. The lease may be released if the lease ID specified on the request matches that associated with the blob. Releasing the lease allows another client to immediately acquire the lease for the blob as soon as the release is complete.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • lease - String. The lease id.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to release the lease

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to release the lease

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to release the lease

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to release the lease

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :origin - String. Optional. Specifies the origin from which the request is issued. The presence of this header results

    in cross-origin resource sharing headers on the response.

See msdn.microsoft.com/en-us/library/azure/ee691972.aspx

Returns nil on success



575
576
577
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 575

def release_blob_lease(container, blob, lease, options = {})
  release_lease container, blob, lease, options
end

#renew_blob_lease(container, blob, lease, options = {}) ⇒ Object

Public: Renews the lease. The lease can be renewed if the lease ID specified on the request matches that associated with the blob. Note that the lease may be renewed even if it has expired as long as the blob has not been modified or leased again since the expiration of that lease. When you renew a lease, the lease duration clock resets.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • lease - String. The lease id

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to renew the lease

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to renew the lease

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to renew the lease

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to renew the lease

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :origin - String. Optional. Specifies the origin from which the request is issued. The presence of this header results

    in cross-origin resource sharing headers on the response.

See msdn.microsoft.com/en-us/library/azure/ee691972.aspx

Returns the renewed lease id



499
500
501
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 499

def renew_blob_lease(container, blob, lease, options = {})
  renew_lease container, blob, lease, options
end

#resize_page_blob(container, blob, size, options = {}) ⇒ Object

Public: Resizes a page blob to the specified size.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • size - String. The blob size. Resizes a page blob to the specified size.

    If the specified value is less than the current size of the blob,
then all pages 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.

  • :if_modified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/ee691966.aspx

Returns nil on success.



351
352
353
354
 
# File 'blob/lib/azure/storage/blob/page.rb', line 351

def resize_page_blob(container, blob, size, options = {})
  options = { content_length: size }.merge(options)
  set_blob_properties container, blob, options
end

#set_blob_metadata(container, blob, metadata, options = {}) ⇒ Object

Public: Sets metadata headers on the blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • metadata - Hash. The custom metadata.

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to set the blob metadata

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to set the blob metadata

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob metadata

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob metadata

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active

    lease, specify the valid lease ID for this header.

See msdn.microsoft.com/en-us/library/azure/dd179414.aspx

Returns nil on success.



404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 404

def set_blob_metadata(container, blob, metadata, options = {})
  query = { "comp" => "metadata" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]

  uri = blob_uri(container, blob, query)

  headers = {}
  StorageService.add_metadata_to_headers metadata, headers
  unless options.empty?
    add_blob_conditional_headers options, headers
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end

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

#set_blob_properties(container, blob, options = {}) ⇒ Object

Public: Sets system properties defined for a blob.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

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

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

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

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

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

  • :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 page blob to the specified size. If the specified

    value is less than the current size of the blob, then all pages above
the specified value are cleared. This property cannot be used to change
the size of a block blob. Setting this property for a block blob returns
status code 400 (Bad Request).

  • :sequence_number_action - Symbol. This property indicates how the service should modify the sequence

                                 number for the blob. Required if :sequence_number is used. This property
                             applies to page blobs only.

                             Specify one of the following options for this property:

* +:max+                       - Sets the sequence number to be the higher of the value included with
                                 the request and the value currently stored for the blob.
* +:update+                    - Sets the sequence number to the value included with the request.
* +:increment+                 - Increments the value of the sequence number by 1. If specifying this
                                 option, do not include the sequence_number option; doing so will return
                                 status code 400 (Bad Request).

  • :sequence_number - Integer. This property sets the blob's sequence number. The sequence number is a

    user-controlled property that you can use to track requests and manage concurrency
issues. Required if the :sequence_number_action option is set to :max or :update.
This property applies to page blobs only.

Use this together with the :sequence_number_action to update the blob's sequence
number, either to the specified value or to the higher of the values specified with
the request or currently stored with the blob.

This header should not be specified if :sequence_number_action is set to :increment;
in this case the service automatically increments the sequence number by one.

To set the sequence number to a value of your choosing, this property must be specified
together with :sequence_number_action

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

  • :lease_id - String. Required if the blob has an active lease. To perform this operation on a blob with an active

    lease, specify the valid lease ID for this header.

Remarks:

The semantics for updating a blob's properties are as follows:

  • A page blob's sequence number is updated only if the request meets either of the following conditions:

    * The :sequence_number_action property is set to :max or :update, and a value for :sequence_number is also set.
* The :sequence_number_action property is set to :increment, indicating that the service should increment
  the sequence number by one.

  • The size of the page blob is modified only if a value for :content_length is specified.

  • If :sequence_number and/or :content_length are the only properties specified, then the other properties of the blob will NOT be modified.

  • If any one or more of the following properties are set, then all of these properties are set together. If a value is not provided for a given property when at least one of the properties listed below is set, then that property will be cleared for the blob.

    * :cache_control
* :content_type
* :content_md5
* :content_encoding
* :content_language
* :content_disposition

See msdn.microsoft.com/en-us/library/azure/ee691966.aspx

Returns nil on success.



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
 
# File 'blob/lib/azure/storage/blob/blob.rb', line 276

def set_blob_properties(container, blob, options = {})
  query = { "comp" => "properties" }
  StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
  uri = blob_uri(container, blob, query)

  headers = {}

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

    if options[:sequence_number_action]
      StorageService.with_header headers, "x-ms-sequence-number-action", options[:sequence_number_action]

      if options[:sequence_number_action].to_s != "increment" && options[:sequence_number]
        StorageService.with_header headers, "x-ms-blob-sequence-number", options[:sequence_number] 
      end
    end

    add_blob_conditional_headers options, headers
    headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id]
  end
  call(:put, uri, nil, headers, options)
  nil
end

#set_sequence_number(container, blob, action, number, options = {}) ⇒ Object

Public: Sets a page blob's sequence number.

Attributes

  • container - String. The container name.

  • blob - String. The blob name.

  • action - Symbol. Indicates how the service should modify the sequence

                                 number for the blob. Required if :sequence_number is used. This property
                             applies to page blobs only.

                             Specify one of the following options for this property:

* +:max+                       - Sets the sequence number to be the higher of the value included with
                                 the request and the value currently stored for the blob.
* +:update+                    - Sets the sequence number to the value included with the request.
* +:increment+                 - Increments the value of the sequence number by 1. If specifying this
                                 option, do not include the sequence_number option; doing so will return
                                 status code 400 (Bad Request).

  • number - Integer. Sets the blob's sequence number. The sequence number is a

    user-controlled property that you can use to track requests and manage concurrency
issues. Required if the 'action' parameter is set to :max or :update.
This property applies to page blobs only.

Use this together with the 'action' parameter to update the blob's sequence
number, either to the specified value or to the higher of the values specified with
the request or currently stored with the blob.

This header should not be specified if the 'action' parameter is set to :increment;
in this case the service automatically increments the sequence number by one.

To set the sequence number to a value of your choosing, this property must be specified
together with the 'action' parameter

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

  • :if_modified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has been modified since the specified date/time. If the blob has not been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_unmodified_since - String. A DateTime value. Specify this conditional header to set the blob properties

    only if the blob has not been modified since the specified date/time. If the blob has been modified,
the Blob service returns status code 412 (Precondition Failed).

  • :if_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value matches the value specified. If the values do not match,
the Blob service returns status code 412 (Precondition Failed).

  • :if_none_match - String. An ETag value. Specify an ETag value for this conditional header to set the blob properties

    only if the blob's ETag value does not match the value specified. If the values are identical,
the Blob service returns status code 412 (Precondition Failed).

See msdn.microsoft.com/en-us/library/azure/ee691966.aspx

Returns nil on success.



496
497
498
499
 
# File 'blob/lib/azure/storage/blob/page.rb', line 496

def set_sequence_number(container, blob, action, number, options = {})
  options = { sequence_number_action: action, sequence_number: number }.merge(options)
  set_blob_properties container, blob, options
end