Class: Google::Cloud::Storage::File

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/storage/file.rb,
lib/google/cloud/storage/file/acl.rb,
lib/google/cloud/storage/file/list.rb,
lib/google/cloud/storage/file/verifier.rb

Overview

File

Represents a File (Object) that belongs to a Bucket. Files (Objects) are the individual pieces of data that you store in Google Cloud Storage. A file can be up to 5 TB in size. Files have two components: data and metadata. The data component is the data from an external file or other data source that you want to store in Google Cloud Storage. The metadata component is a collection of name-value pairs that describe various qualities of the data.

Examples:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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

See Also:

Direct Known Subclasses

Updater

Defined Under Namespace

Classes: Acl, List, Updater

Instance Method Summary collapse

Instance Method Details

#acl ⇒ Object

The 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.

Examples:

Grant access to a user by prepending "user-" to an email:

require "google/cloud"

gcloud = Google::Cloud.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}"

Grant access to a group by prepending "group-" to an email:

require "google/cloud"

gcloud = Google::Cloud.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}"

Or, grant access via a predefined permissions list:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

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

file.acl.public!

See Also:



662
663
664
 
# File 'lib/google/cloud/storage/file.rb', line 662

def acl
  @acl ||= File::Acl.new self
end

#api_url ⇒ Object

A URL that can be used to access the file using the REST API.



109
110
111
 
# File 'lib/google/cloud/storage/file.rb', line 109

def api_url
  @gapi.self_link
end

#bucket ⇒ Object

The name of the Bucket containing this file.



87
88
89
 
# File 'lib/google/cloud/storage/file.rb', line 87

def bucket
  @gapi.bucket
end

#cache_control ⇒ Object

The Cache-Control directive for the file data.



162
163
164
 
# File 'lib/google/cloud/storage/file.rb', line 162

def cache_control
  @gapi.cache_control
end

#cache_control=(cache_control) ⇒ Object

Updates the Cache-Control directive for the file data.



170
171
172
173
 
# File 'lib/google/cloud/storage/file.rb', line 170

def cache_control= cache_control
  @gapi.cache_control = cache_control
  patch_gapi! :cache_control
end

#content_disposition ⇒ Object

The Content-Disposition of the file data.



178
179
180
 
# File 'lib/google/cloud/storage/file.rb', line 178

def content_disposition
  @gapi.content_disposition
end

#content_disposition=(content_disposition) ⇒ Object

Updates the Content-Disposition of the file data.



185
186
187
188
 
# File 'lib/google/cloud/storage/file.rb', line 185

def content_disposition= content_disposition
  @gapi.content_disposition = content_disposition
  patch_gapi! :content_disposition
end

#content_encoding ⇒ Object

The Content-Encoding of the file data.



194
195
196
 
# File 'lib/google/cloud/storage/file.rb', line 194

def content_encoding
  @gapi.content_encoding
end

#content_encoding=(content_encoding) ⇒ Object

Updates the Content-Encoding of the file data.



202
203
204
205
 
# File 'lib/google/cloud/storage/file.rb', line 202

def content_encoding= content_encoding
  @gapi.content_encoding = content_encoding
  patch_gapi! :content_encoding
end

#content_language ⇒ Object

The Content-Language of the file data.



210
211
212
 
# File 'lib/google/cloud/storage/file.rb', line 210

def content_language
  @gapi.content_language
end

#content_language=(content_language) ⇒ Object

Updates the Content-Language of the file data.



217
218
219
220
 
# File 'lib/google/cloud/storage/file.rb', line 217

def content_language= content_language
  @gapi.content_language = content_language
  patch_gapi! :content_language
end

#content_type ⇒ Object

The Content-Type of the file data.



225
226
227
 
# File 'lib/google/cloud/storage/file.rb', line 225

def content_type
  @gapi.content_type
end

#content_type=(content_type) ⇒ Object

Updates the Content-Type of the file data.



233
234
235
236
 
# File 'lib/google/cloud/storage/file.rb', line 233

def content_type= content_type
  @gapi.content_type = content_type
  patch_gapi! :content_type
end

#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil, encryption_key_sha256: nil) ⇒ Google::Cloud::Storage::File

Copy the file to a new location.

If a customer-supplied encryption key was used with Bucket#create_file, the encryption_key and encryption_key_sha256 options must be provided.

Examples:

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

require "google/cloud"

gcloud = Google::Cloud.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 "google/cloud"

gcloud = Google::Cloud.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"

The file can also be copied by specifying a generation:

file.copy "copy/of/previous/generation/file.ext",
          generation: 123456

Parameters:

  • dest_bucket_or_path (String) —

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

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

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

  • acl (String) —

    A predefined set of access controls to apply to new file.

    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.
  • generation (Integer) —

    Select a specific revision of the file to copy. The default is the latest version.

  • encryption_key (String) —

    Optional. The customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to Bucket#create_file. Must be provided if encryption_key_sha256 is provided.

  • encryption_key_sha256 (String) —

    Optional. The SHA256 hash of the customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to Bucket#create_file. Must be provided if encryption_key is provided.

Returns:



462
463
464
465
466
467
468
469
470
471
472
473
474
 
# File 'lib/google/cloud/storage/file.rb', line 462

def copy dest_bucket_or_path, dest_path = nil, acl: nil,
         generation: nil, encryption_key: nil,
         encryption_key_sha256: nil
  ensure_service!
  options = { acl: acl, generation: generation,
              key: encryption_key, key_sha256: encryption_key_sha256 }
  dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
                                                  dest_path, options

  gapi = service.copy_file bucket, name,
                           dest_bucket, dest_path, options
  File.from_gapi gapi, service
end

#crc32c ⇒ Object

The CRC32c checksum of the data, as described in RFC 4960, Appendix B. Encoded using base64 in big-endian byte order.



149
150
151
 
# File 'lib/google/cloud/storage/file.rb', line 149

def crc32c
  @gapi.crc32c
end

#created_at ⇒ Object

Creation time of the file.



127
128
129
 
# File 'lib/google/cloud/storage/file.rb', line 127

def created_at
  @gapi.time_created
end

#delete ⇒ Boolean

Permanently deletes the file.

Examples:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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

Returns:

  • (Boolean) —

    Returns true if the file was deleted.



492
493
494
495
496
 
# File 'lib/google/cloud/storage/file.rb', line 492

def delete
  ensure_service!
  service.delete_file bucket, name
  true
end

#download(path, verify: :md5, encryption_key: nil, encryption_key_sha256: nil) ⇒ File

Download the file's contents to a local file.

By default, the download is verified by calculating the MD5 digest.

If a customer-supplied encryption key was used with Bucket#create_file, the encryption_key and encryption_key_sha256 options must be provided.

Examples:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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

Use the CRC32c digest by passing :crc32c.

require "google/cloud"

gcloud = Google::Cloud.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

Use the MD5 and CRC32c digests by passing :all.

require "google/cloud"

gcloud = Google::Cloud.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

Disable the download verification by passing :none.

require "google/cloud"

gcloud = Google::Cloud.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

Parameters:

  • path (String) —

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

  • verify (Symbol) —

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

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

    Optional. The customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to Bucket#create_file. Must be provided if encryption_key_sha256 is provided.

  • encryption_key_sha256 (String) —

    Optional. The SHA256 hash of the customer-supplied, AES-256 encryption key used to encrypt the file, if one was provided to Bucket#create_file. Must be provided if encryption_key is provided.

Returns:

  • (File) —

    Returns a ::File object on the local file system



382
383
384
385
386
387
388
389
 
# File 'lib/google/cloud/storage/file.rb', line 382

def download path, verify: :md5, encryption_key: nil,
             encryption_key_sha256: nil
  ensure_service!
  service.download_file \
    bucket, name, path,
    key: encryption_key, key_sha256: encryption_key_sha256
  verify_file! ::File.new(path), verify
end

#encryption_key_sha256 ⇒ Object

An RFC 4648 Base64-encoded string of the SHA256 hash of the customer-supplied encryption key. You can use this SHA256 hash to uniquely identify the AES-256 encryption key required to decrypt this file.



264
265
266
267
 
# File 'lib/google/cloud/storage/file.rb', line 264

def encryption_key_sha256
  return nil unless @gapi.customer_encryption
  Base64.decode64 @gapi.customer_encryption.key_sha256
end

#etag ⇒ Object

HTTP 1.1 Entity tag for the file.



155
156
157
 
# File 'lib/google/cloud/storage/file.rb', line 155

def etag
  @gapi.etag
end

#generation ⇒ Object

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



94
95
96
 
# File 'lib/google/cloud/storage/file.rb', line 94

def generation
  @gapi.generation
end

#id ⇒ Object

The ID of the file.



75
76
77
 
# File 'lib/google/cloud/storage/file.rb', line 75

def id
  @gapi.id
end

#kind ⇒ Object

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



69
70
71
 
# File 'lib/google/cloud/storage/file.rb', line 69

def kind
  @gapi.kind
end

#md5 ⇒ Object

MD5 hash of the data; encoded using base64.



141
142
143
 
# File 'lib/google/cloud/storage/file.rb', line 141

def md5
  @gapi.md5_hash
end

#media_url ⇒ Object

A URL that can be used to download the file using the REST API.



115
116
117
 
# File 'lib/google/cloud/storage/file.rb', line 115

def media_url
  @gapi.media_link
end

#metadata ⇒ Object

A hash of custom, user-provided web-safe keys and arbitrary string values that will returned with requests for the file as "x-goog-meta-" response headers.



242
243
244
245
246
 
# File 'lib/google/cloud/storage/file.rb', line 242

def metadata
  m = @gapi.metadata
  m = m.to_h if m.respond_to? :to_h
  m.dup.freeze
end

#metadata=(metadata) ⇒ Object

Updates the hash of custom, user-provided web-safe keys and arbitrary string values that will returned with requests for the file as "x-goog-meta-" response headers.



252
253
254
255
 
# File 'lib/google/cloud/storage/file.rb', line 252

def metadata= metadata
  @gapi.metadata = metadata
  patch_gapi! :metadata
end

#metageneration ⇒ Object

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.



103
104
105
 
# File 'lib/google/cloud/storage/file.rb', line 103

def metageneration
  @gapi.metageneration
end

#name ⇒ Object

The name of this file.



81
82
83
 
# File 'lib/google/cloud/storage/file.rb', line 81

def name
  @gapi.name
end

#public_url(protocol: :https) ⇒ Object Also known as: url

Public URL to access the file. If the file is not public, requests to the URL will return an error. (See Google::Cloud::Storage::File::Acl#public! and Bucket::DefaultAcl#public!) To share a file that is not public see #signed_url.

Examples:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

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

Generate the URL with a protocol other than HTTPS:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

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

Parameters:

  • protocol (String) —

    The protocol to use for the URL. Default is HTTPS.

See Also:



530
531
532
 
# File 'lib/google/cloud/storage/file.rb', line 530

def public_url protocol: :https
  "#{protocol}://storage.googleapis.com/#{bucket}/#{name}"
end

#reload! ⇒ Object Also known as: refresh!

Reloads the file with current data from the Storage service.



668
669
670
671
 
# File 'lib/google/cloud/storage/file.rb', line 668

def reload!
  ensure_service!
  @gapi = service.get_file bucket, name
end

#signed_url(method: nil, expires: nil, content_type: nil, content_md5: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil) ⇒ Object

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.

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.

Examples:

require "google/cloud"

gcloud = Google::Cloud.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 "google/cloud"

gcloud = Google::Cloud.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

Using the issuer and signing_key options:

require "google/cloud/storage"

storage = Google::Cloud.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

Parameters:

  • method (String) —

    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.

  • expires (Integer) —

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

  • content_type (String) —

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

  • content_md5 (String) —

    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.

  • issuer (String) —

    Service Account's Client Email.

  • client_email (String) —

    Service Account's Client Email.

  • signing_key (OpenSSL::PKey::RSA, String) —

    Service Account's Private Key.

  • private_key (OpenSSL::PKey::RSA, String) —

    Service Account's Private Key.

See Also:



605
606
607
608
609
610
611
612
613
614
615
 
# File 'lib/google/cloud/storage/file.rb', line 605

def signed_url method: nil, expires: nil, content_type: nil,
               content_md5: nil, issuer: nil, client_email: nil,
               signing_key: nil, private_key: nil
  ensure_service!
  options = { method: method, expires: expires,
              content_type: content_type, content_md5: content_md5,
              issuer: issuer, client_email: client_email,
              signing_key: signing_key, private_key: private_key }
  signer = File::Signer.new self
  signer.signed_url options
end

#size ⇒ Object

Content-Length of the data in bytes.



121
122
123
 
# File 'lib/google/cloud/storage/file.rb', line 121

def size
  @gapi.size.to_i if @gapi.size
end

#update {|file| ... } ⇒ Object

Updates the file with changes made in the given block in a single PATCH request. The following attributes may be set: #cache_control=, #content_disposition=, #content_encoding=, #content_language=, #content_type=, and #metadata=. The #metadata hash accessible in the block is completely mutable and will be included in the request.

Examples:

require "google/cloud"

gcloud = Google::Cloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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

file.update do |f|
  f.cache_control = "private, max-age=0, no-cache"
  f.content_disposition = "inline; filename=filename.ext"
  f.content_encoding = "deflate"
  f.content_language = "de"
  f.content_type = "application/json"
  f.metadata["player"] = "Bob"
  f.metadata["score"] = "10"
end

Yields:

  • (file) —

    a block yielding a delegate object for updating the file



298
299
300
301
302
303
 
# File 'lib/google/cloud/storage/file.rb', line 298

def update
  updater = Updater.new gapi
  yield updater
  updater.check_for_changed_metadata!
  patch_gapi! updater.updates unless updater.updates.empty?
end

#updated_at ⇒ Object

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



135
136
137
 
# File 'lib/google/cloud/storage/file.rb', line 135

def updated_at
  @gapi.updated
end