Reference documentation and code samples for the Cloud Storage API class Google::Cloud::Storage::Project.
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.
Google::Cloud::Storage::Project is the main object for interacting with Google Storage. Bucket objects are created, read, updated, and deleted by Google::Cloud::Storage::Project.
Inherits
- Object
Example
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext"
Methods
#add_custom_header
def add_custom_header(header_name, header_value) -> Google::Cloud::Storage::Project
Add custom Google extension header to the requests that use the signed URLs.
-
header_name (String) — Name of Google extension header (custom HTTP header that
begin with
x-goog-
) to be included in requests that use the signed URLs. For a reference of allowed headers, see Reference Headers. - header_value (Object) — Valid value of the Google extension header being added. For headers with multiple values, provide values as a simple array, or a comma-separated string.
- (Google::Cloud::Storage::Project) — Returns the Project for method chaining
#add_custom_headers
def add_custom_headers(headers) -> Google::Cloud::Storage::Project
Add custom Google extension headers to the requests that use the signed URLs.
-
headers (Hash) — Google extension headers (custom HTTP headers that
begin with
x-goog-
) to be included in requests that use the signed URLs. Provide headers as a key/value array, where the key is the header name, and the value is an array of header values. For headers with multiple values, provide values as a simple array, or a comma-separated string. For a reference of allowed headers, see Reference Headers.
- (Google::Cloud::Storage::Project) — Returns the Project for method chaining
#bucket
def bucket(bucket_name, skip_lookup: false, if_metageneration_match: nil, if_metageneration_not_match: nil, user_project: nil) -> Google::Cloud::Storage::Bucket, nil
Retrieves bucket by name.
- bucket_name (String) — Name of a bucket.
-
skip_lookup (Boolean) (defaults to: false) — Optionally create a Bucket object
without verifying the bucket resource exists on the Storage service.
Calls made on this object will raise errors if the bucket resource
does not exist. Default is
false
. - if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the bucket's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the bucket's current metageneration does not match the given value.
-
user_project (Boolean, String) (defaults to: nil) — If this parameter is set to
true
, transit costs for operations on the requested bucket or a file it contains will be billed to the current project for this client. (See #project for the ID of the current project.) If this parameter is set to a project ID other than the current project, and that project is authorized for the currently authenticated service account, transit costs will be billed to the given project. This parameter is required with requester pays-enabled buckets. The default isnil
.The value provided will be applied to all operations on the returned bucket instance and its files.
See also Bucket#requester_pays= and Bucket#requester_pays.
- (Google::Cloud::Storage::Bucket, nil) — Returns nil if bucket does not exist
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" puts bucket.name
With user_project
set to bill costs to the default project:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "other-project-bucket", user_project: true files = bucket.files # Billed to current project
With user_project
set to a project other than the default:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "other-project-bucket", user_project: "my-other-project" files = bucket.files # Billed to "my-other-project"
#buckets
def buckets(prefix: nil, token: nil, max: nil, user_project: nil) -> Array<Google::Cloud::Storage::Bucket>
Retrieves a list of buckets for the given project.
- 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.
-
user_project (Boolean, String) (defaults to: nil) — If this parameter is set to
true
, transit costs for operations on the enabled buckets or their files will be billed to the current project for this client. (See #project for the ID of the current project.) If this parameter is set to a project ID other than the current project, and that project is authorized for the currently authenticated service account, transit costs will be billed to the given project. This parameter is required with requester pays-enabled buckets. The default isnil
.The value provided will be applied to all operations on the returned bucket instances and their files.
See also Bucket#requester_pays= and Bucket#requester_pays.
- (Array<Google::Cloud::Storage::Bucket>) — (See Bucket::List)
require "google/cloud/storage" storage = Google::Cloud::Storage.new buckets = storage.buckets buckets.each do |bucket| puts bucket.name end
Retrieve buckets with names that begin with a given prefix:
require "google/cloud/storage" storage = Google::Cloud::Storage.new user_buckets = storage.buckets prefix: "user-" user_buckets.each do |bucket| puts bucket.name end
Retrieve all buckets: (See Bucket::List#all)
require "google/cloud/storage" storage = Google::Cloud::Storage.new buckets = storage.buckets buckets.all do |bucket| puts bucket.name end
#create_bucket
def create_bucket(bucket_name, acl: nil, default_acl: nil, location: nil, custom_placement_config: nil, storage_class: nil, logging_bucket: nil, logging_prefix: nil, website_main: nil, website_404: nil, versioning: nil, requester_pays: nil, user_project: nil, autoclass_enabled: false, enable_object_retention: nil) { |bucket| ... } -> Google::Cloud::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 Google::Cloud#storage to control this behavior.
You can pass website settings for the bucket, including a block that defines CORS rule. See Bucket::Cors for details.
Before enabling uniform bucket-level access (see Bucket#uniform_bucket_level_access=) please review uniform bucket-level access.
- 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.
-
location (String) (defaults to: nil) — The location of the bucket. Optional.
If not passed, the default location, 'US', will be used.
If specifying a dual-region location, the
customPlacementConfig
property should be set in conjunction. See: Storage Locations. - logging_bucket (String) (defaults to: nil) — The destination bucket for the bucket's logs. For more information, see 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 . By default, the object prefix is the name of the bucket for which the logs are enabled. For more information, see Access Logs.
-
storage_class (Symbol, String) (defaults to: nil) — Defines how objects in the
bucket are stored and determines the SLA and the cost of storage.
Accepted values include
:standard
,:nearline
,:coldline
, and:archive
, as well as the equivalent strings returned by Bucket#storage_class. For more information, see Storage Classes. The default value is the:standard
storage class. -
versioning (Boolean) (defaults to: nil) — Whether 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 .
- 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 .
-
user_project (String) (defaults to: nil) — If this parameter is set to a project ID
other than the current project, and that project is authorized for
the currently authenticated service account, transit costs will be
billed to the given project. The default is
nil
. -
autoclass_enabled (Boolean) (defaults to: false) — The bucket's autoclass configuration.
Buckets can have either StorageClass OLM rules or Autoclass, but
not both. When Autoclass is enabled on a bucket, adding StorageClass
OLM rules will result in failure. For more information, see
Autoclass.
The value provided will be applied to all operations on the returned bucket instance and its files.
See also Bucket#requester_pays= and Bucket#requester_pays.
- enable_object_retention (Boolean) (defaults to: nil) — When set to true, object retention is enabled for this bucket.
- (bucket) — a block for configuring the bucket before it is created
- bucket (Bucket) — the bucket object to be configured
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.create_bucket "my-bucket"
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.create_bucket "my-bucket", enable_object_retention: true
Configure the bucket in a block:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.create_bucket "my-bucket" do |b| b.website_main = "index.html" b.website_404 = "not_found.html" b.requester_pays = true b.cors.add_rule ["http://example.org", "https://example.org"], "*", headers: ["X-My-Custom-Header"], max_age: 300 b.lifecycle.add_set_storage_class_rule "COLDLINE", age: 10 end
#create_hmac_key
def create_hmac_key(service_account_email, project_id: nil, user_project: nil) -> Google::Cloud::Storage::HmacKey
Creates a new HMAC key.
- service_account_email (String) — The email address of the service account. Used to create the HMAC key.
-
project_id (String) (defaults to: nil) — The project ID associated with
service_account_email
, ifservice_account_email
belongs to a project other than the currently authenticated project. Optional. If not provided, the project ID for the current project will be used. -
user_project (String) (defaults to: nil) — If this parameter is set to a project ID
other than the current project, and that project is authorized for
the currently authenticated service account, transit costs will be
billed to the given project. The default is
nil
.
#find_bucket
def find_bucket(bucket_name, skip_lookup: false, if_metageneration_match: nil, if_metageneration_not_match: nil, user_project: nil) -> Google::Cloud::Storage::Bucket, nil
Retrieves bucket by name.
- bucket_name (String) — Name of a bucket.
-
skip_lookup (Boolean) (defaults to: false) — Optionally create a Bucket object
without verifying the bucket resource exists on the Storage service.
Calls made on this object will raise errors if the bucket resource
does not exist. Default is
false
. - if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the bucket's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the bucket's current metageneration does not match the given value.
-
user_project (Boolean, String) (defaults to: nil) — If this parameter is set to
true
, transit costs for operations on the requested bucket or a file it contains will be billed to the current project for this client. (See #project for the ID of the current project.) If this parameter is set to a project ID other than the current project, and that project is authorized for the currently authenticated service account, transit costs will be billed to the given project. This parameter is required with requester pays-enabled buckets. The default isnil
.The value provided will be applied to all operations on the returned bucket instance and its files.
See also Bucket#requester_pays= and Bucket#requester_pays.
- (Google::Cloud::Storage::Bucket, nil) — Returns nil if bucket does not exist
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" puts bucket.name
With user_project
set to bill costs to the default project:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "other-project-bucket", user_project: true files = bucket.files # Billed to current project
With user_project
set to a project other than the default:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "other-project-bucket", user_project: "my-other-project" files = bucket.files # Billed to "my-other-project"
#find_buckets
def find_buckets(prefix: nil, token: nil, max: nil, user_project: nil) -> Array<Google::Cloud::Storage::Bucket>
Retrieves a list of buckets for the given project.
- 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.
-
user_project (Boolean, String) (defaults to: nil) — If this parameter is set to
true
, transit costs for operations on the enabled buckets or their files will be billed to the current project for this client. (See #project for the ID of the current project.) If this parameter is set to a project ID other than the current project, and that project is authorized for the currently authenticated service account, transit costs will be billed to the given project. This parameter is required with requester pays-enabled buckets. The default isnil
.The value provided will be applied to all operations on the returned bucket instances and their files.
See also Bucket#requester_pays= and Bucket#requester_pays.
- (Array<Google::Cloud::Storage::Bucket>) — (See Bucket::List)
require "google/cloud/storage" storage = Google::Cloud::Storage.new buckets = storage.buckets buckets.each do |bucket| puts bucket.name end
Retrieve buckets with names that begin with a given prefix:
require "google/cloud/storage" storage = Google::Cloud::Storage.new user_buckets = storage.buckets prefix: "user-" user_buckets.each do |bucket| puts bucket.name end
Retrieve all buckets: (See Bucket::List#all)
require "google/cloud/storage" storage = Google::Cloud::Storage.new buckets = storage.buckets buckets.all do |bucket| puts bucket.name end
#hmac_key
def hmac_key(access_id, project_id: nil, user_project: nil) -> Google::Cloud::Storage::HmacKey
Retrieves an HMAC key's metadata; the key's secret is not included in the representation.
-
project_id (String) (defaults to: nil) — The project ID associated with the
service_account_email
used to create the HMAC key, if the service account email belongs to a project other than the currently authenticated project. Optional. If not provided, the project ID for current project will be used. -
user_project (String) (defaults to: nil) — If this parameter is set to a project ID
other than the current project, and that project is authorized for
the currently authenticated service account, transit costs will be
billed to the given project. The default is
nil
.
#hmac_keys
def hmac_keys(service_account_email: nil, project_id: nil, show_deleted_keys: nil, token: nil, max: nil, user_project: nil) -> Google::Cloud::Storage::HmacKey
Retrieves a list of HMAC key metadata matching the criteria; the keys' secrets are not included.
- service_account_email (String) (defaults to: nil) — If present, only keys for the given service account are returned.
-
project_id (String) (defaults to: nil) — The project ID associated with the
service_account_email
used to create the HMAC keys, if the service account email belongs to a project other than the currently authenticated project. Optional. If not provided, the project ID for current project will be used. -
show_deleted_keys (Boolean) (defaults to: nil) — Whether to include keys in the
DELETED
state. The default value is false. - 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 keys to return.
-
user_project (String) (defaults to: nil) — If this parameter is set to a project ID
other than the current project, and that project is authorized for
the currently authenticated service account, transit costs will be
billed to the given project. The default is
nil
.
#project
def project() -> String
The Storage project connected to.
- (String)
require "google/cloud/storage" storage = Google::Cloud::Storage.new( project_id: "my-project", credentials: "/path/to/keyfile.json" ) storage.project_id #=> "my-project"
#project_id
def project_id() -> String
The Storage project connected to.
- (String)
require "google/cloud/storage" storage = Google::Cloud::Storage.new( project_id: "my-project", credentials: "/path/to/keyfile.json" ) storage.project_id #=> "my-project"
#service_account_email
def service_account_email() -> String
The Google Cloud Storage managed service account created for the project used to initialize the client library. (See also #project_id.)
- (String) — The service account email address.
#signed_url
def signed_url(bucket, path, method: "GET", expires: nil, content_type: nil, content_md5: nil, headers: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil, signer: nil, query: nil, scheme: "HTTPS", virtual_hosted_style: nil, bucket_bound_hostname: nil, version: nil) -> String
Generates a signed URL. See Signed URLs for more information.
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.
- bucket (String, nil) — Name of the bucket, or nil if URL for all buckets is desired.
- path (String) — Path to the file in Google Cloud Storage.
-
method (String) (defaults to: "GET") — The HTTP verb to be used with the signed URL.
Signed URLs can be used
with
GET
,HEAD
,PUT
, andDELETE
requests. Default isGET
. -
expires (Integer) (defaults to: nil) — The number of seconds until the URL expires.
If the
version
is:v2
, the default is 300 (5 minutes). If theversion
is:v4
, the default is 604800 (7 days). -
content_type (String) (defaults to: nil) — When provided, the client (browser) must
send this value in the HTTP header. e.g.
text/plain
. This param is not used if theversion
is:v4
. -
content_md5 (String) (defaults to: nil) — 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. This
param is not used if the
version
is:v4
. -
headers (Hash) (defaults to: nil) — Google extension headers (custom HTTP headers
that begin with
x-goog-
) that must be included in requests that use the signed URL. - issuer (String) (defaults to: nil) — Service Account's Client Email.
- client_email (String) (defaults to: nil) — Service Account's Client Email.
- signing_key (OpenSSL::PKey::RSA, String, Proc) (defaults to: nil) — Service Account's Private Key or a Proc that accepts a single String parameter and returns a RSA SHA256 signature using a valid Google Service Account Private Key.
- private_key (OpenSSL::PKey::RSA, String, Proc) (defaults to: nil) — Service Account's Private Key or a Proc that accepts a single String parameter and returns a RSA SHA256 signature using a valid Google Service Account Private Key.
-
signer (OpenSSL::PKey::RSA, String, Proc) (defaults to: nil) — Service Account's
Private Key or a Proc that accepts a single String parameter and returns a
RSA SHA256 signature using a valid Google Service Account Private Key.
When using this method in environments such as GAE Flexible Environment, GKE, or Cloud Functions where the private key is unavailable, it may be necessary to provide a Proc (or lambda) via the signer parameter. This Proc should return a signature created using a RPC call to the Service Account Credentials signBlob method as shown in the example below.
-
query (Hash) (defaults to: nil) — Query string parameters to include in the signed
URL. The given parameters are not verified by the signature.
Parameters such as
response-content-disposition
andresponse-content-type
can alter the behavior of the response when using the URL, but only when the file resource is missing the corresponding values. (These values can be permanently set using File#content_disposition= and File#content_type=.) -
scheme (String) (defaults to: "HTTPS") — The URL scheme. The default value is
HTTPS
. -
virtual_hosted_style (Boolean) (defaults to: nil) — Whether to use a virtual hosted-style
hostname, which adds the bucket into the host portion of the URI rather
than the path, e.g.
https://mybucket.storage.googleapis.com/...
. For V4 signing, this also sets thehost
header in the canonicalized extension headers to the virtual hosted-style host, unless that header is supplied via theheaders
param. The default value offalse
uses the form ofhttps://storage.googleapis.com/mybucket
. -
bucket_bound_hostname (String) (defaults to: nil) — Use a bucket-bound hostname, which
replaces the
storage.googleapis.com
host with the name of aCNAME
bucket, e.g. a bucket namedgcs-subdomain.my.domain.tld
, or a Google Cloud Load Balancer which routes to a bucket you own, e.g.my-load-balancer-domain.tld
. -
version (Symbol, String) (defaults to: nil) — The version of the signed credential
to create. Must be one of
:v2
or:v4
. The default value is:v2
.
- (String) — The signed URL.
- (SignedUrlUnavailable) — If the service account credentials are missing. Service account credentials are acquired by following the steps in Service Account Authentication.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" shared_url = storage.signed_url bucket_name, file_path
Using the expires
and version
options:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" shared_url = storage.signed_url bucket_name, file_path, expires: 300, # 5 minutes from now version: :v4
Using the issuer
and signing_key
options:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" issuer_email = "service-account@gcloud.com" key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..." shared_url = storage.signed_url bucket_name, file_path, issuer: issuer_email, signing_key: key
Using Cloud IAMCredentials signBlob to create the signature:
require "google/cloud/storage" require "google/apis/iamcredentials_v1" require "googleauth" # Issuer is the service account email that the Signed URL will be signed with # and any permission granted in the Signed URL must be granted to the # Google Service Account. issuer = "service-account@project-id.iam.gserviceaccount.com" # Create a lambda that accepts the string_to_sign signer = lambda do |string_to_sign| IAMCredentials = Google::Apis::IamcredentialsV1 iam_client = IAMCredentials::IAMCredentialsService.new # Get the environment configured authorization scopes = ["https://www.googleapis.com/auth/iam"] iam_client.authorization = Google::Auth.get_application_default scopes request = Google::Apis::IamcredentialsV1::SignBlobRequest.new( payload: string_to_sign ) resource = "projects/-/serviceAccounts/#{issuer}" response = iam_client.sign_service_account_blob resource, request response.signed_blob end storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" url = storage.signed_url bucket_name, file_path, method: "GET", issuer: issuer, signer: signer
Using the headers
option:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" shared_url = storage.signed_url bucket_name, file_path, headers: { "x-goog-acl" => "private", "x-goog-meta-foo" => "bar,baz" }
Generating a signed URL for resumable upload:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket_name = "my-todo-app" file_path = "avatars/heidi/400x400.png" url = storage.signed_url bucket_name, file_path, method: "POST", content_type: "image/png", headers: { "x-goog-resumable" => "start" } # Send the `x-goog-resumable:start` header and the content type # with the resumable upload POST request.
#universe_domain
def universe_domain() -> String
The universe domain the client is connected to
- (String)