class Google::Cloud::Storage::File::Acl

# File Access Control List

Represents a File's Access Control List.

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

Constants

RULES

@private

Attributes

user_project[RW]

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

Public Class Methods

new(file) click to toggle source

@private Initialized a new Acl object. Must provide a valid Bucket object.

# File lib/google/cloud/storage/file/acl.rb, line 75
def initialize file
  @bucket = file.bucket
  @file = file.name
  @service = file.service
  @user_project = file.user_project
  @owners  = nil
  @readers = nil
end
predefined_rule_for(rule_name) click to toggle source

@private

# File lib/google/cloud/storage/file/acl.rb, line 290
def self.predefined_rule_for rule_name
  RULES[rule_name.to_s]
end

Public Instance Methods

add_owner(entity, generation: nil) click to toggle source

Grants owner permission to the file.

@param [String] entity 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

@param [Integer] generation When present, selects a specific

revision of this object. Default is the latest version.

@return [String] The entity.

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

@example 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}"
# File lib/google/cloud/storage/file/acl.rb, line 188
def add_owner entity, generation: nil
  gapi = @service.insert_file_acl @bucket, @file, entity, "OWNER",
                                  generation: generation,
                                  user_project: user_project
  entity = gapi.entity
  @owners&.push entity
  entity
end
add_reader(entity, generation: nil) click to toggle source

Grants reader permission to the file.

@param [String] entity 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

@param [Integer] generation When present, selects a specific

revision of this object. Default is the latest version.

@return [String] The entity.

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

@example 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}"
# File lib/google/cloud/storage/file/acl.rb, line 239
def add_reader entity, generation: nil
  gapi = @service.insert_file_acl @bucket, @file, entity, "READER",
                                  generation: generation,
                                  user_project: user_project
  entity = gapi.entity
  @readers&.push entity
  entity
end
auth!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `authenticatedRead` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.auth!
# File lib/google/cloud/storage/file/acl.rb, line 326
def auth! generation: nil,
          if_generation_match: nil,
          if_generation_not_match: nil,
          if_metageneration_match: nil,
          if_metageneration_not_match: nil
  update_predefined_acl! "authenticatedRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
auth_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: auth!
authenticated!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: auth!
authenticatedRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: auth!
authenticated_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: auth!
bucketOwnerFullControl!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: owner_full!
bucketOwnerRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: owner_read!
delete(entity, generation: nil) click to toggle source

Permanently deletes the entity from the file's access control list.

@param [String] entity 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

@param [Integer] generation When present, selects a specific

revision of this object. Default is the latest version.

@return [Boolean] true if the delete operation did not raise an

error

@example

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}"
# File lib/google/cloud/storage/file/acl.rb, line 280
def delete entity, generation: nil
  @service.delete_file_acl \
    @bucket, @file, entity,
    generation: generation, user_project: user_project
  @owners&.delete entity
  @readers&.delete entity
  true
end
owner_full!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `bucketOwnerFullControl` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.owner_full!
# File lib/google/cloud/storage/file/acl.rb, line 373
def owner_full! generation: nil,
                if_generation_match: nil,
                if_generation_not_match: nil,
                if_metageneration_match: nil,
                if_metageneration_not_match: nil
  update_predefined_acl! "bucketOwnerFullControl",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
Also aliased as: bucketOwnerFullControl!
owner_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `bucketOwnerRead` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.owner_read!
# File lib/google/cloud/storage/file/acl.rb, line 417
def owner_read! generation: nil,
                if_generation_match: nil,
                if_generation_not_match: nil,
                if_metageneration_match: nil,
                if_metageneration_not_match: nil
  update_predefined_acl! "bucketOwnerRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
Also aliased as: bucketOwnerRead!
owners() click to toggle source

Lists the owners of the file.

@return [Array<String>]

@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.owners.each { |owner| puts owner }
# File lib/google/cloud/storage/file/acl.rb, line 121
def owners
  reload! if @owners.nil?
  @owners
end
private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `private` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.private!
# File lib/google/cloud/storage/file/acl.rb, line 461
def private! generation: nil,
             if_generation_match: nil,
             if_generation_not_match: nil,
             if_metageneration_match: nil,
             if_metageneration_not_match: nil
  update_predefined_acl! "private",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
projectPrivate!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: project_private!
project_private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `projectPrivate` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.project_private!
# File lib/google/cloud/storage/file/acl.rb, line 504
def project_private! generation: nil,
                     if_generation_match: nil,
                     if_generation_not_match: nil,
                     if_metageneration_match: nil,
                     if_metageneration_not_match: nil
  update_predefined_acl! "projectPrivate",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
Also aliased as: projectPrivate!
public!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source

Convenience method to apply the `publicRead` predefined ACL rule to the file.

@param [Integer] generation Select a specific revision of the file to

update. The default is the latest version.

@param [Integer] if_generation_match 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.

@param [Integer] if_generation_not_match 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.

@param [Integer] if_metageneration_match Makes the operation conditional

on whether the file's current metageneration matches the given value.

@param [Integer] if_metageneration_not_match Makes the operation

conditional on whether the file's current metageneration does not
match the given value.

@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.public!
# File lib/google/cloud/storage/file/acl.rb, line 548
def public! generation: nil,
            if_generation_match: nil,
            if_generation_not_match: nil,
            if_metageneration_match: nil,
            if_metageneration_not_match: nil
  update_predefined_acl! "publicRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end
Also aliased as: publicRead!, public_read!
publicRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: public!
public_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias for: public!
readers() click to toggle source

Lists the readers of the file.

@return [Array<String>]

@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 }
# File lib/google/cloud/storage/file/acl.rb, line 141
def readers
  reload! if @readers.nil?
  @readers
end
refresh!()
Alias for: reload!
reload!() click to toggle source

Reloads all Access Control List data for the file.

@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.reload!
# File lib/google/cloud/storage/file/acl.rb, line 97
def reload!
  gapi = @service.list_file_acls @bucket, @file,
                                 user_project: user_project
  acls = Array(gapi.items)
  @owners  = entities_from_acls acls, "OWNER"
  @readers = entities_from_acls acls, "READER"
end
Also aliased as: refresh!

Protected Instance Methods

clear!() click to toggle source
# File lib/google/cloud/storage/file/acl.rb, line 565
def clear!
  @owners  = nil
  @readers = nil
  self
end
entities_from_acls(acls, role) click to toggle source
# File lib/google/cloud/storage/file/acl.rb, line 591
def entities_from_acls acls, role
  selected = acls.select { |acl| acl.role == role }
  selected.map(&:entity)
end
update_predefined_acl!(acl_role, generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) click to toggle source
# File lib/google/cloud/storage/file/acl.rb, line 571
def update_predefined_acl! acl_role,
                           generation: nil,
                           if_generation_match: nil,
                           if_generation_not_match: nil,
                           if_metageneration_match: nil,
                           if_metageneration_not_match: nil
  patched_file = Google::Apis::StorageV1::Object.new acl: []
  @service.patch_file @bucket,
                      @file,
                      patched_file,
                      generation: generation,
                      if_generation_match: if_generation_match,
                      if_generation_not_match: if_generation_not_match,
                      if_metageneration_match: if_metageneration_match,
                      if_metageneration_not_match: if_metageneration_not_match,
                      predefined_acl: acl_role,
                      user_project: user_project
  clear!
end