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



657
658
659
 
# File 'lib/google/cloud/storage/file.rb', line 657

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.



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

def api_url
  @gapi.self_link
end

#bucket ⇒ Object

The name of the Bucket containing this file.



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

def bucket
  @gapi.bucket
end

#cache_control ⇒ Object

The Cache-Control directive for the file data.



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

def cache_control
  @gapi.cache_control
end

#cache_control=(cache_control) ⇒ Object

Updates the Cache-Control directive for the file data.



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

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.



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

def content_disposition
  @gapi.content_disposition
end

#content_disposition=(content_disposition) ⇒ Object

Updates the Content-Disposition of the file data.



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

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.



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

def content_encoding
  @gapi.content_encoding
end

#content_encoding=(content_encoding) ⇒ Object

Updates the Content-Encoding of the file data.



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

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.



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

def content_language
  @gapi.content_language
end

#content_language=(content_language) ⇒ Object

Updates the Content-Language of the file data.



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

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.



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

def content_type
  @gapi.content_type
end

#content_type=(content_type) ⇒ Object

Updates the Content-Type of the file data.



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

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:



450
451
452
453
454
455
456
457
458
459
460
461
 
# File 'lib/google/cloud/storage/file.rb', line 450

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.



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

def crc32c
  @gapi.crc32c
end

#created_at ⇒ Object

Creation time of the file.



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

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.



478
479
480
481
482
 
# File 'lib/google/cloud/storage/file.rb', line 478

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

#download(path, verify: :md5, encryption_key: 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 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

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.

Returns:

  • (File) —

    Returns a ::File object on the local file system



371
372
373
374
375
376
377
 
# File 'lib/google/cloud/storage/file.rb', line 371

def download path, verify: :md5, encryption_key: nil
  ensure_service!
  service.download_file \
    bucket, name, path,
    key: encryption_key
  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.



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

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.



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

def etag
  @gapi.etag
end

#generation ⇒ Object

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



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

def generation
  @gapi.generation
end

#id ⇒ Object

The ID of the file.



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

def id
  @gapi.id
end

#kind ⇒ Object

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



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

def kind
  @gapi.kind
end

#md5 ⇒ Object

MD5 hash of the data; encoded using base64.



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

def md5
  @gapi.md5_hash
end

#media_url ⇒ Object

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



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

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.



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

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.



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

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.



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

def metageneration
  @gapi.metageneration
end

#name ⇒ Object

The name of this file.



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

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:



514
515
516
 
# File 'lib/google/cloud/storage/file.rb', line 514

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.



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

def reload!
  ensure_service!
  @gapi = service.get_file bucket, name
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: "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

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:



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

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.



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

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



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

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.



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

def updated_at
  @gapi.updated
end