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](cloud.google.com/storage/docs/json_api/v1/objects)) 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

Modules: Verifier Classes: Acl, List, Signer, Updater

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ File

Returns a new instance of File.



60
61
62
63
 
# File 'lib/google/cloud/storage/file.rb', line 60

def initialize
  @service = nil
  @gapi = Google::Apis::StorageV1::Object.new
end

Instance Attribute Details

#gapi ⇒ Object 



56
57
58
 
# File 'lib/google/cloud/storage/file.rb', line 56

def gapi
  @gapi
end

#service ⇒ Object 



52
53
54
 
# File 'lib/google/cloud/storage/file.rb', line 52

def service
  @service
end

Class Method Details

.from_gapi(gapi, service) ⇒ Object 



682
683
684
685
686
687
 
# File 'lib/google/cloud/storage/file.rb', line 682

def self.from_gapi gapi, service
  new.tap do |f|
    f.gapi = gapi
    f.service = service
  end
end

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



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

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](tools.ietf.org/html/rfc7234#section-5.2) 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](tools.ietf.org/html/rfc7234#section-5.2) 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](tools.ietf.org/html/rfc6266) 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](tools.ietf.org/html/rfc6266) 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 ](tools.ietf.org/html/rfc7231#section-3.1.2.2) 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 ](tools.ietf.org/html/rfc7231#section-3.1.2.2) 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](tools.ietf.org/html/bcp47) 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](tools.ietf.org/html/bcp47) 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](tools.ietf.org/html/rfc2616#section-14.17) 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](tools.ietf.org/html/rfc2616#section-14.17) 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, encryption_key_sha256: nil) ⇒ Google::Cloud::Storage::File

Copy the file to a new location.

If a [customer-supplied encryption key](cloud.google.com/storage/docs/encryption#customer-supplied) 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) (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. Must be provided if ‘encryption_key_sha256` is provided.

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

    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:



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

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](tools.ietf.org/html/rfc4960#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"

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.



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

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](cloud.google.com/storage/docs/encryption#customer-supplied) 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) (defaults to: :md5) —

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

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

    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



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

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](tools.ietf.org/html/rfc4648#section-4) Base64-encoded string of the SHA256 hash of the [customer-supplied encryption key](cloud.google.com/storage/docs/encryption#customer-supplied). 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"

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

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

See Also:



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

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.



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

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]( cloud.google.com/storage/docs/authentication#service_accounts).

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: "[email protected]",
                             signing_key: key

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.

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

See Also:



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

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.



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

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

#to_gs_url ⇒ Object

gs://my-bucket/file-name.json.



676
677
678
 
# File 'lib/google/cloud/storage/file.rb', line 676

def to_gs_url
  "gs://#{bucket}/#{name}"
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



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

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