Class: Gcloud::Storage::File::Acl

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

Overview

# File Access Control List

Represents a File’s Access Control List.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.readers.each { |reader| puts reader }

Constant Summary collapse

RULES = 
{ "authenticatedRead" => "authenticatedRead",
"auth" => "authenticatedRead",
"auth_read" => "authenticatedRead",
"authenticated" => "authenticatedRead",
"authenticated_read" => "authenticatedRead",
"bucketOwnerFullControl" => "bucketOwnerFullControl",
"owner_full" => "bucketOwnerFullControl",
"bucketOwnerRead" => "bucketOwnerRead",
"owner_read" => "bucketOwnerRead",
"private" => "private",
"projectPrivate" => "projectPrivate",
"project_private" => "projectPrivate",
"publicRead" => "publicRead",
"public" => "publicRead",
"public_read" => "publicRead" }

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file) ⇒ Acl

Must provide a valid Bucket object.



56
57
58
59
60
61
62
 
# File 'lib/gcloud/storage/file/acl.rb', line 56

def initialize file
  @bucket = file.bucket
  @file = file.name
  @service = file.service
  @owners  = nil
  @readers = nil
end

Class Method Details

.predefined_rule_for(rule_name) ⇒ Object 



273
274
275
 
# File 'lib/gcloud/storage/file/acl.rb', line 273

def self.predefined_rule_for rule_name
  RULES[rule_name.to_s]
end

Instance Method Details

#add_owner(entity, generation: nil) ⇒ Object

Grants owner permission to the file.

Examples:

Grant access to a user by pre-pending ‘“user-”` to an email:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
email = "[email protected]"
file.acl.add_owner "user-#{email}"

Grant access to a group by pre-pending ‘“group-”` to an email

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
email = "[email protected]"
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) (defaults to: nil) —

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



174
175
176
177
178
179
180
181
 
# File 'lib/gcloud/storage/file/acl.rb', line 174

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 pre-pending ‘“user-”` to an email:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
email = "[email protected]"
file.acl.add_reader "user-#{email}"

Grant access to a group by pre-pending ‘“group-”` to an email

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
email = "[email protected]"
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) (defaults to: nil) —

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



225
226
227
228
229
230
231
232
 
# File 'lib/gcloud/storage/file/acl.rb', line 225

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.auth!



294
295
296
 
# File 'lib/gcloud/storage/file/acl.rb', line 294

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
email = "[email protected]"
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) (defaults to: nil) —

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



264
265
266
267
268
269
270
 
# File 'lib/gcloud/storage/file/acl.rb', line 264

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.owner_full!



317
318
319
 
# File 'lib/gcloud/storage/file/acl.rb', line 317

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.owner_read!



337
338
339
 
# File 'lib/gcloud/storage/file/acl.rb', line 337

def owner_read!
  update_predefined_acl! "bucketOwnerRead"
end

#owners ⇒ Array<String>

Lists the owners of the file.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.owners.each { |owner| puts owner }

Returns:

  • (Array<String>) 


106
107
108
109
 
# File 'lib/gcloud/storage/file/acl.rb', line 106

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

#private! ⇒ Object

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

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.private!



357
358
359
 
# File 'lib/gcloud/storage/file/acl.rb', line 357

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.project_private!



376
377
378
 
# File 'lib/gcloud/storage/file/acl.rb', line 376

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.public!



396
397
398
 
# File 'lib/gcloud/storage/file/acl.rb', line 396

def public!
  update_predefined_acl! "publicRead"
end

#readers ⇒ Array<String>

Lists the readers of the file.

Examples:

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.readers.each { |reader| puts reader }

Returns:

  • (Array<String>) 


127
128
129
130
 
# File 'lib/gcloud/storage/file/acl.rb', line 127

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

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

file = bucket.file "path/to/my-file.ext"
file.acl.reload!



78
79
80
81
82
83
84
85
86
87
 
# File 'lib/gcloud/storage/file/acl.rb', line 78

def reload!
  gapi = @service.list_file_acls @bucket, @file
  acls = Array(gapi.items).map do |acl|
    return acl if acl.is_a? Google::Apis::StorageV1::ObjectAccessControl
    fail "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