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

Classes: Acl, List, Updater

Instance Method Summary collapse

Instance Method Details

#aclObject

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:


616
617
618
# File 'lib/gcloud/storage/file.rb', line 616

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

#api_urlObject

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

#bucketObject

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_controlObject

The Cache-Control 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 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_dispositionObject

The Content-Disposition 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 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_encodingObject

The Content-Encoding 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 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_languageObject

The Content-Language 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 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_typeObject

The Content-Type 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 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

412
413
414
415
416
417
418
419
420
421
422
423
424
425
# File 'lib/gcloud/storage/file.rb', line 412

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

#crc32cObject

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

def crc32c
  @gapi["crc32c"]
end

#created_atObject

Creation time of the file.


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

def created_at
  @gapi["timeCreated"]
end

#deleteBoolean

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

443
444
445
446
447
448
449
450
451
# File 'lib/gcloud/storage/file.rb', line 443

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

343
344
345
346
347
348
349
350
351
352
353
354
# File 'lib/gcloud/storage/file.rb', line 343

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

#etagObject

HTTP 1.1 Entity tag for the file.


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

def etag
  @gapi["etag"]
end

#generationObject

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

#idObject

The ID of the file.


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

def id
  @gapi["id"]
end

#kindObject

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

#md5Object

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_urlObject

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

#metadataObject

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 
  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= 
  patch_gapi! metadata: 
end

#metagenerationObject

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

#nameObject

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"

See Also:


485
486
487
# File 'lib/gcloud/storage/file.rb', line 485

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.


622
623
624
625
626
627
628
629
630
# File 'lib/gcloud/storage/file.rb', line 622

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.

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

See Also:


559
560
561
562
563
564
565
566
567
568
569
# File 'lib/gcloud/storage/file.rb', line 559

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

#sizeObject

Content-Length of the data in bytes.


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

def size
  @gapi["size"]
end

#update {|updater| ... } ⇒ 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.["player"] = "Bob"
  f.["score"] = "10"
end

Yields:

  • (updater)

275
276
277
278
279
# File 'lib/gcloud/storage/file.rb', line 275

def update
  updater = Updater.new 
  yield updater
  patch_gapi! updater.updates unless updater.updates.empty?
end

#updated_atObject

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