File Access Control List
Represents a File's Access Control List.
Inherits
- Object
Example
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.readers.each { |reader| puts reader }
Methods
#add_owner
def add_owner(entity, generation: nil) -> String
Grants owner permission to the file.
-
entity (String) —
The entity holding the permission, in one of the following forms:
- user-userId
- user-email
- group-groupId
- group-email
- domain-domain
- project-team-projectId
- allUsers
- allAuthenticatedUsers
- generation (Integer) (defaults to: nil) — When present, selects a specific revision of this object. Default is the latest version.
- (String) — The entity.
Grant access to a user by prepending "user-"
to an email:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" email = "heidi@example.net" file.acl.add_owner "user-#{email}"
Grant access to a group by prepending "group-"
to email:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" email = "authors@example.net" file.acl.add_owner "group-#{email}"
#add_reader
def add_reader(entity, generation: nil) -> String
Grants reader permission to the file.
-
entity (String) —
The entity holding the permission, in one of the following forms:
- user-userId
- user-email
- group-groupId
- group-email
- domain-domain
- project-team-projectId
- allUsers
- allAuthenticatedUsers
- generation (Integer) (defaults to: nil) — When present, selects a specific revision of this object. Default is the latest version.
- (String) — The entity.
Grant access to a user by prepending "user-"
to an email:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" email = "heidi@example.net" file.acl.add_reader "user-#{email}"
Grant access to a group by prepending "group-"
to email:
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" email = "authors@example.net" file.acl.add_reader "group-#{email}"
#auth!
def auth!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the authenticatedRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.auth!
#auth_read!
def auth_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the authenticatedRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.auth!
#authenticated!
def authenticated!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the authenticatedRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.auth!
#authenticatedRead!
def authenticatedRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the authenticatedRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.auth!
#authenticated_read!
def authenticated_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the authenticatedRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.auth!
#bucketOwnerFullControl!
def bucketOwnerFullControl!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the bucketOwnerFullControl
predefined
ACL rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.owner_full!
#bucketOwnerRead!
def bucketOwnerRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the bucketOwnerRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.owner_read!
#delete
def delete(entity, generation: nil) -> Boolean
Permanently deletes the entity from the file's access control list.
-
entity (String) —
The entity holding the permission, in one of the following forms:
- user-userId
- user-email
- group-groupId
- group-email
- domain-domain
- project-team-projectId
- allUsers
- allAuthenticatedUsers
- generation (Integer) (defaults to: nil) — When present, selects a specific revision of this object. Default is the latest version.
- (Boolean) — true if the delete operation did not raise an error
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" email = "heidi@example.net" file.acl.delete "user-#{email}"
#owner_full!
def owner_full!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the bucketOwnerFullControl
predefined
ACL rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.owner_full!
#owner_read!
def owner_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the bucketOwnerRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.owner_read!
#owners
def owners() -> Array<String>
Lists the owners of the file.
- (Array<String>)
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.owners.each { |owner| puts owner }
#private!
def private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the private
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.private!
#projectPrivate!
def projectPrivate!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the projectPrivate
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.project_private!
#project_private!
def project_private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the projectPrivate
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.project_private!
#public!
def public!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the publicRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.public!
#publicRead!
def publicRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the publicRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.public!
#public_read!
def public_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Convenience method to apply the publicRead
predefined ACL
rule to the file.
- generation (Integer) (defaults to: nil) — Select a specific revision of the file to update. The default is the latest version.
- if_generation_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.
- if_generation_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.
- if_metageneration_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration matches the given value.
- if_metageneration_not_match (Integer) (defaults to: nil) — Makes the operation conditional on whether the file's current metageneration does not match the given value.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.public!
#readers
def readers() -> Array<String>
Lists the readers of the file.
- (Array<String>)
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.readers.each { |reader| puts reader }
#refresh!
def refresh!()
Reloads all Access Control List data for the file.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.reload!
#reload!
def reload!()
Reloads all Access Control List data for the file.
require "google/cloud/storage" storage = Google::Cloud::Storage.new bucket = storage.bucket "my-bucket" file = bucket.file "path/to/my-file.ext" file.acl.reload!
#user_project
def user_project()
A boolean value or a project ID string to indicate the project to
be billed for operations on the bucket and its files. If this
attribute is set to true
, transit costs for operations on the
bucket 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 that project. This attribute is required with requester
pays-enabled buckets. 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.
See also Bucket#requester_pays= and Bucket#requester_pays.
#user_project=
def user_project=(value)
A boolean value or a project ID string to indicate the project to
be billed for operations on the bucket and its files. If this
attribute is set to true
, transit costs for operations on the
bucket 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 that project. This attribute is required with requester
pays-enabled buckets. 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.
See also Bucket#requester_pays= and Bucket#requester_pays.