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/signer.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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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

file.acl.public!

See Also:



772
773
774
 
# File 'lib/google/cloud/storage/file.rb', line 772

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.



111
112
113
 
# File 'lib/google/cloud/storage/file.rb', line 111

def api_url
  @gapi.self_link
end

#bucket ⇒ Object

The name of the Bucket containing this file.



89
90
91
 
# File 'lib/google/cloud/storage/file.rb', line 89

def bucket
  @gapi.bucket
end

#cache_control ⇒ Object

The Cache-Control directive for the file data.



164
165
166
 
# File 'lib/google/cloud/storage/file.rb', line 164

def cache_control
  @gapi.cache_control
end

#cache_control=(cache_control) ⇒ Object

Updates the Cache-Control directive for the file data.



172
173
174
175
 
# File 'lib/google/cloud/storage/file.rb', line 172

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.



180
181
182
 
# File 'lib/google/cloud/storage/file.rb', line 180

def content_disposition
  @gapi.content_disposition
end

#content_disposition=(content_disposition) ⇒ Object

Updates the Content-Disposition of the file data.



187
188
189
190
 
# File 'lib/google/cloud/storage/file.rb', line 187

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.



196
197
198
 
# File 'lib/google/cloud/storage/file.rb', line 196

def content_encoding
  @gapi.content_encoding
end

#content_encoding=(content_encoding) ⇒ Object

Updates the Content-Encoding of the file data.



204
205
206
207
 
# File 'lib/google/cloud/storage/file.rb', line 204

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.



212
213
214
 
# File 'lib/google/cloud/storage/file.rb', line 212

def content_language
  @gapi.content_language
end

#content_language=(content_language) ⇒ Object

Updates the Content-Language of the file data.



219
220
221
222
 
# File 'lib/google/cloud/storage/file.rb', line 219

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.



227
228
229
 
# File 'lib/google/cloud/storage/file.rb', line 227

def content_type
  @gapi.content_type
end

#content_type=(content_type) ⇒ Object

Updates the Content-Type of the file data.



235
236
237
238
 
# File 'lib/google/cloud/storage/file.rb', line 235

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) ⇒ 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 option must be provided.

Examples:

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

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
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.

Returns:



507
508
509
510
511
512
513
514
515
516
517
518
 
# File 'lib/google/cloud/storage/file.rb', line 507

def copy dest_bucket_or_path, dest_path = nil, acl: nil,
         generation: nil, encryption_key: nil
  ensure_service!
  options = { acl: acl, generation: generation,
              key: encryption_key }
  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.



151
152
153
 
# File 'lib/google/cloud/storage/file.rb', line 151

def crc32c
  @gapi.crc32c
end

#created_at ⇒ Object

Creation time of the file.



129
130
131
 
# File 'lib/google/cloud/storage/file.rb', line 129

def created_at
  @gapi.time_created
end

#delete ⇒ Boolean

Permanently deletes the file.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Returns:

  • (Boolean) —

    Returns true if the file was deleted.



592
593
594
595
596
 
# File 'lib/google/cloud/storage/file.rb', line 592

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

#download(path = nil, verify: :md5, encryption_key: nil) ⇒ IO

Download the file's contents to a local file or an IO instance.

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 option must be provided.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Download to an in-memory StringIO object.

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
downloaded = file.download
downloaded.rewind
downloaded.read #=> "Hello world!"

Parameters:

  • path (String, IO) (defaults to: nil) —

    The path on the local file system to write the data to. The path provided must be writable. Can also be an IO object, or IO-ish object like StringIO. If an IO object, the object will be written to, not the filesystem. If omitted, a new StringIO instance will be written to and returned. Optional.

  • verify (Symbol) —

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

Returns:

  • (IO) —

    Returns an IO object representing the file data. This will ordinarily be a ::File object referencing the local file system. However, if the argument to path is nil, a StringIO instance will be returned. If the argument to path is an IO object, then that object will be returned.



422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/google/cloud/storage/file.rb', line 422

def download path = nil, verify: :md5, encryption_key: nil
  ensure_service!
  if path.nil?
    path = StringIO.new
    path.set_encoding "ASCII-8BIT"
  end
  file = service.download_file \
    bucket, name, path,
    key: encryption_key
  # FIX: downloading with encryption key will return nil
  file ||= ::File.new(path)
  verify_file! file, 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.



266
267
268
269
 
# File 'lib/google/cloud/storage/file.rb', line 266

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.



157
158
159
 
# File 'lib/google/cloud/storage/file.rb', line 157

def etag
  @gapi.etag
end

#generation ⇒ Object

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



96
97
98
 
# File 'lib/google/cloud/storage/file.rb', line 96

def generation
  @gapi.generation
end

#id ⇒ Object

The ID of the file.



77
78
79
 
# File 'lib/google/cloud/storage/file.rb', line 77

def id
  @gapi.id
end

#kind ⇒ Object

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



71
72
73
 
# File 'lib/google/cloud/storage/file.rb', line 71

def kind
  @gapi.kind
end

#md5 ⇒ Object

MD5 hash of the data; encoded using base64.



143
144
145
 
# File 'lib/google/cloud/storage/file.rb', line 143

def md5
  @gapi.md5_hash
end

#media_url ⇒ Object

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



117
118
119
 
# File 'lib/google/cloud/storage/file.rb', line 117

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.



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

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.



254
255
256
257
 
# File 'lib/google/cloud/storage/file.rb', line 254

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.



105
106
107
 
# File 'lib/google/cloud/storage/file.rb', line 105

def metageneration
  @gapi.metageneration
end

#name ⇒ Object

The name of this file.



83
84
85
 
# File 'lib/google/cloud/storage/file.rb', line 83

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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

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:



628
629
630
 
# File 'lib/google/cloud/storage/file.rb', line 628

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.



778
779
780
781
 
# File 'lib/google/cloud/storage/file.rb', line 778

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

#rotate(encryption_key: nil, new_encryption_key: nil) ⇒ Google::Cloud::Storage::File

Rewrites the file to the same #bucket and #name with a new customer-supplied encryption key.

If a new key is provided to this method, the new key must be used to subsequently download or copy the file. You must securely manage your keys and ensure that they are not lost. Also, please note that file metadata is not encrypted, with the exception of the CRC32C checksum and MD5 hash. The names of files and buckets are also not encrypted, and you can read or update the metadata of an encrypted file without providing the encryption key.

Examples:

The file will be rewritten with a new encryption key:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new
bucket = storage.bucket "my-bucket"

# Old key was stored securely for later use.
old_key = "y\x03\"\x0E\xB6\xD3\x9B\x0E\xAB*\x19\xFAv\xDEY\xBEI..."

file = bucket.file "path/to/my-file.ext", encryption_key: old_key

# Key generation shown for example purposes only. Write your own.
cipher = OpenSSL::Cipher.new "aes-256-cfb"
cipher.encrypt
new_key = cipher.random_key

file.rotate encryption_key: old_key, new_encryption_key: new_key

Parameters:

  • encryption_key (String, nil) —

    Optional. The last customer-supplied, AES-256 encryption key used to encrypt the file, if one was used.

  • new_encryption_key (String, nil) —

    Optional. The new customer-supplied, AES-256 encryption key with which to encrypt the file. If nil, the rewritten file will be encrypted using the default server-side encryption, not customer-supplied encryption keys.

Returns:

See Also:



565
566
567
568
569
570
571
572
573
574
575
 
# File 'lib/google/cloud/storage/file.rb', line 565

def rotate encryption_key: nil, new_encryption_key: nil
  ensure_service!
  options = { source_key: encryption_key,
              destination_key: new_encryption_key }
  gapi = service.rewrite_file bucket, name, bucket, name, options
  until gapi.done
    options[:token] = gapi.rewrite_token
    gapi = service.rewrite_file bucket, name, bucket, name, options
  end
  File.from_gapi gapi.resource, service
end

#signed_url(method: nil, expires: nil, content_type: nil, content_md5: nil, headers: 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/storage"

storage = Google::Cloud::Storage.new

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/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"
shared_url = file.signed_url method: "PUT",
                             content_type: "image/png",
                             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

Using the headers option:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"
file = bucket.file "avatars/heidi/400x400.png"
shared_url = file.signed_url method: "GET",
                             headers: {
                               "x-goog-acl" => "public-read",
                               "x-goog-meta-foo" => "bar,baz"
                             }

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.

  • headers (Hash) —

    Google extension headers (custom HTTP headers that begin with x-goog-) that must be included in requests that use the signed URL.

  • 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:



718
719
720
721
722
723
724
725
726
727
728
 
# File 'lib/google/cloud/storage/file.rb', line 718

def signed_url method: nil, expires: nil, content_type: nil,
               content_md5: nil, headers: nil, issuer: nil,
               client_email: nil, signing_key: nil, private_key: nil
  ensure_service!
  options = { method: method, expires: expires, headers: headers,
              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.from_file self
  signer.signed_url options
end

#size ⇒ Object

Content-Length of the data in bytes.



123
124
125
 
# File 'lib/google/cloud/storage/file.rb', line 123

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

#storage_class ⇒ Object

The file's storage class. This defines how the file is stored and determines the SLA and the cost of storage. For more information, see Storage Classes and Per-Object Storage Class.



278
279
280
 
# File 'lib/google/cloud/storage/file.rb', line 278

def storage_class
  @gapi.storage_class
end

#storage_class=(storage_class) ⇒ Object

Updates how the file is stored and determines the SLA and the cost of storage. Values include :multi_regional, :regional, :nearline, :coldline, :standard, and :dra (Durable Reduced Availability), as well as the strings returned by #storage_class or Bucket#storage_class. For more information, see Storage Classes and Per-Object Storage Class. The default value is the default storage class for the bucket. See Bucket#storage_class.

Parameters:

  • storage_class (Symbol, String) —

    Storage class of the file.



294
295
296
297
298
 
# File 'lib/google/cloud/storage/file.rb', line 294

def storage_class= storage_class
  resp = service.update_file_storage_class \
    bucket, name, storage_class_for(storage_class)
  @gapi = resp.resource
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/storage"

storage = Google::Cloud::Storage.new

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



328
329
330
331
332
333
 
# File 'lib/google/cloud/storage/file.rb', line 328

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.



137
138
139
 
# File 'lib/google/cloud/storage/file.rb', line 137

def updated_at
  @gapi.updated
end