The File::Acl instance used to control access to the file.

A file 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 file 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"
file = bucket.file "avatars/heidi/400x400.png"

email = "heidi@example.net"
file.acl.add_reader "user-#{email}"

Access to a file 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"
file = bucket.file "avatars/heidi/400x400.png"

email = "authors@example.net"
file.acl.add_reader "group-#{email}"

Access to a file can also be granted to a predefined list of permissions:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"

file.acl.public!

The name of the bucket containing this file.

Copy the file to a new location.

Parameters¶ ↑

dest_bucket_or_path

Either the bucket to copy the file to, or the path to copy the file to in the current bucket. (String)

dest_path

If a bucket was provided in the first parameter, this contains the path to copy the file to in the given bucket. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:acl]

A predefined set of access controls to apply to new 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¶ ↑

File object

Examples¶ ↑

The file can also be copied to a new path in the current bucket:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.copy "path/to/destination/file.ext"

The file can also be copied to a different bucket:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.copy "new-destination-bucket",
          "path/to/destination/file.ext"

CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64.

Permenently deletes the file.

Returns¶ ↑

true if the file was deleted.

Example¶ ↑

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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

Download the file's contents to a local file.

Parameters¶ ↑

path

The path on the local file system to write the data to. The path provided must be writable. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:verify]

The verification algoruthm used to ensure the downloaded file contents are correct. Default is :md5. (Symbol)

Acceptable values are:

• md5 - Verify file content match using the MD5 hash.

• crc32c - Verify file content match using the CRC32c hash.

• all - Perform all available file content verification.

• none - Don't perform file content verification.

Returns¶ ↑

::File object on the local file system

Examples¶ ↑

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.download "path/to/downloaded/file.ext"

The download is verified by calculating the MD5 digest. The CRC32c digest can be used by passing :crc32c.

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.download "path/to/downloaded/file.ext", verify: :crc32c

Both the MD5 and CRC32c digest can be used by passing :all.

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.download "path/to/downloaded/file.ext", verify: :all

The download verification can be disabled by passing :none

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.download "path/to/downloaded/file.ext", verify: :none

HTTP 1.1 Entity tag for the file.

The content generation of this file. Used for object versioning.

The ID of the file.

The kind of item this is. For files, this is always storage#object.

MD5 hash of the data; encoded using base64.

The version of the metadata for this file at this generation. Used for preconditions and for detecting changes in metadata. A metageneration number is only meaningful in the context of a particular generation of a particular file.

The name of this file.

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. See the Access Control Signed URLs guide for more.

Generating a URL requires service account credentials, either by connecting with a service account when calling Gcloud#storage, or by passing in the service account issuer and signing_key values. A SignedUrlUnavailable is raised if the service account credentials are missing. Service account credentials are acquired by following the steps in {Service Account Authentication}[ cloud.google.com/storage/docs/authentication#service_accounts].

Parameters¶ ↑

options

An optional Hash for controlling additional behavior. (Hash)

options[:method]

The HTTP verb to be used with the signed URL. Signed URLs can be used with GET, HEAD, PUT, and DELETE requests. Default is GET. (String)

options[:expires]

The number of seconds until the URL expires. Default is 300/5 minutes. (Integer)

options[:content_type]

When provided, the client (browser) must send this value in the HTTP header. e.g. text/plain (String)

options[:content_md5]

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. (String)

options[:issuer]

Service Account's Client Email. (String)

options[:signing_key]

Service Account's Private Key. (OpenSSL::PKey::RSA or String)

Examples¶ ↑

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"
shared_url = file.signed_url

Any of the option parameters may be specified:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"
shared_url = file.signed_url method: "GET",
                             expires: 300 # 5 minutes from now

Signed URLs require service account credentials. If you are not authenticated with a service account, those credentials can be passed in using the issuer and signing_key options. 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.

require "gcloud/storage"

storage = Gcloud.storage

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"
key = OpenSSL::PKey::RSA.new "-----BEGIN PRIVATE KEY-----\n..."
shared_url = file.signed_url issuer: "service-account@gcloud.com",
                             signing_key: key

Content-Length of the data in bytes.

The creation or modification time of the file. For buckets with versioning enabled, changing an object's metadata does not change this property.

The url to the file.