Class: Gcloud::Storage::File

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/storage/file.rb,
lib/gcloud/storage/file/acl.rb,
lib/gcloud/storage/file/list.rb,
lib/gcloud/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 "gcloud"

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

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/gcloud/storage/file.rb', line 60

def initialize
  @connection = nil
  @gapi = {}
end

Instance Attribute Details

#connection ⇒ Object 



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

def connection
  @connection
end

#gapi ⇒ Object 



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

def gapi
  @gapi
end

Class Method Details

.from_gapi(gapi, conn) ⇒ Object 



646
647
648
649
650
651
 
# File 'lib/gcloud/storage/file.rb', line 646

def self.from_gapi gapi, conn
  new.tap do |f|
    f.gapi = gapi
    f.connection = conn
  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 pre-pending ‘“user-”` to an email:

require "gcloud"

gcloud = Gcloud.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 pre-pending ‘“group-”` to an email:

require "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

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

file.acl.public!

See Also:



620
621
622
 
# File 'lib/gcloud/storage/file.rb', line 620

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/gcloud/storage/file.rb', line 108

def api_url
  @gapi["selfLink"]
end

#bucket ⇒ Object

The name of the Bucket containing this file.



86
87
88
 
# File 'lib/gcloud/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/gcloud/storage/file.rb', line 161

def cache_control
  @gapi["cacheControl"]
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
 
# File 'lib/gcloud/storage/file.rb', line 169

def cache_control= cache_control
  patch_gapi! cache_control: cache_control
end

#content_disposition ⇒ Object

The [Content-Disposition](tools.ietf.org/html/rfc6266) of the file data.



176
177
178
 
# File 'lib/gcloud/storage/file.rb', line 176

def content_disposition
  @gapi["contentDisposition"]
end

#content_disposition=(content_disposition) ⇒ Object

Updates the [Content-Disposition](tools.ietf.org/html/rfc6266) of the file data.



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

def content_disposition= content_disposition
  patch_gapi! content_disposition: content_disposition
end

#content_encoding ⇒ Object

The [Content-Encoding ](tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file data.



190
191
192
 
# File 'lib/gcloud/storage/file.rb', line 190

def content_encoding
  @gapi["contentEncoding"]
end

#content_encoding=(content_encoding) ⇒ Object

Updates the [Content-Encoding ](tools.ietf.org/html/rfc7231#section-3.1.2.2) of the file data.



197
198
199
 
# File 'lib/gcloud/storage/file.rb', line 197

def content_encoding= content_encoding
  patch_gapi! content_encoding: content_encoding
end

#content_language ⇒ Object

The [Content-Language](tools.ietf.org/html/bcp47) of the file data.



204
205
206
 
# File 'lib/gcloud/storage/file.rb', line 204

def content_language
  @gapi["contentLanguage"]
end

#content_language=(content_language) ⇒ Object

Updates the [Content-Language](tools.ietf.org/html/bcp47) of the file data.



211
212
213
 
# File 'lib/gcloud/storage/file.rb', line 211

def content_language= content_language
  patch_gapi! content_language: content_language
end

#content_type ⇒ Object

The [Content-Type](tools.ietf.org/html/rfc2616#section-14.17) of the file data.



218
219
220
 
# File 'lib/gcloud/storage/file.rb', line 218

def content_type
  @gapi["contentType"]
end

#content_type=(content_type) ⇒ Object

Updates the [Content-Type](tools.ietf.org/html/rfc2616#section-14.17) of the file data.



226
227
228
 
# File 'lib/gcloud/storage/file.rb', line 226

def content_type= content_type
  patch_gapi! content_type: content_type
end

#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil) ⇒ Gcloud::Storage::File

Copy the file to a new location.

Examples:

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

require "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.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.

Returns:



416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'lib/gcloud/storage/file.rb', line 416

def copy dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil
  ensure_connection!
  options = { acl: acl, generation: generation }
  dest_bucket, dest_path, options = fix_copy_args dest_bucket_or_path,
                                                  dest_path, options

  resp = connection.copy_file bucket, name,
                              dest_bucket, dest_path, options
  if resp.success?
    File.from_gapi resp.data, connection
  else
    fail ApiError.from_response(resp)
  end
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/gcloud/storage/file.rb', line 148

def crc32c
  @gapi["crc32c"]
end

#created_at ⇒ Object

Creation time of the file.



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

def created_at
  @gapi["timeCreated"]
end

#delete ⇒ Boolean

Permanently deletes the file.

Examples:

require "gcloud"

gcloud = Gcloud.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.



447
448
449
450
451
452
453
454
455
 
# File 'lib/gcloud/storage/file.rb', line 447

def delete
  ensure_connection!
  resp = connection.delete_file bucket, name
  if resp.success?
    true
  else
    fail ApiError.from_response(resp)
  end
end

#download(path, verify: :md5) ⇒ File

Download the file’s contents to a local file.

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

Examples:

require "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.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.

Returns:

  • (File) —

    Returns a ‘::File` object on the local file system



346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/gcloud/storage/file.rb', line 346

def download path, verify: :md5
  ensure_connection!
  resp = connection.download_file bucket, name
  if resp.success?
    ::File.open path, "wb+" do |f|
      f.write resp.body
    end
    verify_file! ::File.new(path), verify
  else
    fail ApiError.from_response(resp)
  end
end

#etag ⇒ Object

HTTP 1.1 Entity tag for the file.



154
155
156
 
# File 'lib/gcloud/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/gcloud/storage/file.rb', line 93

def generation
  @gapi["generation"]
end

#id ⇒ Object

The ID of the file.



74
75
76
 
# File 'lib/gcloud/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/gcloud/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/gcloud/storage/file.rb', line 140

def md5
  @gapi["md5Hash"]
end

#media_url ⇒ Object

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



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

def media_url
  @gapi["mediaLink"]
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.



234
235
236
237
238
 
# File 'lib/gcloud/storage/file.rb', line 234

def metadata
  m = @gapi["metadata"]
  m = m.to_hash if m.respond_to? :to_hash
  m.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.



244
245
246
 
# File 'lib/gcloud/storage/file.rb', line 244

def metadata= metadata
  patch_gapi! metadata: 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/gcloud/storage/file.rb', line 102

def metageneration
  @gapi["metageneration"]
end

#name ⇒ Object

The name of this file.



80
81
82
 
# File 'lib/gcloud/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 Gcloud::Storage::File::Acl#public! and Bucket::DefaultAcl#public!) To share a file that is not public see #signed_url.

Examples:

require "gcloud"

gcloud = Gcloud.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 "gcloud"

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



489
490
491
 
# File 'lib/gcloud/storage/file.rb', line 489

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.



626
627
628
629
630
631
632
633
634
 
# File 'lib/gcloud/storage/file.rb', line 626

def reload!
  ensure_connection!
  resp = connection.get_file bucket, name
  if resp.success?
    @gapi = resp.data
  else
    fail ApiError.from_response(resp)
  end
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 Gcloud.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 "gcloud"

gcloud = Gcloud.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 "gcloud"

gcloud = Gcloud.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 "gcloud/storage"

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



563
564
565
566
567
568
569
570
571
572
573
 
# File 'lib/gcloud/storage/file.rb', line 563

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_connection!
  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/gcloud/storage/file.rb', line 120

def size
  @gapi["size"]
end

#to_gs_url ⇒ Object

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



640
641
642
 
# File 'lib/gcloud/storage/file.rb', line 640

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

gcloud = Gcloud.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



277
278
279
280
281
 
# File 'lib/gcloud/storage/file.rb', line 277

def update
  updater = Updater.new metadata
  yield updater
  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/gcloud/storage/file.rb', line 134

def updated_at
  @gapi["updated"]
end