class Google::Cloud::Storage::Bucket::DefaultAcl

# Bucket Default Access Control List

Represents a Bucket's Default Access Control List.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_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(bucket) click to toggle source

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

# File lib/google/cloud/storage/bucket/acl.rb, line 507
def initialize bucket
  @bucket = bucket.name
  @service = bucket.service
  @user_project = bucket.user_project
  @owners  = nil
  @readers = nil
end

predefined_rule_for(rule_name) click to toggle source

@private

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

Public Instance Methods

add_owner(entity) click to toggle source

Grants default owner permission to files in the bucket.

@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

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

email = "heidi@example.net"
bucket.default_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"

email = "authors@example.net"
bucket.default_acl.add_owner "group-#{email}"

# File lib/google/cloud/storage/bucket/acl.rb, line 613
def add_owner entity
  gapi = @service.insert_default_acl @bucket, entity, "OWNER",
                                     user_project: user_project
  entity = gapi.entity
  @owners&.push entity
  entity
end

add_reader(entity) click to toggle source

Grants default reader permission to files in the bucket.

@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

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

email = "heidi@example.net"
bucket.default_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"

email = "authors@example.net"
bucket.default_acl.add_reader "group-#{email}"

# File lib/google/cloud/storage/bucket/acl.rb, line 656
def add_reader entity
  gapi = @service.insert_default_acl @bucket, entity, "READER",
                                     user_project: user_project
  entity = gapi.entity
  @readers&.push entity
  entity
end

auth!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `authenticatedRead` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.auth!

# File lib/google/cloud/storage/bucket/acl.rb, line 718
def auth! if_metageneration_match: nil
  update_predefined_default_acl! "authenticatedRead", if_metageneration_match: if_metageneration_match
end

Also aliased as: authenticatedRead!, auth_read!, authenticated!, authenticated_read!

auth_read!(if_metageneration_match: nil)

Alias for: auth!

authenticated!(if_metageneration_match: nil)

Alias for: auth!

authenticatedRead!(if_metageneration_match: nil)

Alias for: auth!

authenticated_read!(if_metageneration_match: nil)

Alias for: auth!

bucketOwnerFullControl!(if_metageneration_match: nil)

Alias for: owner_full!

bucketOwnerRead!(if_metageneration_match: nil)

Alias for: owner_read!

delete(entity) click to toggle source

Permanently deletes the entity from the bucket's default access control list for files.

@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

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

email = "heidi@example.net"
bucket.default_acl.delete "user-#{email}"

# File lib/google/cloud/storage/bucket/acl.rb, line 690
def delete entity
  @service.delete_default_acl @bucket, entity,
                              user_project: user_project
  @owners&.delete entity
  @readers&.delete entity
  true
end

owner_full!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `bucketOwnerFullControl` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.owner_full!

# File lib/google/cloud/storage/bucket/acl.rb, line 739
def owner_full! if_metageneration_match: nil
  update_predefined_default_acl! "bucketOwnerFullControl", if_metageneration_match: if_metageneration_match
end

Also aliased as: bucketOwnerFullControl!

owner_read!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `bucketOwnerRead` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.owner_read!

# File lib/google/cloud/storage/bucket/acl.rb, line 757
def owner_read! if_metageneration_match: nil
  update_predefined_default_acl! "bucketOwnerRead", if_metageneration_match: if_metageneration_match
end

Also aliased as: bucketOwnerRead!

owners() click to toggle source

Lists the default owners for files in the bucket.

@return [Array<String>]

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.owners.each { |owner| puts owner }

# File lib/google/cloud/storage/bucket/acl.rb, line 554
def owners
  reload! if @owners.nil?
  @owners
end

private!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `private` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.private!

# File lib/google/cloud/storage/bucket/acl.rb, line 775
def private! if_metageneration_match: nil
  update_predefined_default_acl! "private", if_metageneration_match: if_metageneration_match
end

projectPrivate!(if_metageneration_match: nil)

Alias for: project_private!

project_private!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `projectPrivate` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.project_private!

# File lib/google/cloud/storage/bucket/acl.rb, line 792
def project_private! if_metageneration_match: nil
  update_predefined_default_acl! "projectPrivate", if_metageneration_match: if_metageneration_match
end

Also aliased as: projectPrivate!

public!(if_metageneration_match: nil) click to toggle source

Convenience method to apply the default `publicRead` predefined ACL rule to files in the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.public!

# File lib/google/cloud/storage/bucket/acl.rb, line 810
def public! if_metageneration_match: nil
  update_predefined_default_acl! "publicRead", if_metageneration_match: if_metageneration_match
end

Also aliased as: publicRead!, public_read!

publicRead!(if_metageneration_match: nil)

Alias for: public!

public_read!(if_metageneration_match: nil)

Alias for: public!

readers() click to toggle source

Lists the default readers for files in the bucket.

@return [Array<String>]

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.readers.each { |reader| puts reader }

# File lib/google/cloud/storage/bucket/acl.rb, line 573
def readers
  reload! if @readers.nil?
  @readers
end

refresh!()

Alias for: reload!

reload!() click to toggle source

Reloads all Default Access Control List data for the bucket.

@example

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.default_acl.reload!

# File lib/google/cloud/storage/bucket/acl.rb, line 527
def reload!
  gapi = @service.list_default_acls @bucket,
                                    user_project: user_project
  acls = Array(gapi.items).map do |acl|
    next acl if acl.is_a? Google::Apis::StorageV1::ObjectAccessControl
    raise "Unknown ACL format: #{acl.class}" unless acl.is_a? Hash
    Google::Apis::StorageV1::ObjectAccessControl.from_json acl.to_json
  end
  @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/bucket/acl.rb, line 818
def clear!
  @owners  = nil
  @readers = nil
  self
end

entities_from_acls(acls, role) click to toggle source

# File lib/google/cloud/storage/bucket/acl.rb, line 831
def entities_from_acls acls, role
  selected = acls.select { |acl| acl.role == role }
  selected.map(&:entity)
end

update_predefined_default_acl!(acl_role, if_metageneration_match: nil) click to toggle source

# File lib/google/cloud/storage/bucket/acl.rb, line 824
def update_predefined_default_acl! acl_role, if_metageneration_match: nil
  @service.patch_bucket @bucket, predefined_default_acl: acl_role,
                                 user_project: user_project,
                                 if_metageneration_match: if_metageneration_match
  clear!
end