Class: Google::Cloud::Storage::File::Acl

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

Overview

File Access Control List

Represents a File's Access Control List.

Examples:

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 }

Instance Method Summary collapse

Instance Method Details

#add_owner(entity, generation: nil) ⇒ Object

Grants owner permission to the file.

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"

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

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
  • generation (Integer) —

    When present, selects a specific revision of this object. Default is the latest version.



165
166
167
168
169
170
171
172
 
# File 'lib/google/cloud/storage/file/acl.rb', line 165

def add_owner entity, generation: nil
  options = { generation: generation }
  gapi = @service.insert_file_acl @bucket, @file, entity, "OWNER",
                                  options
  entity = gapi.entity
  @owners.push entity unless @owners.nil?
  entity
end

#add_reader(entity, generation: nil) ⇒ Object

Grants reader permission to the file.

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"

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

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
  • generation (Integer) —

    When present, selects a specific revision of this object. Default is the latest version.



214
215
216
217
218
219
220
221
 
# File 'lib/google/cloud/storage/file/acl.rb', line 214

def add_reader entity, generation: nil
  options = { generation: generation }
  gapi = @service.insert_file_acl @bucket, @file, entity, "READER",
                                  options
  entity = gapi.entity
  @readers.push entity unless @readers.nil?
  entity
end

#auth! ⇒ Object Also known as: authenticatedRead!, auth_read!, authenticated!, authenticated_read!

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

Examples:

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!


281
282
283
 
# File 'lib/google/cloud/storage/file/acl.rb', line 281

def auth!
  update_predefined_acl! "authenticatedRead"
end

#delete(entity, generation: nil) ⇒ Object

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

Examples:

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

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
  • generation (Integer) —

    When present, selects a specific revision of this object. Default is the latest version.



252
253
254
255
256
257
258
 
# File 'lib/google/cloud/storage/file/acl.rb', line 252

def delete entity, generation: nil
  options = { generation: generation }
  @service.delete_file_acl @bucket, @file, entity, options
  @owners.delete entity  unless @owners.nil?
  @readers.delete entity unless @readers.nil?
  true
end

#owner_full! ⇒ Object Also known as: bucketOwnerFullControl!

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

Examples:

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!


303
304
305
 
# File 'lib/google/cloud/storage/file/acl.rb', line 303

def owner_full!
  update_predefined_acl! "bucketOwnerFullControl"
end

#owner_read! ⇒ Object Also known as: bucketOwnerRead!

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

Examples:

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!


322
323
324
 
# File 'lib/google/cloud/storage/file/acl.rb', line 322

def owner_read!
  update_predefined_acl! "bucketOwnerRead"
end

#owners ⇒ Array<String>

Lists the owners of the file.

Examples:

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 }

Returns:

  • (Array<String>) 


100
101
102
103
 
# File 'lib/google/cloud/storage/file/acl.rb', line 100

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

#private! ⇒ Object

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

Examples:

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!


341
342
343
 
# File 'lib/google/cloud/storage/file/acl.rb', line 341

def private!
  update_predefined_acl! "private"
end

#project_private! ⇒ Object Also known as: projectPrivate!

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

Examples:

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!


359
360
361
 
# File 'lib/google/cloud/storage/file/acl.rb', line 359

def project_private!
  update_predefined_acl! "projectPrivate"
end

#public! ⇒ Object Also known as: publicRead!, public_read!

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

Examples:

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!


378
379
380
 
# File 'lib/google/cloud/storage/file/acl.rb', line 378

def public!
  update_predefined_acl! "publicRead"
end

#readers ⇒ Array<String>

Lists the readers of the file.

Examples:

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 }

Returns:

  • (Array<String>) 


120
121
122
123
 
# File 'lib/google/cloud/storage/file/acl.rb', line 120

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

#reload! ⇒ Object Also known as: refresh!

Reloads all Access Control List data for the file.

Examples:

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!


77
78
79
80
81
82
 
# File 'lib/google/cloud/storage/file/acl.rb', line 77

def reload!
  gapi = @service.list_file_acls @bucket, @file
  acls = Array(gapi.items)
  @owners  = entities_from_acls acls, "OWNER"
  @readers = entities_from_acls acls, "READER"
end