Class: Azure::Storage::File::FileService

Inherits:
StorageService
  • Object
show all
Includes:
Common::Core::Utility, Azure::Storage::File, Directory, Share
Defined in:
lib/azure/storage/file/file_service.rb

Constant Summary

Constants included from Azure::Storage::File

StorageService

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Azure::Storage::File

#abort_copy_file, #clear_file_range, #copy_file, #copy_file_from_uri, #create_directory, #create_file, #create_file_from_content, #delete_directory, #delete_file, #get_directory_metadata, #get_directory_properties, #get_file, #get_file_metadata, #get_file_properties, #list_directories_and_files, #list_file_ranges, #put_file_range, #resize_file, #set_directory_metadata, #set_file_metadata, #set_file_properties

Methods included from Share

#create_share, #delete_share, #get_share_acl, #get_share_metadata, #get_share_properties, #get_share_stats, #set_share_acl, #set_share_metadata, #set_share_properties

Constructor Details

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

Public: Initializes an instance of [Azure::Storage::File::FileService]

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_file_host - String. Specified File serivce endpoint or hostname

  • :storage_table_host - String. Specified Table serivce endpoint or hostname

  • :storage_queue_host - String. Specified Queue 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

  • :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 File: only :storage_file_host, if it is to only access files 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 'lib/azure/storage/file/file_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::File::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_file_host
  @storage_service_host[:secondary] = client.storage_file_host true
end

Class Method Details

.create(options = {}, &block) ⇒ Azure::Storage::File::FileService

Public: Creates an instance of [Azure::Storage::File::FileService]

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_file_host - String. Specified File 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

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

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 File: only :storage_file_host, if it is to only access files 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:



81
82
83
84
85
 
# File 'lib/azure/storage/file/file_service.rb', line 81

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

.create_development(proxy_uri = nil, &block) ⇒ Azure::Storage::File::FileService

Public: Creates an instance of [Azure::Storage::File::FileService] with Storage Emulator

Attributes

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

Returns:



94
95
96
97
 
# File 'lib/azure/storage/file/file_service.rb', line 94

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

.create_from_connection_string(connection_string, &block) ⇒ Azure::Storage::File::FileService

Public: Creates an instance of [Azure::Storage::File::FileService] from Environment Variables

Attributes

Returns:



114
115
116
117
 
# File 'lib/azure/storage/file/file_service.rb', line 114

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::File::Default::STG_VERSION }
  Azure::Storage::File::FileService.new(service_options, &block)
end

.create_from_env(&block) ⇒ Azure::Storage::File::FileService

Public: Creates an instance of [Azure::Storage::File::FileService] from Environment Variables

Returns:



102
103
104
105
 
# File 'lib/azure/storage/file/file_service.rb', line 102

def create_from_env(&block)
  service_options = { client: Azure::Storage::Common::Client::create_from_env(&block), api_version: Azure::Storage::File::Default::STG_VERSION }
  Azure::Storage::File::FileService.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 'lib/azure/storage/file/file_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::FILE_CONTENT_TYPE])
  headers[Azure::Storage::Common::HeaderConstants::FILE_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 file 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

#list_shares(options = {}) ⇒ Object

Public: Get a list of Shares 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 shares

    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 shares 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 shares 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 share 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: docs.microsoft.com/en-us/rest/api/storageservices/fileservices/list-shares

Returns an Azure::Storage::Common::EnumerationResults



231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/azure/storage/file/file_service.rb', line 231

def list_shares(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 = shares_uri(query, options)
  response = call(:get, uri, nil, {}, options)

  Serialization.share_enumeration_results_from_xml(response.body)
end