Class: Google::Cloud::Storage::Bucket

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/storage/bucket.rb,
lib/google/cloud/storage/bucket/acl.rb,
lib/google/cloud/storage/bucket/cors.rb,
lib/google/cloud/storage/bucket/list.rb

Overview

Bucket

Represents a Storage bucket. Belongs to a Project and has many Files.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

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

Direct Known Subclasses

Updater

Defined Under Namespace

Classes: Acl, Cors, DefaultAcl, List, Updater

Instance Method Summary collapse

Instance Method Details

#acl ⇒ Object

The Bucket::Acl instance used to control access to the bucket.

A bucket has owners, writers, and readers. Permissions can be granted to an individual user's email address, a group's email address, as well as many predefined lists.

Examples:

Grant access to a user by prepending "user-" to an email:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

email = "heidi@example.net"
bucket.acl.add_reader "user-#{email}"

Grant access to a group by prepending "group-" to an email:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

email = "authors@example.net"
bucket.acl.add_reader "group-#{email}"

Or, grant access via a predefined permissions list:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.acl.public!

See Also:



717
718
719
 
# File 'lib/google/cloud/storage/bucket.rb', line 717

def acl
  @acl ||= Bucket::Acl.new self
end

#api_url ⇒ Object

A URL that can be used to access the bucket using the REST API.



75
76
77
 
# File 'lib/google/cloud/storage/bucket.rb', line 75

def api_url
  @gapi.self_link
end

#cors {|cors| ... } ⇒ Object

Returns the current CORS configuration for a static website served from the bucket.

The return value is a frozen (unmodifiable) array of hashes containing the attributes specified for the Bucket resource field cors.

This method also accepts a block for updating the bucket's CORS rules. See Cors for details.

Examples:

Retrieving the bucket's CORS rules.

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"
bucket.cors #=> [{"origin"=>["http://example.org"],
            #     "method"=>["GET","POST","DELETE"],
            #     "responseHeader"=>["X-My-Custom-Header"],
            #     "maxAgeSeconds"=>3600}]

Updating the bucket's CORS rules inside a block.

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket = storage.bucket "my-todo-app"

bucket.update do |b|
  b.cors do |c|
    c.add_rule ["http://example.org", "https://example.org"],
               "*",
               response_headers: ["X-My-Custom-Header"],
               max_age: 3600
  end
end

Yields:

  • (cors) —

    a block for setting CORS rules

Yield Parameters:

See Also:



128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/google/cloud/storage/bucket.rb', line 128

def cors
  cors_builder = Bucket::Cors.from_gapi @gapi.cors_configurations
  if block_given?
    yield cors_builder
    if cors_builder.changed?
      @gapi.cors_configurations = cors_builder.to_gapi
      patch_gapi! :cors_configurations
    end
  end
  cors_builder.freeze # always return frozen objects
end

#create_file(file, path = nil, acl: nil, cache_control: nil, content_disposition: nil, content_encoding: nil, content_language: nil, content_type: nil, crc32c: nil, md5: nil, metadata: nil, encryption_key: nil, encryption_key_sha256: nil) ⇒ Google::Cloud::Storage::File Also known as: upload_file, new_file

Creates a new File object by providing a path to a local file to upload and the path to store it with in the bucket.

Customer-supplied encryption keys

By default, Google Cloud Storage manages server-side encryption keys on your behalf. However, a customer-supplied encryption key can be provided with the encryption_key and encryption_key_sha256 options. If given, the same key and SHA256 hash also must be provided to subsequently download or copy the file. If you use customer-supplied encryption keys, you must securely manage your keys and ensure that they are not lost. Also, please note that file metadata is not encrypted, with the exception of the CRC32C checksum and MD5 hash. The names of files and buckets are also not encrypted, and you can read or update the metadata of an encrypted file without providing the encryption key.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.create_file "path/to/local.file.ext"

Specifying a destination path:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.create_file "path/to/local.file.ext",
                   "destination/path/file.ext"

Providing a customer-supplied encryption key:

require "google/cloud/storage"
require "digest/sha2"

storage = Google::Cloud::Storage.new
bucket = storage.bucket "my-bucket"

# Key generation shown for example purposes only. Write your own.
cipher = OpenSSL::Cipher.new "aes-256-cfb"
cipher.encrypt
key = cipher.random_key
key_hash = Digest::SHA256.digest key

bucket.create_file "path/to/local.file.ext",
                   "destination/path/file.ext",
                   encryption_key: key,
                   encryption_key_sha256: key_hash

# Store your key and hash securely for later use.
file = bucket.file "destination/path/file.ext",
                   encryption_key: key,
                   encryption_key_sha256: key_hash

Parameters:

  • file (String) —

    Path of the file on the filesystem to upload.

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

    Path to store the file in Google Cloud Storage.

  • acl (String) —

    A predefined set of access controls to apply to this file.

    Acceptable values are:

    • auth, auth_read, authenticated, authenticated_read, authenticatedRead - File owner gets OWNER access, and allAuthenticatedUsers get READER access.
    • owner_full, bucketOwnerFullControl - File owner gets OWNER access, and project team owners get OWNER access.
    • owner_read, bucketOwnerRead - File owner gets OWNER access, and project team owners get READER access.
    • private - File owner gets OWNER access.
    • project_private, projectPrivate - File owner gets OWNER access, and project team members get access according to their roles.
    • public, public_read, publicRead - File owner gets OWNER access, and allUsers get READER access.
  • cache_control (String) —

    The Cache-Control response header to be returned when the file is downloaded.

  • content_disposition (String) —

    The Content-Disposition response header to be returned when the file is downloaded.

  • content_encoding (String) —

    The Content-Encoding response header to be returned when the file is downloaded.

  • content_language (String) —

    The Content-Language response header to be returned when the file is downloaded.

  • content_type (String) —

    The Content-Type response header to be returned when the file is downloaded.

  • crc32c (String) —

    The CRC32c checksum of the file data, as described in RFC 4960, Appendix B. If provided, Cloud Storage will only create the file if the value matches the value calculated by the service. See Validation for more information.

  • md5 (String) —

    The MD5 hash of the file data. If provided, Cloud Storage will only create the file if the value matches the value calculated by the service. See Validation for more information.

  • metadata (Hash) —

    A hash of custom, user-provided web-safe keys and arbitrary string values that will returned with requests for the file as "x-goog-meta-" response headers.

  • encryption_key (String) —

    Optional. A customer-supplied, AES-256 encryption key that will be used to encrypt the file. Must be provided if encryption_key_sha256 is provided.

  • encryption_key_sha256 (String) —

    Optional. The SHA256 hash of the customer-supplied, AES-256 encryption key that will be used to encrypt the file. Must be provided if encryption_key is provided.

Returns:



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
 
# File 'lib/google/cloud/storage/bucket.rb', line 575

def create_file file, path = nil, acl: nil, cache_control: nil,
                content_disposition: nil, content_encoding: nil,
                content_language: nil, content_type: nil,
                crc32c: nil, md5: nil, metadata: nil,
                encryption_key: nil, encryption_key_sha256: nil
  ensure_service!
  options = { acl: File::Acl.predefined_rule_for(acl), md5: md5,
              cache_control: cache_control, content_type: content_type,
              content_disposition: content_disposition, crc32c: crc32c,
              content_encoding: content_encoding,
              content_language: content_language, metadata: metadata,
              key: encryption_key, key_sha256: encryption_key_sha256 }
  ensure_file_exists! file
  # TODO: Handle file as an IO and path is missing more gracefully
  path ||= Pathname(file).to_path
  gapi = service.insert_file name, file, path, options
  File.from_gapi gapi, service
end

#created_at ⇒ Object

Creation time of the bucket.



81
82
83
 
# File 'lib/google/cloud/storage/bucket.rb', line 81

def created_at
  @gapi.time_created
end

#default_acl ⇒ Object

The Bucket::DefaultAcl instance used to control access to the bucket's files.

A bucket's files have owners, writers, and readers. Permissions can be granted to an individual user's email address, a group's email address, as well as many predefined lists.

Examples:

Grant access to a user by prepending "user-" to an email:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

email = "heidi@example.net"
bucket.default_acl.add_reader "user-#{email}"

Grant access to a group by prepending "group-" to an email

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

email = "authors@example.net"
bucket.default_acl.add_reader "group-#{email}"

Or, grant access via a predefined permissions list:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.default_acl.public!

See Also:



761
762
763
 
# File 'lib/google/cloud/storage/bucket.rb', line 761

def default_acl
  @default_acl ||= Bucket::DefaultAcl.new self
end

#delete ⇒ Boolean

Permanently deletes the bucket. The bucket must be empty before it can be deleted.

The API call to delete the bucket may be retried under certain conditions. See Google::Cloud#storage to control this behavior.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"
bucket.delete

Returns:

  • (Boolean) —

    Returns true if the bucket was deleted.



340
341
342
343
344
 
# File 'lib/google/cloud/storage/bucket.rb', line 340

def delete
  ensure_service!
  service.delete_bucket name
  true
end

#file(path, generation: nil, encryption_key: nil, encryption_key_sha256: nil) ⇒ Google::Cloud::Storage::File? Also known as: find_file

Retrieves a file matching the path.

If a customer-supplied encryption key was used with #create_file, the encryption_key and encryption_key_sha256 options must be provided or else the file's CRC32C checksum and MD5 hash will not be returned.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
puts file.name

Parameters:

  • path (String) —

    Name (path) of the file.

  • generation (Integer) —

    When present, selects a specific revision of this object. Default is the latest version.

  • encryption_key (String) —

    Optional. The customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to #create_file. Must be provided if encryption_key_sha256 is provided.

  • encryption_key_sha256 (String) —

    Optional. The SHA256 hash of the customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to #create_file. Must be provided if encryption_key is provided.

Returns:



443
444
445
446
447
448
449
450
451
452
 
# File 'lib/google/cloud/storage/bucket.rb', line 443

def file path, generation: nil, encryption_key: nil,
         encryption_key_sha256: nil
  ensure_service!
  options = { generation: generation, key: encryption_key,
              key_sha256: encryption_key_sha256 }
  gapi = service.get_file name, path, options
  File.from_gapi gapi, service
rescue Google::Cloud::NotFoundError
  nil
end

#files(prefix: nil, delimiter: nil, token: nil, max: nil, versions: nil) ⇒ Array<Google::Cloud::Storage::File> Also known as: find_files

Retrieves a list of files matching the criteria.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"
files = bucket.files
files.each do |file|
  puts file.name
end

Retrieve all files: (See File::List#all)

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"
files = bucket.files
files.all do |file|
  puts file.name
end

Parameters:

  • prefix (String) —

    Filter results to files whose names begin with this prefix.

  • delimiter (String) —

    Returns results in a directory-like mode. items will contain only objects whose names, aside from the prefix, do not contain delimiter. Objects whose names, aside from the prefix, contain delimiter will have their name, truncated after the delimiter, returned in prefixes. Duplicate prefixes are omitted.

  • token (String) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) —

    Maximum number of items plus prefixes to return. As duplicate prefixes are omitted, fewer total results may be returned than requested. The default value of this parameter is 1,000 items.

  • versions (Boolean) —

    If true, lists all versions of an object as distinct results. The default is false. For more information, see Object Versioning .

Returns:



393
394
395
396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/google/cloud/storage/bucket.rb', line 393

def files prefix: nil, delimiter: nil, token: nil, max: nil,
          versions: nil
  ensure_service!
  options = {
    prefix:    prefix,
    delimiter: delimiter,
    token:     token,
    max:       max,
    versions:  versions
  }
  gapi = service.list_files name, options
  File::List.from_gapi gapi, service, name, prefix, delimiter, max,
                       versions
end

#id ⇒ Object

The ID of the bucket.



63
64
65
 
# File 'lib/google/cloud/storage/bucket.rb', line 63

def id
  @gapi.id
end

#kind ⇒ Object

The kind of item this is. For buckets, this is always storage#bucket.



57
58
59
 
# File 'lib/google/cloud/storage/bucket.rb', line 57

def kind
  @gapi.kind
end

#location ⇒ Object

The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Defaults to US. See the developer's guide for the authoritative list.

See Also:



147
148
149
 
# File 'lib/google/cloud/storage/bucket.rb', line 147

def location
  @gapi.location
end

#logging_bucket ⇒ Object

The destination bucket name for the bucket's logs.

See Also:



156
157
158
 
# File 'lib/google/cloud/storage/bucket.rb', line 156

def logging_bucket
  @gapi.logging.log_bucket if @gapi.logging
end

#logging_bucket=(logging_bucket) ⇒ Object

Updates the destination bucket for the bucket's logs.

Parameters:

  • logging_bucket (String) —

    The bucket to hold the logging output

See Also:



167
168
169
170
171
 
# File 'lib/google/cloud/storage/bucket.rb', line 167

def logging_bucket= logging_bucket
  @gapi.logging ||= Google::Apis::StorageV1::Bucket::Logging.new
  @gapi.logging.log_bucket = logging_bucket
  patch_gapi! :logging
end

#logging_prefix ⇒ Object

The logging object prefix for the bucket's logs. For more information,

See Also:



178
179
180
 
# File 'lib/google/cloud/storage/bucket.rb', line 178

def logging_prefix
  @gapi.logging.log_object_prefix if @gapi.logging
end

#logging_prefix=(logging_prefix) ⇒ Object

Updates the logging object prefix. This prefix will be used to create log object names for the bucket. It can be at most 900 characters and must be a valid object name. By default, the object prefix is the name of the bucket for which the logs are enabled.

See Also:



192
193
194
195
196
 
# File 'lib/google/cloud/storage/bucket.rb', line 192

def logging_prefix= logging_prefix
  @gapi.logging ||= Google::Apis::StorageV1::Bucket::Logging.new
  @gapi.logging.log_object_prefix = logging_prefix
  patch_gapi! :logging
end

#name ⇒ Object

The name of the bucket.



69
70
71
 
# File 'lib/google/cloud/storage/bucket.rb', line 69

def name
  @gapi.name
end

#reload! ⇒ Object Also known as: refresh!

Reloads the bucket with current data from the Storage service.



767
768
769
770
 
# File 'lib/google/cloud/storage/bucket.rb', line 767

def reload!
  ensure_service!
  @gapi = service.get_bucket name
end

#signed_url(path, method: nil, expires: nil, content_type: nil, content_md5: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil) ⇒ Object

Access without authentication can be granted to a File for a specified period of time. This URL uses a cryptographic signature of your credentials to access the file identified by path. A URL can be created for paths that do not yet exist. For instance, a URL can be created to PUT file contents to.

Generating a URL requires service account credentials, either by connecting with a service account when calling Google::Cloud.storage, or by passing in the service account issuer and signing_key values. Although the private key can be passed as a string for convenience, creating and storing an instance of OpenSSL::PKey::RSA is more efficient when making multiple calls to signed_url.

A SignedUrlUnavailable is raised if the service account credentials are missing. Service account credentials are acquired by following the steps in Service Account Authentication.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"
shared_url = bucket.signed_url "avatars/heidi/400x400.png",

Any of the option parameters may be specified:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"
shared_url = bucket.signed_url "avatars/heidi/400x400.png",
                               method: "PUT",
                               expires: 300 # 5 minutes from now

Using the issuer and signing_key options:

require "google/cloud/storage"

storage = Google::Cloud.storage

bucket = storage.bucket "my-todo-app"
key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."
shared_url = bucket.signed_url "avatars/heidi/400x400.png",
                               issuer: "service-account@gcloud.com",
                               signing_key: key

Parameters:

  • path (String) —

    Path to of the file in Google Cloud Storage.

  • method (String) —

    The HTTP verb to be used with the signed URL. Signed URLs can be used with GET, HEAD, PUT, and DELETE requests. Default is GET.

  • expires (Integer) —

    The number of seconds until the URL expires. Default is 300/5 minutes.

  • content_type (String) —

    When provided, the client (browser) must send this value in the HTTP header. e.g. text/plain

  • content_md5 (String) —

    The MD5 digest value in base64. If you provide this in the string, the client (usually a browser) must provide this HTTP header with this same value in its request.

  • issuer (String) —

    Service Account's Client Email.

  • client_email (String) —

    Service Account's Client Email.

  • signing_key (OpenSSL::PKey::RSA, String) —

    Service Account's Private Key.

  • private_key (OpenSSL::PKey::RSA, String) —

    Service Account's Private Key.

See Also:



666
667
668
669
670
671
672
673
674
675
676
 
# File 'lib/google/cloud/storage/bucket.rb', line 666

def signed_url path, method: nil, expires: nil, content_type: nil,
               content_md5: nil, issuer: nil, client_email: nil,
               signing_key: nil, private_key: nil
  ensure_service!
  options = { method: method, expires: expires,
              content_type: content_type, content_md5: content_md5,
              issuer: issuer, client_email: client_email,
              signing_key: signing_key, private_key: private_key }
  signer = File::Signer.from_bucket self, path
  signer.signed_url options
end

#storage_class ⇒ Object

The bucket's storage class. This defines how objects in the bucket are stored and determines the SLA and the cost of storage. Values include MULTI_REGIONAL, REGIONAL, NEARLINE, COLDLINE, STANDARD, and DURABLE_REDUCED_AVAILABILITY.



203
204
205
 
# File 'lib/google/cloud/storage/bucket.rb', line 203

def storage_class
  @gapi.storage_class
end

#update {|bucket| ... } ⇒ Object

Updates the bucket with changes made in the given block in a single PATCH request. The following attributes may be set: #cors, #logging_bucket=, #logging_prefix=, #versioning=, #website_main=, and #website_404=. In addition, the #cors configuration accessible in the block is completely mutable and will be included in the request. (See Cors)

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"
bucket.update do |b|
  b.website_main = "index.html"
  b.website_404 = "not_found.html"
  b.cors[0]["method"] = ["GET","POST","DELETE"]
  b.cors[1]["responseHeader"] << "X-Another-Custom-Header"
end

New CORS rules can also be added in a nested block:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket = storage.bucket "my-todo-app"

bucket.update do |b|
  b.cors do |c|
    c.add_rule ["http://example.org", "https://example.org"],
               "*",
               response_headers: ["X-My-Custom-Header"],
               max_age: 300
  end
end

Yields:

  • (bucket) —

    a block yielding a delegate object for updating the file



315
316
317
318
319
320
321
 
# File 'lib/google/cloud/storage/bucket.rb', line 315

def update
  updater = Updater.new @gapi
  yield updater
  # Add check for mutable cors
  updater.check_for_mutable_cors!
  patch_gapi! updater.updates unless updater.updates.empty?
end

#versioning=(new_versioning) ⇒ Boolean

Updates whether Object Versioning is enabled for the bucket.

Returns:

  • (Boolean) 


222
223
224
225
226
 
# File 'lib/google/cloud/storage/bucket.rb', line 222

def versioning= new_versioning
  @gapi.versioning ||= Google::Apis::StorageV1::Bucket::Versioning.new
  @gapi.versioning.enabled = new_versioning
  patch_gapi! :versioning
end

#versioning? ⇒ Boolean

Whether Object Versioning is enabled for the bucket.

Returns:

  • (Boolean) 


211
212
213
 
# File 'lib/google/cloud/storage/bucket.rb', line 211

def versioning?
  @gapi.versioning.enabled? unless @gapi.versioning.nil?
end

#website_404 ⇒ Object

The page returned from a static website served from the bucket when a site visitor requests a resource that does not exist.

See Also:



259
260
261
 
# File 'lib/google/cloud/storage/bucket.rb', line 259

def website_404
  @gapi.website.not_found_page if @gapi.website
end

#website_404=(website_404) ⇒ Object

Updates the page returned from a static website served from the bucket when a site visitor requests a resource that does not exist.

See Also:



270
271
272
273
274
 
# File 'lib/google/cloud/storage/bucket.rb', line 270

def website_404= website_404
  @gapi.website ||= Google::Apis::StorageV1::Bucket::Website.new
  @gapi.website.not_found_page = website_404
  patch_gapi! :website
end

#website_main ⇒ Object

The index page returned from a static website served from the bucket when a site visitor requests the top level directory.

See Also:



235
236
237
 
# File 'lib/google/cloud/storage/bucket.rb', line 235

def website_main
  @gapi.website.main_page_suffix if @gapi.website
end

#website_main=(website_main) ⇒ Object

Updates the index page returned from a static website served from the bucket when a site visitor requests the top level directory.

See Also:



246
247
248
249
250
 
# File 'lib/google/cloud/storage/bucket.rb', line 246

def website_main= website_main
  @gapi.website ||= Google::Apis::StorageV1::Bucket::Website.new
  @gapi.website.main_page_suffix = website_main
  patch_gapi! :website
end