Class: Google::Cloud::Storage::Bucket
- Inherits:
-
Object
- Object
- Google::Cloud::Storage::Bucket
- 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.
Direct Known Subclasses
Defined Under Namespace
Classes: Acl, Cors, DefaultAcl, List, Updater
Instance Method Summary collapse
-
#acl ⇒ Object
The Bucket::Acl instance used to control access to the bucket.
-
#api_url ⇒ Object
A URL that can be used to access the bucket using the REST API.
-
#cors {|cors| ... } ⇒ Object
Returns the current CORS configuration for a static website served from the bucket.
-
#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) ⇒ Google::Cloud::Storage::File
(also: #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.
-
#created_at ⇒ Object
Creation time of the bucket.
-
#default_acl ⇒ Object
The Bucket::DefaultAcl instance used to control access to the bucket's files.
-
#delete ⇒ Boolean
Permanently deletes the bucket.
-
#file(path, generation: nil, encryption_key: nil) ⇒ Google::Cloud::Storage::File?
(also: #find_file)
Retrieves a file matching the path.
-
#files(prefix: nil, delimiter: nil, token: nil, max: nil, versions: nil) ⇒ Array<Google::Cloud::Storage::File>
(also: #find_files)
Retrieves a list of files matching the criteria.
-
#id ⇒ Object
The ID of the bucket.
-
#kind ⇒ Object
The kind of item this is.
-
#location ⇒ Object
The location of the bucket.
-
#logging_bucket ⇒ Object
The destination bucket name for the bucket's logs.
-
#logging_bucket=(logging_bucket) ⇒ Object
Updates the destination bucket for the bucket's logs.
-
#logging_prefix ⇒ Object
The logging object prefix for the bucket's logs.
-
#logging_prefix=(logging_prefix) ⇒ Object
Updates the logging object prefix.
-
#name ⇒ Object
The name of the bucket.
-
#reload! ⇒ Object
(also: #refresh!)
Reloads the bucket with current data from the Storage service.
-
#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.
-
#storage_class ⇒ Object
The bucket's storage class.
-
#update {|bucket| ... } ⇒ Object
Updates the bucket with changes made in the given block in a single PATCH request.
-
#versioning=(new_versioning) ⇒ Boolean
Updates whether Object Versioning is enabled for the bucket.
-
#versioning? ⇒ Boolean
Whether Object Versioning is enabled for the bucket.
-
#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.
-
#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.
-
#website_main ⇒ Object
The index page returned from a static website served from the bucket when a site visitor requests the top level directory.
-
#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.
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.
703 704 705 |
# File 'lib/google/cloud/storage/bucket.rb', line 703 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.
130 131 132 133 134 135 136 137 138 139 140 |
# File 'lib/google/cloud/storage/bucket.rb', line 130 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) ⇒ 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
option. If given, the same
key 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.
561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 |
# File 'lib/google/cloud/storage/bucket.rb', line 561 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 ensure_service! = { 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: , key: encryption_key } 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, 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.
747 748 749 |
# File 'lib/google/cloud/storage/bucket.rb', line 747 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.
342 343 344 345 346 |
# File 'lib/google/cloud/storage/bucket.rb', line 342 def delete ensure_service! service.delete_bucket name true end |
#file(path, generation: nil, encryption_key: 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
option must be
provided or else the file's CRC32C checksum and MD5 hash will not be
returned.
440 441 442 443 444 445 446 447 |
# File 'lib/google/cloud/storage/bucket.rb', line 440 def file path, generation: nil, encryption_key: nil ensure_service! = { generation: generation, key: encryption_key } gapi = service.get_file name, path, 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.
395 396 397 398 399 400 401 402 403 404 405 406 407 408 |
# File 'lib/google/cloud/storage/bucket.rb', line 395 def files prefix: nil, delimiter: nil, token: nil, max: nil, versions: nil ensure_service! = { prefix: prefix, delimiter: delimiter, token: token, max: max, versions: versions } gapi = service.list_files name, 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.
149 150 151 |
# File 'lib/google/cloud/storage/bucket.rb', line 149 def location @gapi.location end |
#logging_bucket ⇒ Object
The destination bucket name for the bucket's logs.
158 159 160 |
# File 'lib/google/cloud/storage/bucket.rb', line 158 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.
169 170 171 172 173 |
# File 'lib/google/cloud/storage/bucket.rb', line 169 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,
180 181 182 |
# File 'lib/google/cloud/storage/bucket.rb', line 180 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.
194 195 196 197 198 |
# File 'lib/google/cloud/storage/bucket.rb', line 194 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.
753 754 755 756 |
# File 'lib/google/cloud/storage/bucket.rb', line 753 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.
652 653 654 655 656 657 658 659 660 661 662 |
# File 'lib/google/cloud/storage/bucket.rb', line 652 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! = { 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 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
.
205 206 207 |
# File 'lib/google/cloud/storage/bucket.rb', line 205 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)
317 318 319 320 321 322 323 |
# File 'lib/google/cloud/storage/bucket.rb', line 317 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.
224 225 226 227 228 |
# File 'lib/google/cloud/storage/bucket.rb', line 224 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.
213 214 215 |
# File 'lib/google/cloud/storage/bucket.rb', line 213 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.
261 262 263 |
# File 'lib/google/cloud/storage/bucket.rb', line 261 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.
272 273 274 275 276 |
# File 'lib/google/cloud/storage/bucket.rb', line 272 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.
237 238 239 |
# File 'lib/google/cloud/storage/bucket.rb', line 237 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.
248 249 250 251 252 |
# File 'lib/google/cloud/storage/bucket.rb', line 248 def website_main= website_main @gapi.website ||= Google::Apis::StorageV1::Bucket::Website.new @gapi.website.main_page_suffix = website_main patch_gapi! :website end |