lib/azure/storage/blob/container.rb in azure-storage-blob-1.1.0 vs lib/azure/storage/blob/container.rb in azure-storage-blob-2.0.0

- old
+ new

@@ -1,634 +1,634 @@ -# frozen_string_literal: true - -#------------------------------------------------------------------------- -# # Copyright (c) Microsoft and contributors. All rights reserved. -# -# The MIT License(MIT) - -# Permission is hereby granted, free of charge, to any person obtaining a copy -# of this software and associated documentation files(the "Software"), to deal -# in the Software without restriction, including without limitation the rights -# to use, copy, modify, merge, publish, distribute, sublicense, and / or sell -# copies of the Software, and to permit persons to whom the Software is -# furnished to do so, subject to the following conditions : - -# The above copyright notice and this permission notice shall be included in -# all copies or substantial portions of the Software. - -# 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. -#-------------------------------------------------------------------------- - -module Azure::Storage::Blob - module Container - include Azure::Storage::Common::Service - - class Container - def initialize - @properties = {} - @metadata = {} - yield self if block_given? - end - - attr_accessor :name - attr_accessor :properties - attr_accessor :metadata - attr_accessor :public_access_level - end - - # Public: Create a new container - # - # ==== Attributes - # - # * +name+ - String. The name of the container. - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:metadata+ - Hash. User defined metadata for the container (optional). - # * +:public_access_level+ - String. One of "container" or "blob" (optional). - # * +:timeout+ - Integer. A timeout in seconds. - # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded - # in the analytics logs when storage analytics logging is enabled. - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179468.aspx - # - # Returns a Container - def create_container(name, options = {}) - # Query - query = {} - query["timeout"] = options[:timeout].to_s if options[:timeout] - - # Scheme + path - uri = container_uri(name, query) - - # Headers - headers = {} - StorageService.add_metadata_to_headers(options[:metadata], headers) if options[:metadata] - headers["x-ms-blob-public-access"] = options[:public_access_level].to_s if options[:public_access_level] - - # Call - response = call(:put, uri, nil, headers, options) - - # result - container = Serialization.container_from_headers(response.headers) - container.name = name - container.metadata = options[:metadata] - container - end - - # Public: Returns all properties and metadata on the container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:timeout+ - Integer. A timeout in seconds. - # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded - # in the analytics logs when storage analytics logging is enabled. - # * +:location_mode+ - LocationMode. Specifies the location mode used to decide - # which location the request should be sent to. - # * +:lease_id+ - String. If specified, Get Container Properties only succeeds if the container’s lease is - # active and matches this ID. If there is no active lease or the ID does not match, 412 - # (Precondition Failed) is returned. - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179370.aspx - # - # Returns a Container - def get_container_properties(name, options = {}) - # Query - query = {} - query["timeout"] = options[:timeout].to_s if options[:timeout] - - headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} - - # Call - options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY - response = call(:get, container_uri(name, query, options), nil, headers, options) - - # result - container = Serialization.container_from_headers(response.headers) - container.name = name - container - end - - # Public: Returns only user-defined metadata for the specified container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:timeout+ - Integer. A timeout in seconds. - # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded - # in the analytics logs when storage analytics logging is enabled. - # * +:location_mode+ - LocationMode. Specifies the location mode used to decide - # which location the request should be sent to. - # * +:lease_id+ - String. If specified, Get Container Metadata only succeeds if the container’s lease is - # active and matches this ID. If there is no active lease or the ID does not match, 412 - # (Precondition Failed) is returned. - # - # See http://msdn.microsoft.com/en-us/library/azure/ee691976.aspx - # - # Returns a Container - def get_container_metadata(name, options = {}) - # Query - query = { "comp" => "metadata" } - query["timeout"] = options[:timeout].to_s if options[:timeout] - - headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} - - # Call - options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY - response = call(:get, container_uri(name, query, options), nil, headers, options) - - # result - container = Serialization.container_from_headers(response.headers) - container.name = name - container - end - - # Public: Sets custom metadata for the container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container - # * +metadata+ - Hash. A Hash of the metadata values - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:timeout+ - Integer. A timeout in seconds. - # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded - # in the analytics logs when storage analytics logging is enabled. - # * +:lease_id+ - String. If specified, Set Container Metadata only succeeds if the container’s lease is - # active and matches this ID. If there is no active lease or the ID does not match, 412 - # (Precondition Failed) is returned. - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179362.aspx - # - # Returns nil on success - def set_container_metadata(name, metadata, options = {}) - # Query - query = { "comp" => "metadata" } - query["timeout"] = options[:timeout].to_s if options[:timeout] - - # Headers - headers = {} - StorageService.add_metadata_to_headers(metadata, headers) if metadata - headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id] - - # Call - call(:put, container_uri(name, query), nil, headers, options) - - # Result - nil - end - - # Public: Gets the access control list (ACL) and any container-level access policies - # for the container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:timeout+ - Integer. A timeout in seconds. - # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded - # in the analytics logs when storage analytics logging is enabled. - # * +:location_mode+ - LocationMode. Specifies the location mode used to decide - # which location the request should be sent to. - # * +:lease_id+ - String. If specified, Get Container ACL only succeeds if the container’s lease is - # active and matches this ID. If there is no active lease or the ID does not match, 412 - # (Precondition Failed) is returned. - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179469.aspx - # - # Returns a tuple of (container, signed_identifiers) - # container - A Azure::Storage::Entity::Blob::Container instance - # signed_identifiers - A list of Azure::Storage::Entity::SignedIdentifier instances - # - def get_container_acl(name, options = {}) - # Query - query = { "comp" => "acl" } - query["timeout"] = options[:timeout].to_s if options[:timeout] - - headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} - - # Call - options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY - response = call(:get, container_uri(name, query, options), nil, headers, options) - - # Result - container = Serialization.container_from_headers(response.headers) - container.name = name - - signed_identifiers = nil - signed_identifiers = Serialization.signed_identifiers_from_xml(response.body) if response.body != nil && response.body.length > 0 - - return container, signed_identifiers - end - - # Public: Sets the ACL and any container-level access policies for the container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container - # * +public_access_level+ - String. The container public access level - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:signed_identifiers+ - Array. A list of Azure::Storage::Entity::SignedIdentifier instances (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. - # * +:lease_id+ - String. If specified, Set Container ACL only succeeds if the container’s lease is - # active and matches this ID. If there is no active lease or the ID does not match, 412 - # (Precondition Failed) is returned. - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179391.aspx - # - # Returns a tuple of (container, signed_identifiers) - # * +container+ - A Azure::Storage::Entity::Blob::Container instance - # * +signed_identifiers+ - A list of Azure::Storage::Entity::SignedIdentifier instances - # - def set_container_acl(name, public_access_level, options = {}) - # Query - query = { "comp" => "acl" } - query["timeout"] = options[:timeout].to_s if options[:timeout] - - # Scheme + path - uri = container_uri(name, query) - - # Headers + body - headers = {} - headers["x-ms-blob-public-access"] = public_access_level if public_access_level && public_access_level.to_s.length > 0 - headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id] - - signed_identifiers = nil - signed_identifiers = options[:signed_identifiers] if options[:signed_identifiers] - - body = nil - body = Serialization.signed_identifiers_to_xml(signed_identifiers) if signed_identifiers - - # Call - response = call(:put, uri, body, headers, options) - - # Result - container = Serialization.container_from_headers(response.headers) - container.name = name - container.public_access_level = public_access_level - - return container, signed_identifiers || [] - end - - # Public: Deletes a container. - # - # ==== Attributes - # - # * +name+ - String. The name of the container. - # * +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. - # * +:lease_id+ - String. Required for version 2012-02-12 and newer if the container has an active lease. To call - # Delete Container on a container that has an active lease, specify the lease ID in this header. - # If this header is not specified when there is an active lease, Delete Container will return 409 - # (Conflict). If you specify the wrong lease ID, or a lease ID on a container that does not have - # an active lease, Delete Container will return 412 (Precondition failed). - # - # See http://msdn.microsoft.com/en-us/library/azure/dd179408.aspx - # - # Returns nil on success - def delete_container(name, options = {}) - # Query - query = {} - query["timeout"] = options[:timeout].to_s if options[:timeout] - - headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} - - # Call - call(:delete, container_uri(name, query), nil, headers, options) - - # result - nil - end - - # Public: Establishes an exclusive write lock on a container. The lock duration can be 15 to 60 seconds, or can be infinite. - # To write to a locked container, a client must provide a lease ID. - # - # ==== Attributes - # - # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://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, or to renew, change, or release the lease. - # - def acquire_container_lease(container, options = {}) - acquire_lease container, nil, options - end - - # Public: Renews the lease. The lease can be renewed if the lease ID specified on the request matches that - # associated with the container. Note that the lease may be renewed even if it has expired as long as the container - # 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. - # * +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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx - # - # Returns the renewed lease id - def renew_container_lease(container, lease, options = {}) - renew_lease container, nil, lease, options - end - - # Public: Change the lease ID. - # - # ==== Attributes - # - # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx - # - # Returns the changed lease id - def change_container_lease(container, lease, proposed_lease, options = {}) - change_lease container, nil, lease, proposed_lease, options - end - - # Public: Releases the lease. The lease may be released if the lease ID specified on the request matches that - # associated with the container. Releasing the lease allows another client to immediately acquire the lease for - # the container as soon as the release is complete. - # - # ==== Attributes - # - # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx - # - # Returns nil on success - def release_container_lease(container, lease, options = {}) - release_lease container, nil, lease, options - end - - # Public: Breaks the lease, if the container 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 container. 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 container. - # - # ==== Attributes - # - # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://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. - def break_container_lease(container, options = {}) - break_lease container, nil, options - end - - # Public: Get a list of Blobs from the server - # - # ==== Attributes - # - # * +name+ - String. The name of the container to list blobs for. - # * +options+ - Hash. Optional parameters. - # - # ==== Options - # - # Accepted key/value pairs in options parameter are: - # * +:prefix+ - String. Filters the results to return only blobs - # whose name begins with the specified prefix. (optional) - # * +:delimiter+ - String. When the request includes this parameter, the operation - # returns a BlobPrefix element in the response body that acts as a - # placeholder for all blobs whose names begin with the same substring - # up to the appearance of the delimiter character. The delimiter may - # be a single character or a string. - # * +:marker+ - String. An identifier that specifies the portion of the - # list to be returned. This value comes from the property - # Azure::Storage::Common::EnumerationResults.continuation_token when - # there are more blobs available than were returned. The - # marker value may then be used here to request the next set - # of list items. (optional) - # * +:max_results+ - Integer. Specifies the maximum number of blobs to return. - # If max_results is not specified, or is a value greater than - # 5,000, the server will return up to 5,000 items. If it is set - # to a value less than or equal to zero, the server will return - # status code 400 (Bad Request). (optional) - # * +:metadata+ - Boolean. Specifies whether or not to return the blob metadata. - # (optional, Default=false) - # * +:snapshots+ - Boolean. Specifies that snapshots should be included in the - # enumeration. Snapshots are listed from oldest to newest in the - # response. (optional, Default=false) - # * +:uncomittedblobs+ - Boolean. Specifies that blobs for which blocks have been uploaded, - # but which have not been committed using put_block_list, be included - # in the response. (optional, Default=false) - # * +:copy+ - Boolean. Specifies that metadata related to any current or previous - # copy_blob operation should be included in the response. - # (optional, Default=false) - # * +: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. - # - # NOTE: Metadata requested with the :metadata parameter must have been stored in - # accordance with the naming restrictions imposed by the 2009-09-19 version of the Blob - # service. Beginning with that version, all metadata names must adhere to the naming - # conventions for C# identifiers. - # - # See: http://msdn.microsoft.com/en-us/library/azure/dd135734.aspx - # - # Any metadata with invalid names which were previously stored, will be returned with the - # key "x-ms-invalid-name" in the metadata hash. This may contain multiple values and be an - # Array (vs a String if it only contains a single value). - # - # Returns an Azure::Storage::Common::EnumerationResults - def list_blobs(name, options = {}) - # Query - query = { "comp" => "list" } - query["prefix"] = options[:prefix].gsub(/\\/, "/") if options[:prefix] - query["delimiter"] = options[:delimiter] if options[:delimiter] - query["marker"] = options[:marker] if options[:marker] - query["maxresults"] = options[:max_results].to_s if options[:max_results] - query["timeout"] = options[:timeout].to_s if options[:timeout] - - included_datasets = [] - included_datasets.push("metadata") if options[:metadata] == true - included_datasets.push("snapshots") if options[:snapshots] == true - included_datasets.push("uncommittedblobs") if options[:uncommittedblobs] == true - included_datasets.push("copy") if options[:copy] == true - - query["include"] = included_datasets.join "," if included_datasets.length > 0 - - # Scheme + path - options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY - uri = container_uri(name, query, options) - - # Call - response = call(:get, uri, nil, {}, options) - - # Result - if response.success? - Serialization.blob_enumeration_results_from_xml(response.body) - else - response.exception - end - end - end -end +# frozen_string_literal: true + +#------------------------------------------------------------------------- +# # Copyright (c) Microsoft and contributors. All rights reserved. +# +# The MIT License(MIT) + +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files(the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and / or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions : + +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. + +# 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. +#-------------------------------------------------------------------------- + +module Azure::Storage::Blob + module Container + include Azure::Storage::Common::Service + + class Container + def initialize + @properties = {} + @metadata = {} + yield self if block_given? + end + + attr_accessor :name + attr_accessor :properties + attr_accessor :metadata + attr_accessor :public_access_level + end + + # Public: Create a new container + # + # ==== Attributes + # + # * +name+ - String. The name of the container. + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:metadata+ - Hash. User defined metadata for the container (optional). + # * +:public_access_level+ - String. One of "container" or "blob" (optional). + # * +:timeout+ - Integer. A timeout in seconds. + # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded + # in the analytics logs when storage analytics logging is enabled. + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179468.aspx + # + # Returns a Container + def create_container(name, options = {}) + # Query + query = {} + query["timeout"] = options[:timeout].to_s if options[:timeout] + + # Scheme + path + uri = container_uri(name, query) + + # Headers + headers = {} + StorageService.add_metadata_to_headers(options[:metadata], headers) if options[:metadata] + headers["x-ms-blob-public-access"] = options[:public_access_level].to_s if options[:public_access_level] + + # Call + response = call(:put, uri, nil, headers, options) + + # result + container = Serialization.container_from_headers(response.headers) + container.name = name + container.metadata = options[:metadata] + container + end + + # Public: Returns all properties and metadata on the container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:timeout+ - Integer. A timeout in seconds. + # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded + # in the analytics logs when storage analytics logging is enabled. + # * +:location_mode+ - LocationMode. Specifies the location mode used to decide + # which location the request should be sent to. + # * +:lease_id+ - String. If specified, Get Container Properties only succeeds if the container’s lease is + # active and matches this ID. If there is no active lease or the ID does not match, 412 + # (Precondition Failed) is returned. + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179370.aspx + # + # Returns a Container + def get_container_properties(name, options = {}) + # Query + query = {} + query["timeout"] = options[:timeout].to_s if options[:timeout] + + headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} + + # Call + options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY + response = call(:get, container_uri(name, query, options), nil, headers, options) + + # result + container = Serialization.container_from_headers(response.headers) + container.name = name + container + end + + # Public: Returns only user-defined metadata for the specified container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:timeout+ - Integer. A timeout in seconds. + # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded + # in the analytics logs when storage analytics logging is enabled. + # * +:location_mode+ - LocationMode. Specifies the location mode used to decide + # which location the request should be sent to. + # * +:lease_id+ - String. If specified, Get Container Metadata only succeeds if the container’s lease is + # active and matches this ID. If there is no active lease or the ID does not match, 412 + # (Precondition Failed) is returned. + # + # See http://msdn.microsoft.com/en-us/library/azure/ee691976.aspx + # + # Returns a Container + def get_container_metadata(name, options = {}) + # Query + query = { "comp" => "metadata" } + query["timeout"] = options[:timeout].to_s if options[:timeout] + + headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} + + # Call + options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY + response = call(:get, container_uri(name, query, options), nil, headers, options) + + # result + container = Serialization.container_from_headers(response.headers) + container.name = name + container + end + + # Public: Sets custom metadata for the container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container + # * +metadata+ - Hash. A Hash of the metadata values + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:timeout+ - Integer. A timeout in seconds. + # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded + # in the analytics logs when storage analytics logging is enabled. + # * +:lease_id+ - String. If specified, Set Container Metadata only succeeds if the container’s lease is + # active and matches this ID. If there is no active lease or the ID does not match, 412 + # (Precondition Failed) is returned. + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179362.aspx + # + # Returns nil on success + def set_container_metadata(name, metadata, options = {}) + # Query + query = { "comp" => "metadata" } + query["timeout"] = options[:timeout].to_s if options[:timeout] + + # Headers + headers = {} + StorageService.add_metadata_to_headers(metadata, headers) if metadata + headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id] + + # Call + call(:put, container_uri(name, query), nil, headers, options) + + # Result + nil + end + + # Public: Gets the access control list (ACL) and any container-level access policies + # for the container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:timeout+ - Integer. A timeout in seconds. + # * +:request_id+ - String. Provides a client-generated, opaque value with a 1 KB character limit that is recorded + # in the analytics logs when storage analytics logging is enabled. + # * +:location_mode+ - LocationMode. Specifies the location mode used to decide + # which location the request should be sent to. + # * +:lease_id+ - String. If specified, Get Container ACL only succeeds if the container’s lease is + # active and matches this ID. If there is no active lease or the ID does not match, 412 + # (Precondition Failed) is returned. + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179469.aspx + # + # Returns a tuple of (container, signed_identifiers) + # container - A Azure::Storage::Entity::Blob::Container instance + # signed_identifiers - A list of Azure::Storage::Entity::SignedIdentifier instances + # + def get_container_acl(name, options = {}) + # Query + query = { "comp" => "acl" } + query["timeout"] = options[:timeout].to_s if options[:timeout] + + headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} + + # Call + options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY + response = call(:get, container_uri(name, query, options), nil, headers, options) + + # Result + container = Serialization.container_from_headers(response.headers) + container.name = name + + signed_identifiers = nil + signed_identifiers = Serialization.signed_identifiers_from_xml(response.body) if response.body != nil && response.body.length > 0 + + return container, signed_identifiers + end + + # Public: Sets the ACL and any container-level access policies for the container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container + # * +public_access_level+ - String. The container public access level + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:signed_identifiers+ - Array. A list of Azure::Storage::Entity::SignedIdentifier instances (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. + # * +:lease_id+ - String. If specified, Set Container ACL only succeeds if the container’s lease is + # active and matches this ID. If there is no active lease or the ID does not match, 412 + # (Precondition Failed) is returned. + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179391.aspx + # + # Returns a tuple of (container, signed_identifiers) + # * +container+ - A Azure::Storage::Entity::Blob::Container instance + # * +signed_identifiers+ - A list of Azure::Storage::Entity::SignedIdentifier instances + # + def set_container_acl(name, public_access_level, options = {}) + # Query + query = { "comp" => "acl" } + query["timeout"] = options[:timeout].to_s if options[:timeout] + + # Scheme + path + uri = container_uri(name, query) + + # Headers + body + headers = {} + headers["x-ms-blob-public-access"] = public_access_level if public_access_level && public_access_level.to_s.length > 0 + headers["x-ms-lease-id"] = options[:lease_id] if options[:lease_id] + + signed_identifiers = nil + signed_identifiers = options[:signed_identifiers] if options[:signed_identifiers] + + body = nil + body = Serialization.signed_identifiers_to_xml(signed_identifiers) if signed_identifiers + + # Call + response = call(:put, uri, body, headers, options) + + # Result + container = Serialization.container_from_headers(response.headers) + container.name = name + container.public_access_level = public_access_level + + return container, signed_identifiers || [] + end + + # Public: Deletes a container. + # + # ==== Attributes + # + # * +name+ - String. The name of the container. + # * +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. + # * +:lease_id+ - String. Required for version 2012-02-12 and newer if the container has an active lease. To call + # Delete Container on a container that has an active lease, specify the lease ID in this header. + # If this header is not specified when there is an active lease, Delete Container will return 409 + # (Conflict). If you specify the wrong lease ID, or a lease ID on a container that does not have + # an active lease, Delete Container will return 412 (Precondition failed). + # + # See http://msdn.microsoft.com/en-us/library/azure/dd179408.aspx + # + # Returns nil on success + def delete_container(name, options = {}) + # Query + query = {} + query["timeout"] = options[:timeout].to_s if options[:timeout] + + headers = options[:lease_id] ? { "x-ms-lease-id" => options[:lease_id] } : {} + + # Call + call(:delete, container_uri(name, query), nil, headers, options) + + # result + nil + end + + # Public: Establishes an exclusive write lock on a container. The lock duration can be 15 to 60 seconds, or can be infinite. + # To write to a locked container, a client must provide a lease ID. + # + # ==== Attributes + # + # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://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, or to renew, change, or release the lease. + # + def acquire_container_lease(container, options = {}) + acquire_lease container, nil, options + end + + # Public: Renews the lease. The lease can be renewed if the lease ID specified on the request matches that + # associated with the container. Note that the lease may be renewed even if it has expired as long as the container + # 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. + # * +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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx + # + # Returns the renewed lease id + def renew_container_lease(container, lease, options = {}) + renew_lease container, nil, lease, options + end + + # Public: Change the lease ID. + # + # ==== Attributes + # + # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx + # + # Returns the changed lease id + def change_container_lease(container, lease, proposed_lease, options = {}) + change_lease container, nil, lease, proposed_lease, options + end + + # Public: Releases the lease. The lease may be released if the lease ID specified on the request matches that + # associated with the container. Releasing the lease allows another client to immediately acquire the lease for + # the container as soon as the release is complete. + # + # ==== Attributes + # + # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://msdn.microsoft.com/en-us/library/azure/ee691972.aspx + # + # Returns nil on success + def release_container_lease(container, lease, options = {}) + release_lease container, nil, lease, options + end + + # Public: Breaks the lease, if the container 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 container. 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 container. + # + # ==== Attributes + # + # * +container+ - String. The container 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 container has been modified since the specified date/time. If the container 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 container has not been modified since the specified date/time. If the container 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 container'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 container'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 http://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. + def break_container_lease(container, options = {}) + break_lease container, nil, options + end + + # Public: Get a list of Blobs from the server + # + # ==== Attributes + # + # * +name+ - String. The name of the container to list blobs for. + # * +options+ - Hash. Optional parameters. + # + # ==== Options + # + # Accepted key/value pairs in options parameter are: + # * +:prefix+ - String. Filters the results to return only blobs + # whose name begins with the specified prefix. (optional) + # * +:delimiter+ - String. When the request includes this parameter, the operation + # returns a BlobPrefix element in the response body that acts as a + # placeholder for all blobs whose names begin with the same substring + # up to the appearance of the delimiter character. The delimiter may + # be a single character or a string. + # * +:marker+ - String. An identifier that specifies the portion of the + # list to be returned. This value comes from the property + # Azure::Storage::Common::EnumerationResults.continuation_token when + # there are more blobs available than were returned. The + # marker value may then be used here to request the next set + # of list items. (optional) + # * +:max_results+ - Integer. Specifies the maximum number of blobs to return. + # If max_results is not specified, or is a value greater than + # 5,000, the server will return up to 5,000 items. If it is set + # to a value less than or equal to zero, the server will return + # status code 400 (Bad Request). (optional) + # * +:metadata+ - Boolean. Specifies whether or not to return the blob metadata. + # (optional, Default=false) + # * +:snapshots+ - Boolean. Specifies that snapshots should be included in the + # enumeration. Snapshots are listed from oldest to newest in the + # response. (optional, Default=false) + # * +:uncomittedblobs+ - Boolean. Specifies that blobs for which blocks have been uploaded, + # but which have not been committed using put_block_list, be included + # in the response. (optional, Default=false) + # * +:copy+ - Boolean. Specifies that metadata related to any current or previous + # copy_blob operation should be included in the response. + # (optional, Default=false) + # * +: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. + # + # NOTE: Metadata requested with the :metadata parameter must have been stored in + # accordance with the naming restrictions imposed by the 2009-09-19 version of the Blob + # service. Beginning with that version, all metadata names must adhere to the naming + # conventions for C# identifiers. + # + # See: http://msdn.microsoft.com/en-us/library/azure/dd135734.aspx + # + # Any metadata with invalid names which were previously stored, will be returned with the + # key "x-ms-invalid-name" in the metadata hash. This may contain multiple values and be an + # Array (vs a String if it only contains a single value). + # + # Returns an Azure::Storage::Common::EnumerationResults + def list_blobs(name, options = {}) + # Query + query = { "comp" => "list" } + query["prefix"] = options[:prefix].gsub(/\\/, "/") if options[:prefix] + query["delimiter"] = options[:delimiter] if options[:delimiter] + query["marker"] = options[:marker] if options[:marker] + query["maxresults"] = options[:max_results].to_s if options[:max_results] + query["timeout"] = options[:timeout].to_s if options[:timeout] + + included_datasets = [] + included_datasets.push("metadata") if options[:metadata] == true + included_datasets.push("snapshots") if options[:snapshots] == true + included_datasets.push("uncommittedblobs") if options[:uncommittedblobs] == true + included_datasets.push("copy") if options[:copy] == true + + query["include"] = included_datasets.join "," if included_datasets.length > 0 + + # Scheme + path + options[:request_location_mode] = Azure::Storage::Common::RequestLocationMode::PRIMARY_OR_SECONDARY + uri = container_uri(name, query, options) + + # Call + response = call(:get, uri, nil, {}, options) + + # Result + if response.success? + Serialization.blob_enumeration_results_from_xml(response.body) + else + response.exception + end + end + end +end