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 the File/Object that belong to a Bucket.

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ File

Create an empty File object.



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

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

Instance Attribute Details

#connection ⇒ Object

The Connection object.



40
41
42
 
# File 'lib/gcloud/storage/file.rb', line 40

def connection
  @connection
end

#gapi ⇒ Object

The Google API Client object.



44
45
46
 
# File 'lib/gcloud/storage/file.rb', line 44

def gapi
  @gapi
end

Class Method Details

.from_gapi(gapi, conn) ⇒ Object

New File from a Google API Client object.



475
476
477
478
479
480
 
# File 'lib/gcloud/storage/file.rb', line 475

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!



462
463
464
 
# File 'lib/gcloud/storage/file.rb', line 462

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

#bucket ⇒ Object

The name of the bucket containing this file.



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

def bucket
  @gapi["bucket"]
end

#copy(dest_bucket_or_path, dest_path = nil, options = {}) ⇒ 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)

options

An optional Hash for controlling additional behavior. (Hash)

options[: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.

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"



281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/gcloud/storage/file.rb', line 281

def copy dest_bucket_or_path, dest_path = nil, options = {}
  ensure_connection!
  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

CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64.



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

def crc32c
  @gapi["crc32c"]
end

#delete ⇒ Object

Permenently 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



314
315
316
317
318
319
320
321
322
 
# File 'lib/gcloud/storage/file.rb', line 314

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

#download(path, options = {}) ⇒ 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)

options

An optional Hash for controlling additional behavior. (Hash)

options[: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



206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/gcloud/storage/file.rb', line 206

def download path, options = {}
  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), options
  else
    fail ApiError.from_response(resp)
  end
end

#etag ⇒ Object

HTTP 1.1 Entity tag for the file.



129
130
131
 
# File 'lib/gcloud/storage/file.rb', line 129

def etag
  @gapi["etag"]
end

#generation ⇒ Object

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



81
82
83
 
# File 'lib/gcloud/storage/file.rb', line 81

def generation
  @gapi["generation"]
end

#id ⇒ Object

The ID of the file.



62
63
64
 
# File 'lib/gcloud/storage/file.rb', line 62

def id
  @gapi["id"]
end

#kind ⇒ Object

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



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

def kind
  @gapi["kind"]
end

#md5 ⇒ Object

MD5 hash of the data; encoded using base64.



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

def md5
  @gapi["md5Hash"]
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.



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

def metageneration
  @gapi["metageneration"]
end

#name ⇒ Object

The name of this file.



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

def name
  @gapi["name"]
end

#signed_url(options = {}) ⇒ 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

options

An optional Hash for controlling additional behavior. (Hash)

options[: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)

options[:expires]

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

options[:content_type]

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

options[: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)

options[:issuer]

Service Account’s Client Email. (String)

options[:signing_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



403
404
405
406
407
 
# File 'lib/gcloud/storage/file.rb', line 403

def signed_url options = {}
  ensure_connection!
  signer = File::Signer.new self
  signer.signed_url options
end

#size ⇒ Object

Content-Length of the data in bytes.



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

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.



469
470
471
 
# File 'lib/gcloud/storage/file.rb', line 469

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



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

def updated_at
  @gapi["updated"]
end

#url ⇒ Object

The url to the file.



96
97
98
 
# File 'lib/gcloud/storage/file.rb', line 96

def url
  @gapi["selfLink"]
end