Class: Gcloud::Storage::Bucket

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

Overview

Bucket

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

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

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

Defined Under Namespace

Classes: Acl, DefaultAcl, List

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

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.



482
483
484
485
486
487
 
# File 'lib/gcloud/storage/bucket.rb', line 482

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!



409
410
411
 
# File 'lib/gcloud/storage/bucket.rb', line 409

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

A note about large uploads

You may encounter a broken pipe error while attempting to upload large files. To avoid this problem, add httpclient as a dependency to your project, and configure Faraday to use it, after requiring Gcloud, but before initiating your Gcloud connection.

require "gcloud"

Faraday.default_adapter = :httpclient

gcloud = Gcloud.new
storage = gcloud.storage
bucket = storage.bucket "my-todo-app"



344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/gcloud/storage/bucket.rb', line 344

def create_file file, path = nil, options = {}
  ensure_connection!
  ensure_file_exists! file

  options[:acl] = File::Acl.predefined_rule_for options[:acl]

  if resumable_upload? file
    upload_resumable file, path, options[:chunk_size], options
  else
    upload_multipart file, path, options
  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!



463
464
465
 
# File 'lib/gcloud/storage/bucket.rb', line 463

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 options = {}
  ensure_connection!
  resp = connection.delete_bucket name, options
  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, options = {}
  ensure_connection!
  resp = connection.get_file name, path, options
  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 is false. 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 options = {}
  ensure_connection!
  resp = connection.list_files name, options
  if resp.success?
    File::List.from_response 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.

cloud.google.com/storage/docs/concepts-techniques



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

#reload! ⇒ Object Also known as: refresh!

Reloads the bucket with current data from the Storage service.



469
470
471
472
473
474
475
476
477
 
# File 'lib/gcloud/storage/bucket.rb', line 469

def reload!
  ensure_connection!
  resp = connection.get_bucket name
  if resp.success?
    @gapi = resp.data
  else
    fail ApiError.from_response(resp)
  end
end

#url ⇒ Object

The URI of this bucket.



73
74
75
 
# File 'lib/gcloud/storage/bucket.rb', line 73

def url
  @gapi["selfLink"]
end