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"

Download a public file with an unauthenticated client:

require "google/cloud/storage"

storage = Google::Cloud::Storage.anonymous

bucket = storage.bucket "public-bucket", skip_lookup: true
file = bucket.file "path/to/public-file.ext", skip_lookup: true

downloaded = file.download
downloaded.rewind
downloaded.read #=> "Hello world!"

See Also:

Direct Known Subclasses

Updater

Defined Under Namespace

Classes: Acl, List, Updater

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#user_project ⇒ Object

If this attribute is set to true, transit costs for operations on the file will be billed to the current project for this client. (See Project#project for the ID of the current project.) If this attribute is set to a project ID, and that project is authorized for the currently authenticated service account, transit costs will be billed to that project. This attribute is required with requester pays-enabled buckets. The default is nil.

In general, this attribute should be set when first retrieving the owning bucket by providing the user_project option to Project#bucket or Project#buckets.

See also Bucket#requester_pays= and Bucket#requester_pays.

Examples:

Setting a non-default project:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "other-project-bucket", user_project: true
file = bucket.file "path/to/file.ext" # Billed to current project
file.user_project = "my-other-project"
file.download "file.ext" # Billed to "my-other-project"


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

def user_project
  @user_project
end

Instance Method Details

#acl ⇒ File::Acl

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 = "[email protected]"
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 = "[email protected]"
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!

Returns:

See Also:



1279
1280
1281
 
# File 'lib/google/cloud/storage/file.rb', line 1279

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

#api_url ⇒ String

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

Returns:

  • (String) 


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

def api_url
  @gapi.self_link
end

#bucket ⇒ String

The name of the Bucket containing this file.

Returns:

  • (String) 


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

def bucket
  @gapi.bucket
end

#cache_control ⇒ String

The Cache-Control directive for the file data. If omitted, and the file is accessible to all anonymous users, the default will be public, max-age=3600.

Returns:

  • (String) 


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

def cache_control
  @gapi.cache_control
end

#cache_control=(cache_control) ⇒ Object

Updates the Cache-Control directive for the file data. If omitted, and the file is accessible to all anonymous users, the default will be public, max-age=3600.

Parameters:

  • cache_control (String) —

    The Cache-Control directive.



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

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

#content_disposition ⇒ String

The Content-Disposition of the file data.

Returns:

  • (String) 


275
276
277
 
# File 'lib/google/cloud/storage/file.rb', line 275

def content_disposition
  @gapi.content_disposition
end

#content_disposition=(content_disposition) ⇒ Object

Updates the Content-Disposition of the file data.

Parameters:

  • content_disposition (String) —

    The Content-Disposition of the file.



286
287
288
289
 
# File 'lib/google/cloud/storage/file.rb', line 286

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

#content_encoding ⇒ String

The Content-Encoding of the file data.

Returns:

  • (String) 


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

def content_encoding
  @gapi.content_encoding
end

#content_encoding=(content_encoding) ⇒ Object

Updates the Content-Encoding of the file data.

Parameters:

  • content_encoding (String) —

    The Content-Encoding of the file.



309
310
311
312
 
# File 'lib/google/cloud/storage/file.rb', line 309

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

#content_language ⇒ String

The Content-Language of the file data.

Returns:

  • (String) 


320
321
322
 
# File 'lib/google/cloud/storage/file.rb', line 320

def content_language
  @gapi.content_language
end

#content_language=(content_language) ⇒ Object

Updates the Content-Language of the file data.

Parameters:

  • content_language (String) —

    The Content-Language of the file.



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

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

#content_type ⇒ String

The Content-Type of the file data.

Returns:

  • (String) 


341
342
343
 
# File 'lib/google/cloud/storage/file.rb', line 341

def content_type
  @gapi.content_type
end

#content_type=(content_type) ⇒ Object

Updates the Content-Type of the file data.

Parameters:

  • content_type (String) —

    The Content-Type of the file.



352
353
354
355
 
# File 'lib/google/cloud/storage/file.rb', line 352

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

#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil) {|file| ... } ⇒ 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

The file can be modified during copying:

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" do |f|
  f.metadata["copied_from"] = "#{file.bucket}/#{file.name}"
end

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) (defaults to: nil) —

    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) (defaults to: nil) —

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

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

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

Yields:

  • (file) —

    a block yielding a delegate object for updating

Returns:



783
784
785
786
787
788
789
790
791
 
# File 'lib/google/cloud/storage/file.rb', line 783

def copy dest_bucket_or_path, dest_path = nil,
         acl: nil, generation: nil, encryption_key: nil
  rewrite dest_bucket_or_path, dest_path,
          acl: acl, generation: generation,
          encryption_key: encryption_key,
          new_encryption_key: encryption_key do |updater|
    yield updater if block_given?
  end
end

#crc32c ⇒ String

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

Returns:

  • (String) 


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

def crc32c
  @gapi.crc32c
end

#created_at ⇒ DateTime

Creation time of the file.

Returns:

  • (DateTime) 


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

def created_at
  @gapi.time_created
end

#delete(generation: nil) ⇒ 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

The file's generation can used by passing true:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

A generation can also be specified:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Parameters:

  • generation (Boolean, Integer) (defaults to: nil) —

    Specify a version of the file to delete. When true, it will delete the version returned by #generation. The default behavior is to delete the latest version of the file (regardless of the version to which the file is set, which is the version returned by #generation.)

Returns:

  • (Boolean) —

    Returns true if the file was deleted.



1081
1082
1083
1084
1085
1086
1087
 
# File 'lib/google/cloud/storage/file.rb', line 1081

def delete generation: nil
  generation = self.generation if generation == true
  ensure_service!
  service.delete_file bucket, name, generation: generation,
                                    user_project: user_project
  true
end

#download(path = nil, verify: :md5, encryption_key: nil, range: nil, skip_decompress: nil) ⇒ ::File, StringIO

Download the file's contents to a local file or an File-like object.

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!"

Download a public file with an unauthenticated client.

require "google/cloud/storage"

storage = Google::Cloud::Storage.anonymous

bucket = storage.bucket "public-bucket", skip_lookup: true
file = bucket.file "path/to/public-file.ext", skip_lookup: true

downloaded = file.download
downloaded.rewind
downloaded.read #=> "Hello world!"

Upload and download gzip-encoded file data.

require "zlib"
require "google/cloud/storage"

storage = Google::Cloud::Storage.new

gz = StringIO.new ""
z = Zlib::GzipWriter.new gz
z.write "Hello world!"
z.close
data = StringIO.new gz.string

bucket = storage.bucket "my-bucket"

bucket.create_file data, "path/to/gzipped.txt",
                   content_encoding: "gzip"

file = bucket.file "path/to/gzipped.txt"

# The downloaded data is decompressed by default.
file.download "path/to/downloaded/hello.txt"

# The downloaded data remains compressed with skip_decompress.
file.download "path/to/downloaded/gzipped.txt",
              skip_decompress: true

Partially download.


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 range: 6..10
downloaded.rewind
downloaded.read #=> "world"

Parameters:

  • path (String, ::File) (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 File object, or File-like object such as StringIO. If an file 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) (defaults to: :md5) —

    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) (defaults to: nil) —

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

  • range (Range, String) (defaults to: nil) —

    Optional. The byte range of the file's contents to download or a string header value. Provide this to perform a partial download. When a range is provided, no verification is performed regardless of the verify parameter's value.

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

    Optional. If true, the data for a Storage object returning a Content-Encoding: gzip response header will not be automatically decompressed by this client library. The default is nil. Note that all requests by this client library send the Accept-Encoding: gzip header, so decompressive transcoding is not performed in the Storage service. (See Transcoding of gzip-compressed files)

Returns:

  • (::File, StringIO) —

    Returns a file 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 File-like object, then that object will be returned.



676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
 
# File 'lib/google/cloud/storage/file.rb', line 676

def download path = nil, verify: :md5, encryption_key: nil, range: nil,
             skip_decompress: nil
  ensure_service!
  if path.nil?
    path = StringIO.new
    path.set_encoding "ASCII-8BIT"
  end
  file, resp =
    service.download_file bucket, name, path,
                          key: encryption_key, range: range,
                          user_project: user_project
  # FIX: downloading with encryption key will return nil
  file ||= ::File.new(path)
  verify = :none if range
  verify_file! file, verify
  if !skip_decompress &&
     Array(resp.header["Content-Encoding"]).include?("gzip")
    file = gzip_decompress file
  end
  file
end

#encryption_key_sha256 ⇒ String

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.

Returns:

  • (String) 


393
394
395
396
 
# File 'lib/google/cloud/storage/file.rb', line 393

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

#etag ⇒ String

HTTP 1.1 Entity tag for the file.

Returns:

  • (String) 


241
242
243
 
# File 'lib/google/cloud/storage/file.rb', line 241

def etag
  @gapi.etag
end

#exists? ⇒ Boolean

Determines whether the file exists in the Storage service.

Returns:

  • (Boolean) 


1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
 
# File 'lib/google/cloud/storage/file.rb', line 1335

def exists?
  # Always true if we have a grpc object
  return true unless lazy?
  # If we have a value, return it
  return @exists unless @exists.nil?
  ensure_gapi!
  @exists = true
rescue Google::Cloud::NotFoundError
  @exists = false
end

#generation ⇒ Fixnum

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

Returns:

  • (Fixnum) 


153
154
155
 
# File 'lib/google/cloud/storage/file.rb', line 153

def generation
  @gapi.generation
end

#generations ⇒ Array<Google::Cloud::Storage::File>

Retrieves a list of versioned files for the current object.

Useful for listing archived versions of the file, restoring the live version of the file to an older version, or deleting an archived version. You can turn versioning on or off for a bucket at any time with Bucket#versioning=. Turning versioning off leaves existing file versions in place and causes the bucket to stop accumulating new archived object versions. (See Bucket#versioning? and #generation)

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.generation #=> 1234567890
file.generations.each do |versioned_file|
  versioned_file.generation
end

Returns:

See Also:



480
481
482
483
484
485
486
487
 
# File 'lib/google/cloud/storage/file.rb', line 480

def generations
  ensure_service!
  gapi = service.list_files bucket, prefix: name,
                                    versions: true,
                                    user_project: user_project
  File::List.from_gapi gapi, service, bucket, name, nil, nil, true,
                       user_project: user_project
end

#id ⇒ String

The ID of the file.

Returns:

  • (String) 


125
126
127
 
# File 'lib/google/cloud/storage/file.rb', line 125

def id
  @gapi.id
end

#kind ⇒ String

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

Returns:

  • (String) 


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

def kind
  @gapi.kind
end

#kms_key ⇒ String?

The Cloud KMS encryption key that was used to protect the file, or nil if none has been configured.

Returns:

  • (String, nil) —

    A Cloud KMS encryption key, or nil if none has been configured.

See Also:



408
409
410
 
# File 'lib/google/cloud/storage/file.rb', line 408

def kms_key
  @gapi.kms_key_name
end

#md5 ⇒ String

MD5 hash of the data; encoded using base64.

Returns:

  • (String) 


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

def md5
  @gapi.md5_hash
end

#media_url ⇒ String

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

Returns:

  • (String) 


183
184
185
 
# File 'lib/google/cloud/storage/file.rb', line 183

def media_url
  @gapi.media_link
end

#metadata ⇒ Hash(String => String)

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.

Returns:

  • (Hash(String => String)) 


364
365
366
367
368
 
# File 'lib/google/cloud/storage/file.rb', line 364

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.

Parameters:

  • metadata (Hash(String => String)) —

    The user-provided metadata, in key/value pairs.



378
379
380
381
 
# File 'lib/google/cloud/storage/file.rb', line 378

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

#metageneration ⇒ Fixnum

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.

Returns:

  • (Fixnum) 


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

def metageneration
  @gapi.metageneration
end

#name ⇒ String

The name of this file.

Returns:

  • (String) 


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

def name
  @gapi.name
end

#public_url(protocol: :https) ⇒ String 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) (defaults to: :https) —

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

Returns:

  • (String)

See Also:



1121
1122
1123
 
# File 'lib/google/cloud/storage/file.rb', line 1121

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

#reload!(generation: nil) ⇒ Object Also known as: refresh!

Reloads the file with current data from the Storage service.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

The file's generation can used by passing true:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext", generation: 123456
file.reload! generation: true

A generation can also be specified:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext", generation: 123456
file.reload! generation: 123457

Parameters:

  • generation (Boolean, Integer) (defaults to: nil) —

    Specify a version of the file to reload with. When true, it will reload the version returned by #generation. The default behavior is to reload with the latest version of the file (regardless of the version to which the file is set, which is the version returned by #generation.)



1322
1323
1324
1325
1326
1327
1328
1329
1330
 
# File 'lib/google/cloud/storage/file.rb', line 1322

def reload! generation: nil
  generation = self.generation if generation == true
  ensure_service!
  @gapi = service.get_file bucket, name, generation: generation,
                                         user_project: user_project
  # If NotFound then lazy will never be unset
  @lazy = nil
  self
end

#rewrite(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil, new_encryption_key: nil, new_kms_key: nil) {|file| ... } ⇒ Google::Cloud::Storage::File

Rewrites the file to a new location. Or the same location can be provided to rewrite the file in place.

If a customer-supplied encryption key was used with Bucket#create_file, the encryption_key option must be provided. Unlike #copy, separate encryption keys are used to read (encryption_key) and to write (new_encryption_key) file contents.

Examples:

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

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

The file can also be rewritten 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.rewrite "new-destination-bucket",
             "path/to/destination/file.ext"

The file can also be rewritten 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.rewrite "copy/of/previous/generation/file.ext",
             generation: 123456

The file can be modified during rewriting:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.rewrite "new-destination-bucket",
             "path/to/destination/file.ext" do |f|
  f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
end

Rewriting with a customer-supplied 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..."

# 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 = bucket.file "path/to/my-file.ext"
file.rewrite "new-destination-bucket",
             "path/to/destination/file.ext",
             encryption_key: old_key,
             new_encryption_key: new_key do |f|
  f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
end

Rewriting with a customer-managed Cloud KMS encryption key:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

# KMS key ring must use the same location as the bucket.
kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"

# Old customer-supplied 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"
file.rewrite "new-destination-bucket",
             "path/to/destination/file.ext",
             encryption_key: old_key,
             new_kms_key: kms_key_name do |f|
  f.metadata["rewritten_from"] = "#{file.bucket}/#{file.name}"
end

Parameters:

  • dest_bucket_or_path (String) —

    Either the bucket to rewrite the file to, or the path to rewrite 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 rewrite the file to in the given bucket.

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

    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) (defaults to: nil) —

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

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

    Optional. The customer-supplied, AES-256 encryption key used to decrypt the file, if the existing file is encrypted.

  • new_encryption_key (String, nil) (defaults to: nil) —

    Optional. The new customer-supplied, AES-256 encryption key with which to encrypt the file. If not provided, the rewritten file will be encrypted using the default server-side encryption, or the new_kms_key if one is provided. Do not provide if new_kms_key is used.

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

    Optional. Resource name of the Cloud KMS key, of the form projects/my-prj/locations/kr-loc/keyRings/my-kr/cryptoKeys/my-key, that will be used to encrypt the file. The KMS key ring must use the same location as the bucket.The Service Account associated with your project requires access to this encryption key. Do not provide if new_encryption_key is used.

Yields:

  • (file) —

    a block yielding a delegate object for updating

Returns:



937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
 
# File 'lib/google/cloud/storage/file.rb', line 937

def rewrite dest_bucket_or_path, dest_path = nil,
            acl: nil, generation: nil,
            encryption_key: nil, new_encryption_key: nil,
            new_kms_key: nil
  ensure_service!
  dest_bucket, dest_path = fix_rewrite_args dest_bucket_or_path,
                                            dest_path

  update_gapi = nil
  if block_given?
    updater = Updater.new gapi
    yield updater
    updater.check_for_changed_metadata!
    if updater.updates.any?
      update_gapi = gapi_from_attrs updater.updates
    end
  end

  new_gapi = rewrite_gapi bucket, name, update_gapi,
                          new_bucket: dest_bucket, new_name: dest_path,
                          acl: acl, generation: generation,
                          encryption_key: encryption_key,
                          new_encryption_key: new_encryption_key,
                          new_kms_key: new_kms_key,
                          user_project: user_project

  File.from_gapi new_gapi, service, user_project: user_project
end

#rotate(encryption_key: nil, new_encryption_key: nil, new_kms_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:

Rotating to a new customer-supplied 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

Rotating to a customer-managed Cloud KMS encryption key:

require "google/cloud/storage"

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

# KMS key ring must use the same location as the bucket.
kms_key_name = "projects/a/locations/b/keyRings/c/cryptoKeys/d"

# 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

file.rotate encryption_key: old_key, new_kms_key: kms_key_name

Parameters:

  • encryption_key (String, nil) (defaults to: nil) —

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

  • new_encryption_key (String, nil) (defaults to: nil) —

    Optional. The new customer-supplied, AES-256 encryption key with which to encrypt the file. If not provided, the rewritten file will be encrypted using the default server-side encryption, or the new_kms_key if one is provided. Do not provide if new_kms_key is used.

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

    Optional. Resource name of the Cloud KMS key, of the form projects/my-prj/locations/kr-loc/keyRings/my-kr/cryptoKeys/my-key, that will be used to encrypt the file. The KMS key ring must use the same location as the bucket.The Service Account associated with your project requires access to this encryption key. Do not provide if new_encryption_key is used.

Returns:

See Also:



1034
1035
1036
1037
1038
1039
 
# File 'lib/google/cloud/storage/file.rb', line 1034

def rotate encryption_key: nil, new_encryption_key: nil,
           new_kms_key: nil
  rewrite bucket, name, encryption_key: encryption_key,
                        new_encryption_key: new_encryption_key,
                        new_kms_key: new_kms_key
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, query: nil) ⇒ String

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: "[email protected]",
                             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) (defaults to: nil) —

    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) (defaults to: nil) —

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

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

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

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

  • 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) (defaults to: nil) —

    Service Account's Private Key.

  • private_key (OpenSSL::PKey::RSA, String) (defaults to: nil) —

    Service Account's Private Key.

  • 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 and response-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 #content_disposition= and #content_type=.)

Returns:

  • (String)

See Also:



1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
 
# File 'lib/google/cloud/storage/file.rb', line 1221

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,
               query: nil
  ensure_service!
  signer = File::Signer.from_file self
  signer.signed_url 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,
                    query: query
end

#size ⇒ Integer

Content-Length of the data in bytes.

Returns:

  • (Integer) 


192
193
194
 
# File 'lib/google/cloud/storage/file.rb', line 192

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

#storage_class ⇒ String

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.

Returns:

  • (String) 


422
423
424
 
# File 'lib/google/cloud/storage/file.rb', line 422

def storage_class
  @gapi.storage_class
end

#storage_class=(storage_class) ⇒ Object

Rewrites the file with a new storage class, which determines the SLA and the cost of storage. Accepted values include:

  • :multi_regional
  • :regional
  • :nearline
  • :coldline

as well as the equivalent 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.



445
446
447
448
 
# File 'lib/google/cloud/storage/file.rb', line 445

def storage_class= storage_class
  @gapi.storage_class = storage_class_for(storage_class)
  update_gapi! :storage_class
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



517
518
519
520
521
522
 
# File 'lib/google/cloud/storage/file.rb', line 517

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

#updated_at ⇒ DateTime

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

Returns:

  • (DateTime) 


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

def updated_at
  @gapi.updated
end