Class: Gcloud::Storage::Bucket
- Inherits:
-
Object
- Object
- Gcloud::Storage::Bucket
- Defined in:
- lib/gcloud/storage/bucket.rb,
lib/gcloud/storage/bucket/acl.rb,
lib/gcloud/storage/bucket/list.rb
Overview
Defined Under Namespace
Classes: Acl, DefaultAcl, List
Instance Attribute Summary collapse
-
#connection ⇒ Object
The Connection object.
-
#gapi ⇒ Object
The Google API Client object.
Class Method Summary collapse
-
.from_gapi(gapi, conn) ⇒ Object
New Bucket from a Google API Client object.
Instance Method Summary collapse
-
#acl ⇒ Object
The Bucket::Acl instance used to control access to the bucket.
-
#create_file(file, path = nil, options = {}) ⇒ Object
(also: #upload_file, #new_file)
Create 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(options = {}) ⇒ Object
Permenently deletes the bucket.
-
#file(path, options = {}) ⇒ Object
(also: #find_file)
Retrieves a file matching the path.
-
#files(options = {}) ⇒ Object
(also: #find_files)
Retrieves a list of files matching the criteria.
-
#id ⇒ Object
The ID of the bucket.
-
#initialize ⇒ Bucket
constructor
Create an empty Bucket object.
-
#kind ⇒ Object
The kind of item this is.
-
#location ⇒ Object
The location of the bucket.
-
#name ⇒ Object
The name of the bucket.
-
#url ⇒ Object
The URI of this bucket.
Constructor Details
#initialize ⇒ Bucket
Create an empty Bucket object.
47 48 49 50 |
# File 'lib/gcloud/storage/bucket.rb', line 47 def initialize #:nodoc: @connection = nil @gapi = {} end |
Instance Attribute Details
#connection ⇒ Object
The Connection object.
39 40 41 |
# File 'lib/gcloud/storage/bucket.rb', line 39 def connection @connection end |
#gapi ⇒ Object
The Google API Client object.
43 44 45 |
# File 'lib/gcloud/storage/bucket.rb', line 43 def gapi @gapi end |
Class Method Details
.from_gapi(gapi, conn) ⇒ Object
New Bucket from a Google API Client object.
452 453 454 455 456 457 |
# File 'lib/gcloud/storage/bucket.rb', line 452 def self.from_gapi gapi, conn #:nodoc: new.tap do |f| f.gapi = gapi f.connection = conn end end |
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. See the Access Control guide for more.
Examples
Access to a bucket can be granted to a user by appending “user-” to the email address:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
email = "[email protected]"
bucket.acl.add_reader "user-#{email}"
Access to a bucket can be granted to a group by appending “group-” to the email address:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
email = "[email protected]"
bucket.acl.add_reader "group-#{email}"
Access to a bucket can also be granted to a predefined list of permissions:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
bucket.acl.public!
392 393 394 |
# File 'lib/gcloud/storage/bucket.rb', line 392 def acl @acl ||= Bucket::Acl.new self end |
#create_file(file, path = nil, options = {}) ⇒ Object Also known as: upload_file, new_file
Create a new File object by providing a path to a local file to upload and the path to store it with in the bucket.
Parameters
file
-
Path of the file on the filesystem to upload. (
String
) path
-
Path to store the file in Google Cloud Storage. (
String
) options
-
An optional Hash for controlling additional behavior. (
Hash
) options[:acl]
-
A predefined set of access controls to apply to this file. (
String
)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.
-
Returns
Gcloud::Storage::File
Examples
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
bucket.create_file "path/to/local.file.ext"
Additionally, a destination path can be specified.
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
bucket.create_file "path/to/local.file.ext",
"destination/path/file.ext"
A chunk_size value can be provided in the options to be used in resumable uploads. This value is the number of bytes per chunk and must be divisible by 256KB. If it is not divisible by 265KB then it will be lowered to the nearest acceptible value.
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
bucket.create_file "path/to/local.file.ext",
"destination/path/file.ext",
chunk_size: 1024*1024 # 1 MB chunk
327 328 329 330 331 332 333 334 335 336 337 338 |
# File 'lib/gcloud/storage/bucket.rb', line 327 def create_file file, path = nil, = {} ensure_connection! ensure_file_exists! file [:acl] = File::Acl.predefined_rule_for [:acl] if resumable_upload? file upload_resumable file, path, [:chunk_size], else upload_multipart file, path, end end |
#created_at ⇒ Object
Creation time of the bucket.
90 91 92 |
# File 'lib/gcloud/storage/bucket.rb', line 90 def created_at @gapi["timeCreated"] 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. See the Access Control guide for more.
Examples
Access to a bucket’s files can be granted to a user by appending “user-” to the email address:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
email = "[email protected]"
bucket.default_acl.add_reader "user-#{email}"
Access to a bucket’s files can be granted to a group by appending “group-” to the email address:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
email = "[email protected]"
bucket.default_acl.add_reader "group-#{email}"
Access to a bucket’s files can also be granted to a predefined list of permissions:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"
bucket.default_acl.public!
446 447 448 |
# File 'lib/gcloud/storage/bucket.rb', line 446 def default_acl @default_acl ||= Bucket::DefaultAcl.new self end |
#delete(options = {}) ⇒ Object
Permenently deletes the bucket. The bucket must be empty before it can be deleted.
Parameters
options
-
An optional Hash for controlling additional behavior. (
Hash
) options[:retries]
-
The number of times the API call should be retried. Default is Gcloud::Backoff.retries. (
Integer
)
Returns
true
if the bucket was deleted.
Examples
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
bucket.delete
The API call to delete the bucket may be retried under certain conditions. See Gcloud::Backoff to control this behavior, or specify the wanted behavior in the call:
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
bucket.delete retries: 5
132 133 134 135 136 137 138 139 140 |
# File 'lib/gcloud/storage/bucket.rb', line 132 def delete = {} ensure_connection! resp = connection.delete_bucket name, if resp.success? true else fail ApiError.from_response(resp) end end |
#file(path, options = {}) ⇒ Object Also known as: find_file
Retrieves a file matching the path.
Parameters
path
-
Name (path) of the file. (
String
)
Returns
Gcloud::Storage::File or nil if file does not exist
Example
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
file = bucket.file "path/to/my-file.ext"
puts file.name
242 243 244 245 246 247 248 249 250 |
# File 'lib/gcloud/storage/bucket.rb', line 242 def file path, = {} ensure_connection! resp = connection.get_file name, path, if resp.success? File.from_gapi resp.data, connection else fail ApiError.from_response(resp) end end |
#files(options = {}) ⇒ Object Also known as: find_files
Retrieves a list of files matching the criteria.
Parameters
options
-
An optional Hash for controlling additional behavior. (
Hash
) options[:prefix]
-
Filter results to files whose names begin with this prefix. (
String
) options[:token]
-
A previously-returned page token representing part of the larger set of results to view. (
String
) options[:max]
-
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. (
Integer
) options[:versions]
-
If
true
, lists all versions of an object as distinct results. The default isfalse
. For more information, see Object Versioning . (Boolean
) options[:max]
-
Maximum number of buckets to return. (
Integer
)
Returns
Array of Gcloud::Storage::File (Gcloud::Storage::File::List)
Examples
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
files = bucket.files
files.each do |file|
puts file.name
end
If you have a significant number of files, you may need to paginate through them: (See File::List#token)
require "gcloud"
gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-bucket"
all_files = []
tmp_files = bucket.files
while tmp_files.any? do
tmp_files.each do |file|
all_files << file
end
# break loop if no more buckets available
break if tmp_files.token.nil?
# get the next group of files
tmp_files = bucket.files token: tmp_files.token
end
207 208 209 210 211 212 213 214 215 |
# File 'lib/gcloud/storage/bucket.rb', line 207 def files = {} ensure_connection! resp = connection.list_files name, if resp.success? File::List.from_resp resp, connection else fail ApiError.from_response(resp) end end |
#id ⇒ Object
The ID of the bucket.
61 62 63 |
# File 'lib/gcloud/storage/bucket.rb', line 61 def id @gapi["id"] end |
#kind ⇒ Object
The kind of item this is. For buckets, this is always storage#bucket.
55 56 57 |
# File 'lib/gcloud/storage/bucket.rb', line 55 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.
84 85 86 |
# File 'lib/gcloud/storage/bucket.rb', line 84 def location @gapi["location"] end |
#name ⇒ Object
The name of the bucket.
67 68 69 |
# File 'lib/gcloud/storage/bucket.rb', line 67 def name @gapi["name"] end |
#url ⇒ Object
The URI of this bucket.
73 74 75 |
# File 'lib/gcloud/storage/bucket.rb', line 73 def url @gapi["selfLink"] end |