Module: Google::Cloud::Storage

Defined in:
lib/google/cloud/storage.rb,
lib/google/cloud/storage/file.rb,
lib/google/cloud/storage/bucket.rb,
lib/google/cloud/storage/errors.rb,
lib/google/cloud/storage/policy.rb,
lib/google/cloud/storage/convert.rb,
lib/google/cloud/storage/project.rb,
lib/google/cloud/storage/service.rb,
lib/google/cloud/storage/version.rb,
lib/google/cloud/storage/file/acl.rb,
lib/google/cloud/storage/hmac_key.rb,
lib/google/cloud/storage/file/list.rb,
lib/google/cloud/storage/bucket/acl.rb,
lib/google/cloud/storage/bucket/cors.rb,
lib/google/cloud/storage/bucket/list.rb,
lib/google/cloud/storage/credentials.rb,
lib/google/cloud/storage/post_object.rb,
lib/google/cloud/storage/notification.rb,
lib/google/cloud/storage/file/verifier.rb,
lib/google/cloud/storage/hmac_key/list.rb,
lib/google/cloud/storage/file/signer_v2.rb,
lib/google/cloud/storage/file/signer_v4.rb,
lib/google/cloud/storage/policy/binding.rb,
lib/google/cloud/storage/policy/bindings.rb,
lib/google/cloud/storage/bucket/lifecycle.rb,
lib/google/cloud/storage/policy/condition.rb

Overview

Google Cloud Storage

Google Cloud Storage is an Internet service to store data in Google's cloud. It allows world-wide storage and retrieval of any amount of data and at any time, taking advantage of Google's own reliable and fast networking infrastructure to perform data operations in a cost effective manner.

See Storage Overview.

Defined Under Namespace

Classes: Bucket, Credentials, File, FileVerificationError, HmacKey, Notification, Policy, PolicyV1, PolicyV3, PostObject, Project, SignedUrlUnavailable

Constant Summary collapse

GOOGLEAPIS_URL = 
"https://storage.googleapis.com".freeze
VERSION = 
"1.52.0".freeze

Class Method Summary collapse

Class Method Details

.anonymous(retries: nil, timeout: nil, open_timeout: nil, read_timeout: nil, send_timeout: nil, endpoint: nil, max_elapsed_time: nil, base_interval: nil, max_interval: nil, multiplier: nil, upload_chunk_size: nil, universe_domain: nil) ⇒ Google::Cloud::Storage::Project

Creates an unauthenticated, anonymous client for retrieving public data from the Storage service. Each call creates a new connection.

Examples:

Use skip_lookup to avoid retrieving non-public metadata:

require "google/cloud/storage"

storage = Google::Cloud::Storage.anonymous

bucket = storage.bucket "public-bucket", skip_lookup: true
file = bucket.file "path/to/public-file.ext", skip_lookup: true

downloaded = file.download
downloaded.rewind
downloaded.read #=> "Hello world!"

Parameters:

  • retries (Integer) (defaults to: nil) —

    Number of times to retry requests on server error. The default value is 3. Optional.

  • max_elapsed_time (Integer) (defaults to: nil) —

    Total time in seconds that requests are allowed to keep being retried.

  • base_interval (Float) (defaults to: nil) —

    The initial interval in seconds between tries.

  • max_interval (Integer) (defaults to: nil) —

    The maximum interval in seconds that any individual retry can reach.

  • multiplier (Integer) (defaults to: nil) —

    Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.

  • timeout (Integer) (defaults to: nil) —

    (default timeout) The max duration, in seconds, to wait before timing out. Optional. If left blank, the wait will be at most the time permitted by the underlying HTTP/RPC protocol.

  • open_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before failed connections time out. Optional.

  • read_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before requests time out. Optional.

  • send_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before receiving response from server times out. Optional.

  • endpoint (String) (defaults to: nil) —

    Override of the endpoint host name. Optional. If the param is nil, uses the default endpoint.

  • universe_domain (String) (defaults to: nil) —

    Override of the universe domain. Optional. If unset or nil, uses the default unvierse domain

  • upload_chunk_size (Integer) (defaults to: nil) —

    The chunk size of storage upload, in bytes. The default value is 100 MB, i.e. 104_857_600 bytes. To disable chunking and upload the complete file regardless of size, pass 0 as the chunk size.

Returns:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
 
# File 'lib/google/cloud/storage.rb', line 172

def self.anonymous retries: nil, timeout: nil, open_timeout: nil,
                   read_timeout: nil, send_timeout: nil, endpoint: nil,
                   max_elapsed_time: nil, base_interval: nil, max_interval: nil,
                   multiplier: nil, upload_chunk_size: nil, universe_domain: nil
  open_timeout ||= timeout
  read_timeout ||= timeout
  send_timeout ||= timeout
  Storage::Project.new(
    Storage::Service.new(
      nil, nil, retries: retries, timeout: timeout, open_timeout: open_timeout,
      read_timeout: read_timeout, send_timeout: send_timeout, host: endpoint,
      max_elapsed_time: max_elapsed_time, base_interval: base_interval,
      max_interval: max_interval, multiplier: multiplier, upload_chunk_size: upload_chunk_size,
      universe_domain: universe_domain
    )
  )
end

.configure {|Google::Cloud.configure.storage| ... } ⇒ Google::Cloud::Config

Configure the Google Cloud Storage library.

The following Storage configuration parameters are supported:

  • project_id - (String) Identifier for a Storage project. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • endpoint - (String) Override of the endpoint host name, or nil to use the default endpoint.
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • retries - (Integer) Number of times to retry requests on server error.
  • max_elapsed_time - (Integer) Total time in seconds that requests are allowed to keep being retried.
  • base_interval - (Float) The initial interval in seconds between tries.
  • max_interval - (Integer) The maximum interval in seconds that any individual retry can reach.
  • multiplier - (Integer) Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.
  • timeout - (Integer) (default timeout) The max duration, in seconds, to wait before timing out. If left blank, the wait will be at most the time permitted by the underlying HTTP/RPC protocol.
  • open_timeout - (Integer) How long, in seconds, before failed connections time out.
  • read_timeout - (Integer) How long, in seconds, before requests time out.
  • send_timeout - (Integer) How long, in seconds, before receiving response from server times out.
  • upload_chunk_size - (Integer) The chunk size of storage upload, in bytes.

Yields:

Returns:

  • (Google::Cloud::Config) —

    The configuration object the Google::Cloud::Storage library uses.



224
225
226
227
228
 
# File 'lib/google/cloud/storage.rb', line 224

def self.configure
  yield Google::Cloud.configure.storage if block_given?

  Google::Cloud.configure.storage
end

.new(project_id: nil, credentials: nil, scope: nil, retries: nil, timeout: nil, open_timeout: nil, read_timeout: nil, send_timeout: nil, endpoint: nil, project: nil, keyfile: nil, max_elapsed_time: nil, base_interval: nil, max_interval: nil, multiplier: nil, upload_chunk_size: nil, universe_domain: nil) ⇒ Google::Cloud::Storage::Project

Creates a new object for connecting to the Storage service. Each call creates a new connection.

For more information on connecting to Google Cloud see the Authentication Guide.

rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

bucket = storage.bucket "my-bucket"
file = bucket.file "path/to/my-file.ext"

Parameters:

  • project_id (String) (defaults to: nil) —

    Project identifier for the Storage service you are connecting to. If not present, the default project for the credentials is used.

  • credentials (String, Hash, Google::Auth::Credentials) (defaults to: nil) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • scope (String, Array<String>) (defaults to: nil) —

    The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access. See Using OAuth 2.0 to Access Google APIs.

    The default scope is:

    • https://www.googleapis.com/auth/devstorage.full_control
  • retries (Integer) (defaults to: nil) —

    Number of times to retry requests on server error. The default value is 3. Optional.

  • max_elapsed_time (Integer) (defaults to: nil) —

    Total time in seconds that requests are allowed to keep being retried.

  • base_interval (Float) (defaults to: nil) —

    The initial interval in seconds between tries.

  • max_interval (Integer) (defaults to: nil) —

    The maximum interval in seconds that any individual retry can reach.

  • multiplier (Integer) (defaults to: nil) —

    Each successive interval grows by this factor. A multipler of 1.5 means the next interval will be 1.5x the current interval.

  • timeout (Integer) (defaults to: nil) —

    (default timeout) The max duration, in seconds, to wait before timing out. Optional. If left blank, the wait will be at most the time permitted by the underlying HTTP/RPC protocol.

  • open_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before failed connections time out. Optional.

  • read_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before requests time out. Optional.

  • send_timeout (Integer) (defaults to: nil) —

    How long, in seconds, before receiving response from server times out. Optional.

  • endpoint (String) (defaults to: nil) —

    Override of the endpoint host name. Optional. If the param is nil, uses the default endpoint.

  • universe_domain (String) (defaults to: nil) —

    Override of the universe domain. Optional. If unset or nil, uses the default unvierse domain

  • upload_chunk_size (Integer) (defaults to: nil) —

    The chunk size of storage upload, in bytes. The default value is 100 MB, i.e. 104_857_600 bytes. To disable chunking and upload the complete file regardless of size, pass 0 as the chunk size.

  • project (String) (defaults to: nil) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) (defaults to: nil) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/google/cloud/storage.rb', line 93

def self.new project_id: nil, credentials: nil, scope: nil, retries: nil,
             timeout: nil, open_timeout: nil, read_timeout: nil,
             send_timeout: nil, endpoint: nil, project: nil, keyfile: nil,
             max_elapsed_time: nil, base_interval: nil, max_interval: nil,
             multiplier: nil, upload_chunk_size: nil, universe_domain: nil
  scope             ||= configure.scope
  retries           ||= configure.retries
  timeout           ||= configure.timeout
  open_timeout      ||= (configure.open_timeout || timeout)
  read_timeout      ||= (configure.read_timeout || timeout)
  send_timeout      ||= (configure.send_timeout || timeout)
  endpoint          ||= configure.endpoint
  credentials       ||= (keyfile || default_credentials(scope: scope))
  max_elapsed_time  ||= configure.max_elapsed_time
  base_interval     ||= configure.base_interval
  max_interval      ||= configure.max_interval
  multiplier        ||= configure.multiplier
  upload_chunk_size ||= configure.upload_chunk_size
  universe_domain   ||= configure.universe_domain

  unless credentials.is_a? Google::Auth::Credentials
    credentials = Storage::Credentials.new credentials, scope: scope
  end

  project_id = resolve_project_id(project_id || project, credentials)
  raise ArgumentError, "project_id is missing" if project_id.empty?

  Storage::Project.new(
    Storage::Service.new(
      project_id, credentials,
      retries: retries, timeout: timeout, open_timeout: open_timeout,
      read_timeout: read_timeout, send_timeout: send_timeout,
      host: endpoint, quota_project: configure.quota_project,
      max_elapsed_time: max_elapsed_time, base_interval: base_interval,
      max_interval: max_interval, multiplier: multiplier, upload_chunk_size: upload_chunk_size,
      universe_domain: universe_domain
    )
  )
end