Class: Azure::Storage::Blob::BlobService

Inherits:
StorageService
  • Object
show all
Includes:
Azure::Storage::Blob, Container, Common::Core::Utility
Defined in:
blob/lib/azure/storage/blob/blob_service.rb

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Container

#acquire_container_lease, #break_container_lease, #change_container_lease, #create_container, #delete_container, #get_container_acl, #get_container_metadata, #get_container_properties, #list_blobs, #release_container_lease, #renew_container_lease, #set_container_acl, #set_container_metadata

Methods included from Azure::Storage::Blob

#abort_copy_blob, #acquire_blob_lease, #append_blob_block, #break_blob_lease, #change_blob_lease, #clear_blob_pages, #commit_blob_blocks, #copy_blob, #copy_blob_from_uri, #create_append_blob, #create_append_blob_from_content, #create_blob_snapshot, #create_block_blob, #create_page_blob, #create_page_blob_from_content, #delete_blob, #get_blob, #get_blob_metadata, #get_blob_properties, #incremental_copy_blob, #list_blob_blocks, #list_page_blob_ranges, #put_blob_block, #put_blob_pages, #release_blob_lease, #renew_blob_lease, #resize_page_blob, #set_blob_metadata, #set_blob_properties, #set_sequence_number

Constructor Details

#initialize(options = {}, &block) ⇒ BlobService

Public: Initializes an instance of [Azure::Storage::Blob::BlobService]

Attributes

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :use_development_storage - TrueClass|FalseClass. Whether to use storage emulator.

  • :development_storage_proxy_uri - String. Used with :use_development_storage if emulator is hosted other than localhost.

  • :storage_connection_string - String. The storage connection string.

  • :storage_account_name - String. The name of the storage account.

  • :storage_access_key - Base64 String. The access key of the storage account.

  • :storage_sas_token - String. The signed access signature for the storage account or one of its service.

  • :storage_blob_host - String. Specified Blob serivce endpoint or hostname

  • :storage_dns_suffix - String. The suffix of a regional Storage Serivce, to

  • :default_endpoints_protocol - String. http or https

  • :use_path_style_uri - String. Whether use path style URI for specified endpoints

  • :ca_file - String. File path of the CA file if having issue with SSL

  • :ssl_version - Symbol. The ssl version to be used, sample: :TLSv1_1, :TLSv1_2, for the details, see github.com/ruby/openssl/blob/master/lib/openssl/ssl.rb

  • :ssl_min_version - Symbol. The min ssl version supported, only supported in Ruby 2.5+

  • :ssl_max_version - Symbol. The max ssl version supported, only supported in Ruby 2.5+

  • :user_agent_prefix - String. The user agent prefix that can identify the application calls the library

  • :client - Azure::Storage::Common::Client. The common client used to initalize the service.

The valid set of options include:

  • Storage Emulator: :use_development_storage required, :development_storage_proxy_uri optionally

  • Storage account name and key: :storage_account_name and :storage_access_key required, set :storage_dns_suffix necessarily

  • Storage account name and SAS token: :storage_account_name and :storage_sas_token required, set :storage_dns_suffix necessarily

  • Specified hosts and SAS token: At least one of the service host and SAS token. It's up to user to ensure the SAS token is suitable for the serivce

  • Azure::Storage::Common::Client: The common client used to initalize the service. This client can be initalized and used repeatedly.

  • Anonymous Blob: only :storage_blob_host, if it is to only access blobs within a container

Additional notes:

  • Specified hosts can be set when use account name with access key or sas token

  • :default_endpoints_protocol can be set if the scheme is not specified in hosts

  • Storage emulator always use path style URI

  • :ca_file is independent.

When empty options are given, it will try to read settings from Environment Variables. Refer to [Azure::Storage::Common::ClientOptions.env_vars_mapping] for the mapping relationship



161
162
163
164
165
166
167
168
169
170
171
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 161

def initialize(options = {}, &block)
  service_options = options.clone
  client_config = service_options[:client] ||= Azure::Storage::Common::Client::create(service_options, &block)
  @user_agent_prefix = service_options[:user_agent_prefix] if service_options[:user_agent_prefix]
  @api_version = service_options[:api_version] || Azure::Storage::Blob::Default::STG_VERSION
  signer = service_options[:signer] || client_config.signer || Azure::Storage::Common::Core::Auth::SharedKey.new(client_config., client_config.storage_access_key)
  signer.api_ver = @api_version if signer.is_a? Azure::Storage::Common::Core::Auth::SharedAccessSignatureSigner
  super(signer, client_config., service_options, &block)
  @storage_service_host[:primary] = client.storage_blob_host
  @storage_service_host[:secondary] = client.storage_blob_host true
end

Class Method Details

.create(options = {}, &block) ⇒ Azure::Storage::Blob::BlobService

Public: Creates an instance of [Azure::Storage::Blob::BlobService]

Attributes

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :use_development_storage - TrueClass|FalseClass. Whether to use storage emulator.

  • :development_storage_proxy_uri - String. Used with :use_development_storage if emulator is hosted other than localhost.

  • :storage_account_name - String. The name of the storage account.

  • :storage_access_key - Base64 String. The access key of the storage account.

  • :storage_sas_token - String. The signed access signature for the storage account or one of its service.

  • :storage_blob_host - String. Specified Blob service endpoint or hostname

  • :storage_dns_suffix - String. The suffix of a regional Storage Service, to

  • :default_endpoints_protocol - String. http or https

  • :use_path_style_uri - String. Whether use path style URI for specified endpoints

  • :ca_file - String. File path of the CA file if having issue with SSL

  • :user_agent_prefix - String. The user agent prefix that can identify the application calls the library

The valid set of options include:

  • Storage Emulator: :use_development_storage required, :development_storage_proxy_uri optionally

  • Storage account name and key: :storage_account_name and :storage_access_key required, set :storage_dns_suffix necessarily

  • Storage account name and SAS token: :storage_account_name and :storage_sas_token required, set :storage_dns_suffix necessarily

  • Specified hosts and SAS token: At least one of the service host and SAS token. It's up to user to ensure the SAS token is suitable for the serivce

  • Anonymous Blob: only :storage_blob_host, if it is to only access blobs within a container

Additional notes:

  • Specified hosts can be set when use account name with access key or sas token

  • :default_endpoints_protocol can be set if the scheme is not specified in hosts

  • Storage emulator always use path style URI

  • :ca_file is independent.

When empty options are given, it will try to read settings from Environment Variables. Refer to [Azure::Storage::Common::ClientOptions.env_vars_mapping] for the mapping relationship

Returns:



80
81
82
83
84
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 80

def create(options = {}, &block)
  service_options = { client: Azure::Storage::Common::Client::create(options, &block), api_version: Azure::Storage::Blob::Default::STG_VERSION }
  service_options[:user_agent_prefix] = options[:user_agent_prefix] if options[:user_agent_prefix]
  Azure::Storage::Blob::BlobService.new(service_options, &block)
end

.create_development(proxy_uri = nil, &block) ⇒ Azure::Storage::Blob::BlobService

Public: Creates an instance of [Azure::Storage::Blob::BlobService] with Storage Emulator

Attributes

  • proxy_uri - String. Used with :use_development_storage if emulator is hosted other than localhost.

Returns:



93
94
95
96
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 93

def create_development(proxy_uri = nil, &block)
  service_options = { client: Azure::Storage::Common::Client::create_development(proxy_uri, &block), api_version: Azure::Storage::Blob::Default::STG_VERSION }
  Azure::Storage::Blob::BlobService.new(service_options, &block)
end

.create_from_connection_string(connection_string, &block) ⇒ Azure::Storage::Blob::BlobService

Public: Creates an instance of [Azure::Storage::Blob::BlobService] from Environment Variables

Attributes

Returns:



113
114
115
116
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 113

def create_from_connection_string(connection_string, &block)
  service_options = { client: Azure::Storage::Common::Client::create_from_connection_string(connection_string, &block), api_version: Azure::Storage::Blob::Default::STG_VERSION }
  Azure::Storage::Blob::BlobService.new(service_options, &block)
end

.create_from_env(&block) ⇒ Azure::Storage::Blob::BlobService

Public: Creates an instance of [Azure::Storage::Blob::BlobService] from Environment Variables

Returns:



101
102
103
104
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 101

def create_from_env(&block)
  service_options = { client: Azure::Storage::Common::Client::create_from_env(&block), api_version: Azure::Storage::Blob::Default::STG_VERSION }
  Azure::Storage::Blob::BlobService.new(service_options, &block)
end

Instance Method Details

#call(method, uri, body = nil, headers = {}, options = {}) ⇒ Object 



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 173

def call(method, uri, body = nil, headers = {}, options = {})
  content_type = get_or_apply_content_type(body, headers[Azure::Storage::Common::HeaderConstants::BLOB_CONTENT_TYPE])
  headers[Azure::Storage::Common::HeaderConstants::BLOB_CONTENT_TYPE] = content_type if content_type

  headers["x-ms-version"] = @api_version ? @api_version : Default::STG_VERSION
  headers["User-Agent"] = @user_agent_prefix ? "#{@user_agent_prefix}; #{Default::USER_AGENT}" : Default::USER_AGENT
  response = super

  # Force the response.body to the content charset of specified in the header.
  # Content-Type is echo'd back for the blob and is used to store the encoding of the octet stream
  if !response.nil? && !response.body.nil? && response.headers["Content-Type"]
    charset = parse_charset_from_content_type(response.headers["Content-Type"])
    response.body.force_encoding(charset) if charset && charset.length > 0
  end

  response
end

#get_user_delegation_key(start, expiry) ⇒ Object

Public: Obtain a user delegation key for the purpose of signing SAS tokens.

Attributes

  • start - Time. The start time for the user delegation SAS.

  • expiry - Time. The expiry time of user delegation SAS.

See: docs.microsoft.com/en-us/rest/api/storageservices/get-user-delegation-key

NOTE: A token credential must be present on the service object for this request to succeed. The start and expiry times must be within 7 days of the current time.

Returns an Azure::Storage::Common::UserDelegationKey

Raises:

  • (ArgumentError) 


271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 271

def get_user_delegation_key(start, expiry)
  max_delegation_time = Time.now + BlobConstants::MAX_USER_DELEGATION_KEY_SECONDS
  raise ArgumentError, "Start time must be before #{max_delegation_time}" if start > max_delegation_time
  raise ArgumentError, "Expiry time must be before #{max_delegation_time}" if expiry > max_delegation_time
  raise ArgumentError, "Start time must be before expiry time" if start >= expiry

  body = Serialization.key_info_to_xml(start, expiry)

  response = call(:post, user_delegation_key_uri, body)

  Serialization.user_delegation_key_from_xml(response.body)
end

#list_containers(options = {}) ⇒ Object

Public: Get a list of Containers from the server.

Attributes

  • options - Hash. Optional parameters.

Options

Accepted key/value pairs in options parameter are:

  • :prefix - String. Filters the results to return only containers

    whose name begins with the specified prefix. (optional)

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

    list to be returned. This value comes from the property
Azure::Storage::Common::EnumerationResults.continuation_token when there
are more containers 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 containers 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 container metadata.

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

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

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: msdn.microsoft.com/en-us/library/aa664670(VS.71).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



240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'blob/lib/azure/storage/blob/blob_service.rb', line 240

def list_containers(options = {})
  query = {}
  if options
    StorageService.with_query query, "prefix", options[:prefix]
    StorageService.with_query query, "marker", options[:marker]
    StorageService.with_query query, "maxresults", options[:max_results].to_s if options[:max_results]
    StorageService.with_query query, "include", "metadata" if options[:metadata] == true
    StorageService.with_query query, "timeout", options[:timeout].to_s if options[:timeout]
  end

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

  Serialization.container_enumeration_results_from_xml(response.body)
end