Class: Google::Cloud::Storage::File
- Inherits:
-
Object
- Object
- Google::Cloud::Storage::File
- Defined in:
- lib/google/cloud/storage/file.rb,
lib/google/cloud/storage/file/acl.rb,
lib/google/cloud/storage/file/list.rb,
lib/google/cloud/storage/file/signer.rb,
lib/google/cloud/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.
Direct Known Subclasses
Defined Under Namespace
Instance Attribute Summary collapse
-
#user_project ⇒ Object
A boolean value or a project ID string for a requester pays bucket and its files.
Instance Method Summary collapse
-
#acl ⇒ Object
The Acl instance used to control access to the file.
-
#api_url ⇒ Object
A URL that can be used to access the file using the REST API.
-
#bucket ⇒ Object
The name of the Bucket containing this file.
-
#cache_control ⇒ Object
The Cache-Control directive for the file data.
-
#cache_control=(cache_control) ⇒ Object
Updates the Cache-Control directive for the file data.
-
#content_disposition ⇒ Object
The Content-Disposition of the file data.
-
#content_disposition=(content_disposition) ⇒ Object
Updates the Content-Disposition of the file data.
-
#content_encoding ⇒ Object
The Content-Encoding of the file data.
-
#content_encoding=(content_encoding) ⇒ Object
Updates the Content-Encoding of the file data.
-
#content_language ⇒ Object
The Content-Language of the file data.
-
#content_language=(content_language) ⇒ Object
Updates the Content-Language of the file data.
-
#content_type ⇒ Object
The Content-Type of the file data.
-
#content_type=(content_type) ⇒ Object
Updates the Content-Type of the file data.
-
#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil) {|file| ... } ⇒ Google::Cloud::Storage::File
Copy the file to a new location.
-
#crc32c ⇒ Object
The CRC32c checksum of the data, as described in RFC 4960, Appendix B.
-
#created_at ⇒ Object
Creation time of the file.
-
#delete(generation: nil) ⇒ Boolean
Permanently deletes the file.
-
#download(path = nil, verify: :md5, encryption_key: nil) ⇒ IO
Download the file's contents to a local file or an IO instance.
-
#encryption_key_sha256 ⇒ Object
An RFC 4648 Base64-encoded string of the SHA256 hash of the customer-supplied encryption key.
-
#etag ⇒ Object
HTTP 1.1 Entity tag for the file.
-
#exists? ⇒ Boolean
Determines whether the file exists in the Storage service.
-
#generation ⇒ Object
The content generation of this file.
-
#generations ⇒ Array<Google::Cloud::Storage::File>
Retrieves a list of versioned files for the current object.
-
#id ⇒ Object
The ID of the file.
-
#kind ⇒ Object
The kind of item this is.
-
#md5 ⇒ Object
MD5 hash of the data; encoded using base64.
-
#media_url ⇒ Object
A URL that can be used to download the file using the REST API.
-
#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.
-
#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.
-
#metageneration ⇒ Object
The version of the metadata for this file at this generation.
-
#name ⇒ Object
The name of this file.
-
#public_url(protocol: :https) ⇒ Object
(also: #url)
Public URL to access the file.
-
#reload!(generation: nil) ⇒ Object
(also: #refresh!)
Reloads the file with current data from the Storage service.
-
#rotate(encryption_key: nil, new_encryption_key: nil) ⇒ Google::Cloud::Storage::File
Rewrites the file to the same #bucket and #name with a new customer-supplied encryption key.
-
#signed_url(method: nil, expires: nil, content_type: nil, content_md5: nil, headers: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil, query: nil) ⇒ 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.
-
#storage_class ⇒ Object
The file's storage class.
-
#storage_class=(storage_class) ⇒ Object
Updates how the file is stored and determines the SLA and the cost of storage.
-
#update {|file| ... } ⇒ Object
Updates the file with changes made in the given block in a single PATCH request.
-
#updated_at ⇒ Object
The creation or modification time of the file.
Instance Attribute Details
#user_project ⇒ Object
A boolean value or a project ID string for a requester pays
bucket and its files. If this attribute is set to true
, transit
costs for operations on the file will be billed to the current
project for this client. (See Project#project for the ID of the
current project.) If this attribute is set to a project ID, and that
project is authorized for the currently authenticated service account,
transit costs will be billed to the that project. The default is
nil
.
In general, this attribute should be set when first retrieving the
owning bucket by providing the user_project
option to
Project#bucket.
The requester pays feature is currently available only to whitelisted projects.
See also Bucket#requester_pays= and Bucket#requester_pays to enable requester pays for a bucket.
87 88 89 |
# File 'lib/google/cloud/storage/file.rb', line 87 def user_project @user_project 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.
909 910 911 |
# File 'lib/google/cloud/storage/file.rb', line 909 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.
144 145 146 |
# File 'lib/google/cloud/storage/file.rb', line 144 def api_url @gapi.self_link end |
#bucket ⇒ Object
The name of the Bucket containing this file.
122 123 124 |
# File 'lib/google/cloud/storage/file.rb', line 122 def bucket @gapi.bucket end |
#cache_control ⇒ Object
The Cache-Control directive for the file data.
197 198 199 |
# File 'lib/google/cloud/storage/file.rb', line 197 def cache_control @gapi.cache_control end |
#cache_control=(cache_control) ⇒ Object
Updates the Cache-Control directive for the file data.
205 206 207 208 |
# File 'lib/google/cloud/storage/file.rb', line 205 def cache_control= cache_control @gapi.cache_control = cache_control update_gapi! :cache_control end |
#content_disposition ⇒ Object
The Content-Disposition of the file data.
213 214 215 |
# File 'lib/google/cloud/storage/file.rb', line 213 def content_disposition @gapi.content_disposition end |
#content_disposition=(content_disposition) ⇒ Object
Updates the Content-Disposition of the file data.
220 221 222 223 |
# File 'lib/google/cloud/storage/file.rb', line 220 def content_disposition= content_disposition @gapi.content_disposition = content_disposition update_gapi! :content_disposition end |
#content_encoding ⇒ Object
The Content-Encoding of the file data.
229 230 231 |
# File 'lib/google/cloud/storage/file.rb', line 229 def content_encoding @gapi.content_encoding end |
#content_encoding=(content_encoding) ⇒ Object
Updates the Content-Encoding of the file data.
237 238 239 240 |
# File 'lib/google/cloud/storage/file.rb', line 237 def content_encoding= content_encoding @gapi.content_encoding = content_encoding update_gapi! :content_encoding end |
#content_language ⇒ Object
The Content-Language of the file data.
245 246 247 |
# File 'lib/google/cloud/storage/file.rb', line 245 def content_language @gapi.content_language end |
#content_language=(content_language) ⇒ Object
Updates the Content-Language of the file data.
252 253 254 255 |
# File 'lib/google/cloud/storage/file.rb', line 252 def content_language= content_language @gapi.content_language = content_language update_gapi! :content_language end |
#content_type ⇒ Object
The Content-Type of the file data.
260 261 262 |
# File 'lib/google/cloud/storage/file.rb', line 260 def content_type @gapi.content_type end |
#content_type=(content_type) ⇒ Object
Updates the Content-Type of the file data.
268 269 270 271 |
# File 'lib/google/cloud/storage/file.rb', line 268 def content_type= content_type @gapi.content_type = content_type update_gapi! :content_type end |
#copy(dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil) {|file| ... } ⇒ Google::Cloud::Storage::File
Copy the file to a new location.
If a customer-supplied encryption
key
was used with Bucket#create_file, the encryption_key
option must
be provided.
591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 |
# File 'lib/google/cloud/storage/file.rb', line 591 def copy dest_bucket_or_path, dest_path = nil, acl: nil, generation: nil, encryption_key: nil ensure_service! = { acl: acl, generation: generation, key: encryption_key, user_project: user_project } dest_bucket, dest_path, = fix_copy_args dest_bucket_or_path, dest_path, copy_gapi = nil if block_given? updater = Updater.new gapi yield updater updater. copy_gapi = gapi_from_attrs(updater.updates) if updater.updates.any? end resp = service.copy_file bucket, name, dest_bucket, dest_path, copy_gapi, until resp.done sleep 1 resp = service.copy_file bucket, name, dest_bucket, dest_path, copy_gapi, .merge(token: resp.rewrite_token) end File.from_gapi resp.resource, service end |
#crc32c ⇒ Object
The CRC32c checksum of the data, as described in RFC 4960, Appendix B. Encoded using base64 in big-endian byte order.
184 185 186 |
# File 'lib/google/cloud/storage/file.rb', line 184 def crc32c @gapi.crc32c end |
#created_at ⇒ Object
Creation time of the file.
162 163 164 |
# File 'lib/google/cloud/storage/file.rb', line 162 def created_at @gapi.time_created end |
#delete(generation: nil) ⇒ Boolean
Permanently deletes the file.
717 718 719 720 721 722 723 |
# File 'lib/google/cloud/storage/file.rb', line 717 def delete generation: nil generation = self.generation if generation == true ensure_service! service.delete_file bucket, name, generation: generation, user_project: user_project true end |
#download(path = nil, verify: :md5, encryption_key: nil) ⇒ IO
Download the file's contents to a local file or an IO instance.
By default, the download is verified by calculating the MD5 digest.
If a customer-supplied encryption
key
was used with Bucket#create_file, the encryption_key
option must
be provided.
493 494 495 496 497 498 499 500 501 502 503 504 |
# File 'lib/google/cloud/storage/file.rb', line 493 def download path = nil, verify: :md5, encryption_key: nil ensure_service! if path.nil? path = StringIO.new path.set_encoding "ASCII-8BIT" end file = service.download_file \ bucket, name, path, key: encryption_key, user_project: user_project # FIX: downloading with encryption key will return nil file ||= ::File.new(path) verify_file! file, verify end |
#encryption_key_sha256 ⇒ Object
An RFC 4648 Base64-encoded string of the SHA256 hash of the customer-supplied encryption key. You can use this SHA256 hash to uniquely identify the AES-256 encryption key required to decrypt this file.
299 300 301 302 |
# File 'lib/google/cloud/storage/file.rb', line 299 def encryption_key_sha256 return nil unless @gapi.customer_encryption Base64.decode64 @gapi.customer_encryption.key_sha256 end |
#etag ⇒ Object
HTTP 1.1 Entity tag for the file.
190 191 192 |
# File 'lib/google/cloud/storage/file.rb', line 190 def etag @gapi.etag end |
#exists? ⇒ Boolean
Determines whether the file exists in the Storage service.
965 966 967 968 969 970 971 972 973 974 |
# File 'lib/google/cloud/storage/file.rb', line 965 def exists? # Always true if we have a grpc object return true unless lazy? # If we have a value, return it return @exists unless @exists.nil? ensure_gapi! @exists = true rescue Google::Cloud::NotFoundError @exists = false end |
#generation ⇒ Object
The content generation of this file. Used for object versioning.
129 130 131 |
# File 'lib/google/cloud/storage/file.rb', line 129 def generation @gapi.generation end |
#generations ⇒ Array<Google::Cloud::Storage::File>
Retrieves a list of versioned files for the current object.
Useful for listing archived versions of the file, restoring the live version of the file to an older version, or deleting an archived version. You can turn versioning on or off for a bucket at any time with Bucket#versioning=. Turning versioning off leaves existing file versions in place and causes the bucket to stop accumulating new archived object versions. (See Bucket#versioning and #generation)
362 363 364 365 366 367 368 369 |
# File 'lib/google/cloud/storage/file.rb', line 362 def generations ensure_service! gapi = service.list_files bucket, prefix: name, versions: true, user_project: user_project File::List.from_gapi gapi, service, bucket, name, nil, nil, true, user_project: user_project end |
#id ⇒ Object
The ID of the file.
110 111 112 |
# File 'lib/google/cloud/storage/file.rb', line 110 def id @gapi.id end |
#kind ⇒ Object
The kind of item this is. For files, this is always storage#object.
104 105 106 |
# File 'lib/google/cloud/storage/file.rb', line 104 def kind @gapi.kind end |
#md5 ⇒ Object
MD5 hash of the data; encoded using base64.
176 177 178 |
# File 'lib/google/cloud/storage/file.rb', line 176 def md5 @gapi.md5_hash end |
#media_url ⇒ Object
A URL that can be used to download the file using the REST API.
150 151 152 |
# File 'lib/google/cloud/storage/file.rb', line 150 def media_url @gapi.media_link 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.
277 278 279 280 281 |
# File 'lib/google/cloud/storage/file.rb', line 277 def m = @gapi. m = m.to_h if m.respond_to? :to_h m.dup.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.
287 288 289 290 |
# File 'lib/google/cloud/storage/file.rb', line 287 def @gapi. = update_gapi! :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.
138 139 140 |
# File 'lib/google/cloud/storage/file.rb', line 138 def @gapi. end |
#name ⇒ Object
The name of this file.
116 117 118 |
# File 'lib/google/cloud/storage/file.rb', line 116 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 Google::Cloud::Storage::File::Acl#public! and Bucket::DefaultAcl#public!) To share a file that is not public see #signed_url.
755 756 757 |
# File 'lib/google/cloud/storage/file.rb', line 755 def public_url protocol: :https "#{protocol}://storage.googleapis.com/#{bucket}/#{name}" end |
#reload!(generation: nil) ⇒ Object Also known as: refresh!
Reloads the file with current data from the Storage service.
952 953 954 955 956 957 958 959 960 |
# File 'lib/google/cloud/storage/file.rb', line 952 def reload! generation: nil generation = self.generation if generation == true ensure_service! @gapi = service.get_file bucket, name, generation: generation, user_project: user_project # If NotFound then lazy will never be unset @lazy = nil self end |
#rotate(encryption_key: nil, new_encryption_key: nil) ⇒ Google::Cloud::Storage::File
Rewrites the file to the same #bucket and #name with a new customer-supplied encryption key.
If a new key is provided to this method, the new key must be used to subsequently download or copy the file. You must securely manage your keys and ensure that they are not lost. Also, please note that file metadata is not encrypted, with the exception of the CRC32C checksum and MD5 hash. The names of files and buckets are also not encrypted, and you can read or update the metadata of an encrypted file without providing the encryption key.
663 664 665 666 667 668 669 670 671 672 673 674 675 |
# File 'lib/google/cloud/storage/file.rb', line 663 def rotate encryption_key: nil, new_encryption_key: nil ensure_service! = { source_key: encryption_key, destination_key: new_encryption_key, user_project: user_project } gapi = service.rewrite_file bucket, name, bucket, name, nil, until gapi.done sleep 1 [:token] = gapi.rewrite_token gapi = service.rewrite_file bucket, name, bucket, name, nil, end File.from_gapi gapi.resource, service end |
#signed_url(method: nil, expires: nil, content_type: nil, content_md5: nil, headers: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil, query: 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
Google::Cloud.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.
853 854 855 856 857 858 859 860 861 862 863 864 865 |
# File 'lib/google/cloud/storage/file.rb', line 853 def signed_url method: nil, expires: nil, content_type: nil, content_md5: nil, headers: nil, issuer: nil, client_email: nil, signing_key: nil, private_key: nil, query: nil ensure_service! signer = File::Signer.from_file self signer.signed_url method: method, expires: expires, headers: headers, content_type: content_type, content_md5: content_md5, issuer: issuer, client_email: client_email, signing_key: signing_key, private_key: private_key, query: query end |
#size ⇒ Object
Content-Length of the data in bytes.
156 157 158 |
# File 'lib/google/cloud/storage/file.rb', line 156 def size @gapi.size.to_i if @gapi.size end |
#storage_class ⇒ Object
The file's storage class. This defines how the file is stored and determines the SLA and the cost of storage. For more information, see Storage Classes and Per-Object Storage Class.
311 312 313 |
# File 'lib/google/cloud/storage/file.rb', line 311 def storage_class @gapi.storage_class end |
#storage_class=(storage_class) ⇒ Object
Updates how the file is stored and determines the SLA and the cost of
storage. Accepted values include :multi_regional
, :regional
,
:nearline
, and :coldline
, as well as the equivalent strings
returned by #storage_class or Bucket#storage_class. For more
information, see Storage
Classes and
Per-Object Storage
Class.
The default value is the default storage class for the bucket. See
Bucket#storage_class.
327 328 329 330 |
# File 'lib/google/cloud/storage/file.rb', line 327 def storage_class= storage_class @gapi.storage_class = storage_class_for(storage_class) update_gapi! :storage_class 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.
399 400 401 402 403 404 |
# File 'lib/google/cloud/storage/file.rb', line 399 def update updater = Updater.new gapi yield updater updater. update_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.
170 171 172 |
# File 'lib/google/cloud/storage/file.rb', line 170 def updated_at @gapi.updated end |