Class: Google::Cloud::Storage::Bucket::Acl

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/storage/bucket/acl.rb

Overview

Bucket Access Control List

Represents a Bucket's Access Control List.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#user_project ⇒ Object

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 Google::Cloud::Storage::Bucket#requester_pays= and Google::Cloud::Storage::Bucket#requester_pays.



68
69
70
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 68

def user_project
  @user_project
end

Instance Method Details

#add_owner(entity) ⇒ String

Grants owner permission to the bucket.

Examples:

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

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

Parameters:

  • 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

Returns:

  • (String) —

    The entity.



197
198
199
200
201
202
203
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 197

def add_owner entity
  gapi = @service.insert_bucket_acl @bucket, entity, "OWNER",
                                    user_project: user_project
  entity = gapi.entity
  @owners&.push entity
  entity
end

#add_reader(entity) ⇒ String

Grants reader permission to the bucket.

Examples:

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

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

Parameters:

  • 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

Returns:

  • (String) —

    The entity.



287
288
289
290
291
292
293
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 287

def add_reader entity
  gapi = @service.insert_bucket_acl @bucket, entity, "READER",
                                    user_project: user_project
  entity = gapi.entity
  @readers&.push entity
  entity
end

#add_writer(entity) ⇒ String

Grants writer permission to the bucket.

Examples:

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.acl.add_writer "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"

email = "authors@example.net"
bucket.acl.add_writer "group-#{email}"

Parameters:

  • 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

Returns:

  • (String) —

    The entity.



242
243
244
245
246
247
248
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 242

def add_writer entity
  gapi = @service.insert_bucket_acl @bucket, entity, "WRITER",
                                    user_project: user_project
  entity = gapi.entity
  @writers&.push entity
  entity
end

#auth!(if_metageneration_match: nil) ⇒ Object Also known as: authenticatedRead!, auth_read!, authenticated!, authenticated_read!

Convenience method to apply the authenticatedRead predefined ACL rule to the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.auth!


352
353
354
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 352

def auth! if_metageneration_match: nil
  update_predefined_acl! "authenticatedRead", if_metageneration_match: if_metageneration_match
end

#delete(entity) ⇒ Boolean

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

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Parameters:

  • 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

Returns:

  • (Boolean) 


323
324
325
326
327
328
329
330
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 323

def delete entity
  @service.delete_bucket_acl @bucket, entity,
                             user_project: user_project
  @owners&.delete entity
  @writers&.delete entity
  @readers&.delete entity
  true
end

#owners ⇒ Array<String>

Lists the owners of the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Returns:

  • (Array<String>) 


117
118
119
120
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 117

def owners
  reload! if @owners.nil?
  @owners
end

#private!(if_metageneration_match: nil) ⇒ Object

Convenience method to apply the private predefined ACL rule to the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.private!


373
374
375
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 373

def private! if_metageneration_match: nil
  update_predefined_acl! "private", if_metageneration_match: if_metageneration_match
end

#project_private!(if_metageneration_match: nil) ⇒ Object Also known as: projectPrivate!

Convenience method to apply the projectPrivate predefined ACL rule to the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.project_private!


390
391
392
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 390

def project_private! if_metageneration_match: nil
  update_predefined_acl! "projectPrivate", if_metageneration_match: if_metageneration_match
end

#public!(if_metageneration_match: nil) ⇒ Object Also known as: publicRead!, public_read!

Convenience method to apply the publicRead predefined ACL rule to the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.public!


408
409
410
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 408

def public! if_metageneration_match: nil
  update_predefined_acl! "publicRead", if_metageneration_match: if_metageneration_match
end

#public_write!(if_metageneration_match: nil) ⇒ Object Also known as: publicReadWrite!

Convenience method to apply the publicReadWrite predefined ACL rule to the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.public_write!


426
427
428
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 426

def public_write! if_metageneration_match: nil
  update_predefined_acl! "publicReadWrite", if_metageneration_match: if_metageneration_match
end

#readers ⇒ Array<String>

Lists the readers of the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

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

Returns:

  • (Array<String>) 


155
156
157
158
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 155

def readers
  reload! if @readers.nil?
  @readers
end

#reload! ⇒ Object Also known as: refresh!

Reloads all Access Control List data for the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.reload!


94
95
96
97
98
99
100
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 94

def reload!
  gapi = @service.list_bucket_acls @bucket, user_project: user_project
  acls = Array(gapi.items)
  @owners  = entities_from_acls acls, "OWNER"
  @writers = entities_from_acls acls, "WRITER"
  @readers = entities_from_acls acls, "READER"
end

#writers ⇒ Array<String>

Lists the owners of the bucket.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-bucket"

bucket.acl.writers.each { |writer| puts writer }

Returns:

  • (Array<String>) 


136
137
138
139
 
# File 'lib/google/cloud/storage/bucket/acl.rb', line 136

def writers
  reload! if @writers.nil?
  @writers
end