Class: Gcloud::Storage::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/storage/project.rb

Overview

# Project

Represents the project that storage buckets and files belong to. All data in Google Cloud Storage belongs inside a project. A project consists of a set of users, a set of APIs, billing, authentication, and monitoring settings for those APIs.

Gcloud::Storage::Project is the main object for interacting with Google Storage. Bucket objects are created, read, updated, and deleted by Gcloud::Storage::Project.

See Gcloud#storage

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(project, credentials) ⇒ Project

See Gcloud#storage



58
59
60
61
62
 
# File 'lib/gcloud/storage/project.rb', line 58

def initialize project, credentials
  project = project.to_s # Always cast to a string
  fail ArgumentError, "project is missing" if project.empty?
  @connection = Connection.new project, credentials
end

Instance Attribute Details

#connection ⇒ Object 



52
53
54
 
# File 'lib/gcloud/storage/project.rb', line 52

def connection
  @connection
end

Class Method Details

.default_project ⇒ Object 



82
83
84
85
86
87
 
# File 'lib/gcloud/storage/project.rb', line 82

def self.default_project
  ENV["STORAGE_PROJECT"] ||
    ENV["GCLOUD_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"] ||
    Gcloud::GCE.project_id
end

Instance Method Details

#bucket(bucket_name) ⇒ Gcloud::Storage::Bucket? Also known as: find_bucket

Retrieves bucket by name.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"
puts bucket.name

Parameters:

  • bucket_name (String) —

    Name of a bucket.

Returns:



166
167
168
169
170
171
172
173
174
 
# File 'lib/gcloud/storage/project.rb', line 166

def bucket bucket_name
  resp = connection.get_bucket bucket_name
  if resp.success?
    Bucket.from_gapi resp.data, connection
  else
    return nil if resp.data["error"]["code"] == 404
    fail ApiError.from_response(resp)
  end
end

#buckets(prefix: nil, token: nil, max: nil) ⇒ Array<Gcloud::Storage::Bucket> Also known as: find_buckets

Retrieves a list of buckets for the given project.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

buckets = storage.buckets
buckets.each do |bucket|
  puts bucket.name
end

Retrieve all buckets with names that begin with a given prefix:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

user_buckets = storage.buckets prefix: "user-"

With pagination: (See Bucket::List#token)

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

all_buckets = []
tmp_buckets = storage.buckets
while tmp_buckets.any? do
  tmp_buckets.each do |bucket|
    all_buckets << bucket
  end
  # break loop if no more buckets available
  break if tmp_buckets.token.nil?
  # get the next group of buckets
  tmp_buckets = storage.buckets token: tmp_buckets.token
end

Parameters:

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

    Filter results to buckets whose names begin with this prefix.

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

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

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

    Maximum number of buckets to return.

Returns:



138
139
140
141
142
143
144
145
146
 
# File 'lib/gcloud/storage/project.rb', line 138

def buckets prefix: nil, token: nil, max: nil
  options = { prefix: prefix, token: token, max: max }
  resp = connection.list_buckets options
  if resp.success?
    Bucket::List.from_response resp, connection
  else
    fail ApiError.from_response(resp)
  end
end

#create_bucket(bucket_name, acl: nil, default_acl: nil, cors: nil, location: nil, logging_bucket: nil, logging_prefix: nil, retries: nil, storage_class: nil, versioning: nil, website_main: nil, website_404: nil) {|cors| ... } ⇒ Gcloud::Storage::Bucket

Creates a new bucket with optional attributes. Also accepts a block for defining the CORS configuration for a static website served from the bucket. See Bucket::Cors for details.

The API call to create the bucket may be retried under certain conditions. See Backoff to control this behavior, or specify the wanted behavior in the call with the ‘:retries:` option.

You can pass [website settings](cloud.google.com/storage/docs/website-configuration) for the bucket, including a block that defines CORS rule. See Bucket::Cors for details.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.create_bucket "my-bucket"

Specify the number of retries to attempt:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.create_bucket "my-bucket", retries: 5

Add CORS rules in a block:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

options = {
  website_main: "index.html"
  website_404: "not_found.html"
}
bucket = storage.create_bucket "my-bucket", options do |c|
  c.add_rule ["http://example.org", "https://example.org"],
             "*",
             response_headers: ["X-My-Custom-Header"],
             max_age: 300
end

Parameters:

  • bucket_name (String) —

    Name of a bucket.

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

    Apply a predefined set of access controls to this bucket.

    Acceptable values are:

    • ‘auth`, `auth_read`, `authenticated`, `authenticated_read`, `authenticatedRead` - Project team owners get OWNER access, and allAuthenticatedUsers get READER access.

    • ‘private` - Project team owners get OWNER access.

    • ‘project_private`, `projectPrivate` - Project team members get access according to their roles.

    • ‘public`, `public_read`, `publicRead` - Project team owners get OWNER access, and allUsers get READER access.

    • ‘public_write`, `publicReadWrite` - Project team owners get OWNER access, and allUsers get WRITER access.

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

    Apply a predefined set of default object access controls to this bucket.

    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.

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

    The CORS rules for the bucket. Accepts an array of hashes containing the attributes specified for the [resource description of cors](cloud.google.com/storage/docs/json_api/v1/buckets#cors).

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

    The location of the bucket. Object data for objects in the bucket resides in physical storage within this region. Possible values include ‘ASIA`, `EU`, and `US`. (See the [developer’s guide](cloud.google.com/storage/docs/bucket-locations) for the authoritative list. The default value is ‘US`.

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

    The destination bucket for the bucket’s logs. For more information, see [Access Logs](cloud.google.com/storage/docs/access-logs).

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

    The prefix used to create log object names for the bucket. It can be at most 900 characters and must be a [valid object name](cloud.google.com/storage/docs/bucket-naming#objectnames) . By default, the object prefix is the name of the bucket for which the logs are enabled. For more information, see [Access Logs](cloud.google.com/storage/docs/access-logs).

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

    The number of times the API call should be retried. Default is Backoff.retries.

  • storage_class (Symbol, String) (defaults to: nil) —

    Defines how objects in the bucket are stored and determines the SLA and the cost of storage. Values include ‘:standard`, `:nearline`, and `:dra` (Durable Reduced Availability), as well as the strings returned by Bucket#storage_class. For more information, see [Storage Classes](cloud.google.com/storage/docs/storage-classes). The default value is `:standard`.

  • versioning (Boolean) (defaults to: nil) —

    Whether [Object Versioning](cloud.google.com/storage/docs/object-versioning) is to be enabled for the bucket. The default value is ‘false`.

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

    The index page returned from a static website served from the bucket when a site visitor requests the top level directory. For more information, see [How to Host a Static Website ](cloud.google.com/storage/docs/website-configuration#step4).

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

    The page returned from a static website served from the bucket when a site visitor requests a resource that does not exist. For more information, see [How to Host a Static Website ](cloud.google.com/storage/docs/website-configuration#step4).

Yields:

  • (cors) —

    a block for setting CORS rules

Yield Parameters:

Returns:

See Also:



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/gcloud/storage/project.rb', line 308

def create_bucket bucket_name, acl: nil, default_acl: nil, cors: nil,
                  location: nil, logging_bucket: nil, logging_prefix: nil,
                  retries: nil, storage_class: nil, versioning: nil,
                  website_main: nil, website_404: nil
  opts = { acl: acl_rule(acl), default_acl: acl_rule(default_acl),
           cors: cors, location: location, logging_bucket: logging_bucket,
           logging_prefix: logging_prefix, retries: retries,
           storage_class: storage_class, versioning: versioning,
           website_main: website_main, website_404: website_404 }
  if block_given?
    cors_builder = Bucket::Cors.new
    yield cors_builder
    opts[:cors] = cors_builder if cors_builder.changed?
  end
  insert_bucket bucket_name, opts
end

#project ⇒ Object

The Storage project connected to.

Examples:

require "gcloud"

gcloud = Gcloud.new "my-todo-project",
                    "/path/to/keyfile.json"
storage = gcloud.storage

storage.project #=> "my-todo-project"



76
77
78
 
# File 'lib/gcloud/storage/project.rb', line 76

def project
  connection.project
end