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. For more information, see Concepts and Techniques.

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.download "/downloads/#{bucket.name}/#{file.name}"

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

Create an empty File object.



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

def initialize #:nodoc:
  @connection = nil
  @gapi = {}
end

Instance Attribute Details

#connection ⇒ Object

The Connection object.



49
50
51
 
# File 'lib/gcloud/storage/file.rb', line 49

def connection
  @connection
end

#gapi ⇒ Object

The Google API Client object.



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

def gapi
  @gapi
end

Class Method Details

.from_gapi(gapi, conn) ⇒ Object

New File from a Google API Client object.



688
689
690
691
692
693
 
# File 'lib/gcloud/storage/file.rb', line 688

def self.from_gapi gapi, conn #:nodoc:
  new.tap do |f|
    f.gapi = gapi
    f.connection = conn
  end
end

Instance Method Details

#acl ⇒ Object

The File::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. See the Access Control guide for more.

Examples

Access to a file can be granted to a user by appending “user-” to the email address:

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

Access to a file can be granted to a group by appending “group-” to the email address:

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

Access to a file can also be granted to a predefined list of permissions:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

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

file.acl.public!



662
663
664
 
# File 'lib/gcloud/storage/file.rb', line 662

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.



105
106
107
 
# File 'lib/gcloud/storage/file.rb', line 105

def api_url
  @gapi["selfLink"]
end

#bucket ⇒ Object

The name of the bucket containing this file.



83
84
85
 
# File 'lib/gcloud/storage/file.rb', line 83

def bucket
  @gapi["bucket"]
end

#cache_control ⇒ Object

The Cache-Control directive for the file data.



158
159
160
 
# File 'lib/gcloud/storage/file.rb', line 158

def cache_control
  @gapi["cacheControl"]
end

#cache_control=(cache_control) ⇒ Object

Updates the Cache-Control directive for the file data.



166
167
168
 
# File 'lib/gcloud/storage/file.rb', line 166

def cache_control= cache_control
  patch_gapi! cache_control: cache_control
end

#content_disposition ⇒ Object

The Content-Disposition of the file data.



173
174
175
 
# File 'lib/gcloud/storage/file.rb', line 173

def content_disposition
  @gapi["contentDisposition"]
end

#content_disposition=(content_disposition) ⇒ Object

Updates the Content-Disposition of the file data.



180
181
182
 
# File 'lib/gcloud/storage/file.rb', line 180

def content_disposition= content_disposition
  patch_gapi! content_disposition: content_disposition
end

#content_encoding ⇒ Object

The Content-Encoding of the file data.



187
188
189
 
# File 'lib/gcloud/storage/file.rb', line 187

def content_encoding
  @gapi["contentEncoding"]
end

#content_encoding=(content_encoding) ⇒ Object

Updates the Content-Encoding of the file data.



194
195
196
 
# File 'lib/gcloud/storage/file.rb', line 194

def content_encoding= content_encoding
  patch_gapi! content_encoding: content_encoding
end

#content_language ⇒ Object

The Content-Language of the file data.



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

def content_language
  @gapi["contentLanguage"]
end

#content_language=(content_language) ⇒ Object

Updates the Content-Language of the file data.



208
209
210
 
# File 'lib/gcloud/storage/file.rb', line 208

def content_language= content_language
  patch_gapi! content_language: content_language
end

#content_type ⇒ Object

The Content-Type of the file data.



215
216
217
 
# File 'lib/gcloud/storage/file.rb', line 215

def content_type
  @gapi["contentType"]
end

#content_type=(content_type) ⇒ Object

Updates the Content-Type of the file data.



223
224
225
 
# File 'lib/gcloud/storage/file.rb', line 223

def content_type= content_type
  patch_gapi! content_type: content_type
end

#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil) ⇒ Object

Copy the file to a new location.

Parameters

dest_bucket_or_path

Either the bucket to copy the file to, or the path to copy the file to in the current bucket. (String)

dest_path

If a bucket was provided in the first parameter, this contains the path to copy the file to in the given bucket. (String)

acl

A predefined set of access controls to apply to new file. (String)

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

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

Returns

File object

Examples

The file can also 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



431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/gcloud/storage/file.rb', line 431

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. Encoded using base64 in big-endian byte order.



145
146
147
 
# File 'lib/gcloud/storage/file.rb', line 145

def crc32c
  @gapi["crc32c"]
end

#created_at ⇒ Object

Creation time of the file.



123
124
125
 
# File 'lib/gcloud/storage/file.rb', line 123

def created_at
  @gapi["timeCreated"]
end

#delete ⇒ Object

Permanently deletes the file.

Returns

true if the file was deleted.

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



465
466
467
468
469
470
471
472
473
 
# File 'lib/gcloud/storage/file.rb', line 465

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

Download the file’s contents to a local file.

Parameters

path

The path on the local file system to write the data to. The path provided must be writable. (String)

verify

The verification algoruthm used to ensure the downloaded file contents are correct. Default is :md5. (Symbol)

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 object on the local file system

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"

The download is verified by calculating the MD5 digest. The CRC32c digest can be used 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

Both the MD5 and CRC32c digest can be used 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

The download verification can be disabled 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



350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/gcloud/storage/file.rb', line 350

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.



151
152
153
 
# File 'lib/gcloud/storage/file.rb', line 151

def etag
  @gapi["etag"]
end

#generation ⇒ Object

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



90
91
92
 
# File 'lib/gcloud/storage/file.rb', line 90

def generation
  @gapi["generation"]
end

#id ⇒ Object

The ID of the file.



71
72
73
 
# File 'lib/gcloud/storage/file.rb', line 71

def id
  @gapi["id"]
end

#kind ⇒ Object

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



65
66
67
 
# File 'lib/gcloud/storage/file.rb', line 65

def kind
  @gapi["kind"]
end

#md5 ⇒ Object

MD5 hash of the data; encoded using base64.



137
138
139
 
# File 'lib/gcloud/storage/file.rb', line 137

def md5
  @gapi["md5Hash"]
end

#media_url ⇒ Object

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



111
112
113
 
# File 'lib/gcloud/storage/file.rb', line 111

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.



231
232
233
234
235
 
# File 'lib/gcloud/storage/file.rb', line 231

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.



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

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.



99
100
101
 
# File 'lib/gcloud/storage/file.rb', line 99

def metageneration
  @gapi["metageneration"]
end

#name ⇒ Object

The name of this file.



77
78
79
 
# File 'lib/gcloud/storage/file.rb', line 77

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 File::Acl#public! and Bucket::DefaultAcl#public!) For more information, read [Accessing Public Data]https://cloud.google.com/storage/docs/access-public-data.

To share a file that is not public see #signed_url.

Parameters

protocol

The protocol to use for the URL. Default is HTTPS. (String)

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

To generate the URL with a protocol other than HTTPS, use the protocol option:

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"



511
512
513
 
# File 'lib/gcloud/storage/file.rb', line 511

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.



668
669
670
671
672
673
674
675
676
 
# File 'lib/gcloud/storage/file.rb', line 668

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. See the Access Control Signed URLs guide for more.

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. A SignedUrlUnavailable is raised if the service account credentials are missing. Service account credentials are acquired by following the steps in Account Authentication[ cloud.google.com/storage/docs/authentication#service_accounts].

Parameters

method

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. (String)

expires

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

content_type

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

content_md5

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. (String)

issuer

Service Account’s Client Email. (String)

client_email

Service Account’s Client Email. (String)

signing_key

Service Account’s Private Key. (OpenSSL::PKey::RSA or String)

private_key

Service Account’s Private Key. (OpenSSL::PKey::RSA or String)

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

Signed URLs require service account credentials. If you are not authenticated with a service account, those credentials can be passed in using the issuer and signing_key options. 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.

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



597
598
599
600
601
602
603
604
605
606
607
 
# File 'lib/gcloud/storage/file.rb', line 597

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.



117
118
119
 
# File 'lib/gcloud/storage/file.rb', line 117

def size
  @gapi["size"]
end

#to_gs_url ⇒ Object

URI of the location and file name in the format of gs://my-bucket/file-name.json.



682
683
684
 
# File 'lib/gcloud/storage/file.rb', line 682

def to_gs_url #:nodoc:
  "gs://#{bucket}/#{name}"
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.metadata["player"] = "Bob"
  f.metadata["score"] = "10"
end

Yields:

  • (updater) 


273
274
275
276
277
 
# File 'lib/gcloud/storage/file.rb', line 273

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.



131
132
133
 
# File 'lib/gcloud/storage/file.rb', line 131

def updated_at
  @gapi["updated"]
end