Class: Gcloud::Storage::File
- Inherits:
-
Object
- Object
- Gcloud::Storage::File
- 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
Defined Under Namespace
Modules: Verifier Classes: Acl, List, Signer
Instance Attribute Summary collapse
-
#connection ⇒ Object
The Connection object.
-
#gapi ⇒ Object
The Google API Client object.
Class Method Summary collapse
-
.from_gapi(gapi, conn) ⇒ Object
New File from a Google API Client object.
Instance Method Summary collapse
-
#acl ⇒ Object
The File::Acl instance used to control access to the file.
-
#bucket ⇒ Object
The name of the bucket containing this file.
-
#copy(dest_bucket_or_path, dest_path = nil, options = {}) ⇒ Object
Copy the file to a new location.
-
#crc32c ⇒ Object
CRC32c checksum, as described in RFC 4960, Appendix B; encoded using base64.
-
#delete ⇒ Object
Permenently deletes the file.
-
#download(path, options = {}) ⇒ Object
Download the file’s contents to a local file.
-
#etag ⇒ Object
HTTP 1.1 Entity tag for the file.
-
#generation ⇒ Object
The content generation of this file.
-
#id ⇒ Object
The ID of the file.
-
#initialize ⇒ File
constructor
Create an empty File object.
-
#kind ⇒ Object
The kind of item this is.
-
#md5 ⇒ Object
MD5 hash of the data; encoded using base64.
-
#metageneration ⇒ Object
The version of the metadata for this file at this generation.
-
#name ⇒ Object
The name of this file.
-
#signed_url(options = {}) ⇒ Object
Access without authentication can be granted to a File for a specified period of time.
-
#size ⇒ Object
Content-Length of the data in bytes.
-
#to_gs_url ⇒ Object
URI of the location and file name in the format of
gs://my-bucket/file-name.json
. -
#updated_at ⇒ Object
The creation or modification time of the file.
-
#url ⇒ Object
The url to the file.
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, = {} ensure_connection! dest_bucket, dest_path, = fix_copy_args dest_bucket_or_path, dest_path, resp = connection.copy_file bucket, name, dest_bucket, dest_path, 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
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, = {} 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), 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 @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
, andDELETE
requests. Default isGET
. (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
orString
)
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 = {} ensure_connection! signer = File::Signer.new self signer.signed_url 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 |