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.

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

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



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

def initialize file #:nodoc:
  @bucket = file.bucket
  @file = file.name
  @connection = file.connection
  @owners  = nil
  @writers = nil
  @readers = nil
end

Class Method Details

.predefined_rule_for(rule_name) ⇒ Object

:nodoc:



401
402
403
 
# File 'lib/gcloud/storage/file/acl.rb', line 401

def self.predefined_rule_for rule_name #:nodoc:
  RULES[rule_name.to_s]
end

Instance Method Details

#add_owner(entity, options = {}) ⇒ Object

Grants owner permission to the file.

Parameters

entity

The entity holding the permission, in one of the following forms: (String)

  • user-userId

  • user-email

  • group-groupId

  • group-email

  • domain-domain

  • project-team-projectId

  • allUsers

  • allAuthenticatedUsers

options

An optional Hash for controlling additional behavior. (Hash)

options[:generation]

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

Examples

Access to a file can be granted to a user by appending “user-” to the email address:

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

Access to a file can be granted to a group by appending “group-” to the email address:

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



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

def add_owner entity, options = {}
  resp = @connection.insert_file_acl @bucket, @file, entity,
                                     "OWNER", options
  if resp.success?
    entity = resp.data["entity"]
    @owners.push entity unless @owners.nil?
    return entity
  end
  nil
end

#add_reader(entity, options = {}) ⇒ Object

Grants reader permission to the file.

Parameters

entity

The entity holding the permission, in one of the following forms: (String)

  • user-userId

  • user-email

  • group-groupId

  • group-email

  • domain-domain

  • project-team-projectId

  • allUsers

  • allAuthenticatedUsers

options

An optional Hash for controlling additional behavior. (Hash)

options[:generation]

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

Examples

Access to a file can be granted to a user by appending “user-” to the email address:

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

Access to a file can be granted to a group by appending “group-” to the email address:

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



342
343
344
345
346
347
348
349
350
351
 
# File 'lib/gcloud/storage/file/acl.rb', line 342

def add_reader entity, options = {}
  resp = @connection.insert_file_acl @bucket, @file, entity,
                                     "READER", options
  if resp.success?
    entity = resp.data["entity"]
    @readers.push entity unless @readers.nil?
    return entity
  end
  nil
end

#add_writer(entity, options = {}) ⇒ Object

Grants writer permission to the file.

Parameters

entity

The entity holding the permission, in one of the following forms: (String)

  • user-userId

  • user-email

  • group-groupId

  • group-email

  • domain-domain

  • project-team-projectId

  • allUsers

  • allAuthenticatedUsers

options

An optional Hash for controlling additional behavior. (Hash)

options[:generation]

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

Examples

Access to a file can be granted to a user by appending “user-” to the email address:

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_writer "user-#{email}"

Access to a file can be granted to a group by appending “group-” to the email address:

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_writer "group-#{email}"



277
278
279
280
281
282
283
284
285
286
 
# File 'lib/gcloud/storage/file/acl.rb', line 277

def add_writer entity, options = {}
  resp = @connection.insert_file_acl @bucket, @file, entity,
                                     "WRITER", options
  if resp.success?
    entity = resp.data["entity"]
    @writers.push entity unless @writers.nil?
    return entity
  end
  nil
end

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

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

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



423
424
425
 
# File 'lib/gcloud/storage/file/acl.rb', line 423

def auth!
  update_predefined_acl! "authenticatedRead"
end

#delete(entity, options = {}) ⇒ Object

Permenently deletes the entity from the file’s access control list.

Parameters

entity

The entity holding the permission, in one of the following forms: (String)

  • user-userId

  • user-email

  • group-groupId

  • group-email

  • domain-domain

  • project-team-projectId

  • allUsers

  • allAuthenticatedUsers

options

An optional Hash for controlling additional behavior. (Hash)

options[:generation]

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

Example

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



390
391
392
393
394
395
396
397
398
399
 
# File 'lib/gcloud/storage/file/acl.rb', line 390

def delete entity, options = {}
  resp = @connection.delete_file_acl @bucket, @file, entity, options
  if resp.success?
    @owners.delete entity  unless @owners.nil?
    @writers.delete entity unless @writers.nil?
    @readers.delete entity unless @readers.nil?
    return true
  end
  false
end

#owner_full! ⇒ Object Also known as: bucketOwnerFullControl!

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

Example

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!



447
448
449
 
# File 'lib/gcloud/storage/file/acl.rb', line 447

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.

Example

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!



468
469
470
 
# File 'lib/gcloud/storage/file/acl.rb', line 468

def owner_read!
  update_predefined_acl! "bucketOwnerRead"
end

#owners ⇒ Object

Lists the owners of the file.

Returns

Array of Strings

Example

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 }



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

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

#private! ⇒ Object

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

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



489
490
491
 
# File 'lib/gcloud/storage/file/acl.rb', line 489

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.

Example

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!



509
510
511
 
# File 'lib/gcloud/storage/file/acl.rb', line 509

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.

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



530
531
532
 
# File 'lib/gcloud/storage/file/acl.rb', line 530

def public!
  update_predefined_acl! "publicRead"
end

#readers ⇒ Object

Lists the readers of the file.

Returns

Array of Strings

Example

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 }



153
154
155
156
 
# File 'lib/gcloud/storage/file/acl.rb', line 153

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

#refresh! ⇒ Object

Reloads all Access Control List data for the file.

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



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

def refresh!
  resp = @connection.list_file_acls @bucket, @file
  acls = resp.data["items"]
  @owners  = entities_from_acls acls, "OWNER"
  @writers = entities_from_acls acls, "WRITER"
  @readers = entities_from_acls acls, "READER"
end

#writers ⇒ Object

Lists the owners of the file.

Returns

Array of Strings

Example

require "gcloud"

gcloud = Gcloud.new
storage = gcloud.storage

bucket = storage.bucket "my-bucket"

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



129
130
131
132
 
# File 'lib/gcloud/storage/file/acl.rb', line 129

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