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 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 Bucket#requester_pays= and Bucket#requester_pays.



70
71
72
 
# File 'lib/google/cloud/storage/file/acl.rb', line 70

def user_project
  @user_project
end

Instance Method Details

#add_owner(entity, generation: nil) ⇒ String

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) (defaults to: nil) —

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

Returns:

  • (String) —

    The entity.



188
189
190
191
192
193
194
195
 
# File 'lib/google/cloud/storage/file/acl.rb', line 188

def add_owner entity, generation: nil
  gapi = @service.insert_file_acl @bucket, @file, entity, "OWNER",
                                  generation: generation,
                                  user_project: user_project
  entity = gapi.entity
  @owners&.push entity
  entity
end

#add_reader(entity, generation: nil) ⇒ String

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) (defaults to: nil) —

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

Returns:

  • (String) —

    The entity.



239
240
241
242
243
244
245
246
 
# File 'lib/google/cloud/storage/file/acl.rb', line 239

def add_reader entity, generation: nil
  gapi = @service.insert_file_acl @bucket, @file, entity, "READER",
                                  generation: generation,
                                  user_project: user_project
  entity = gapi.entity
  @readers&.push entity
  entity
end

#auth!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



326
327
328
329
330
331
332
333
334
335
336
337
 
# File 'lib/google/cloud/storage/file/acl.rb', line 326

def auth! generation: nil,
          if_generation_match: nil,
          if_generation_not_match: nil,
          if_metageneration_match: nil,
          if_metageneration_not_match: nil
  update_predefined_acl! "authenticatedRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end

#delete(entity, generation: nil) ⇒ Boolean

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) (defaults to: nil) —

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

Returns:

  • (Boolean) —

    true if the delete operation did not raise an error



280
281
282
283
284
285
286
287
 
# File 'lib/google/cloud/storage/file/acl.rb', line 280

def delete entity, generation: nil
  @service.delete_file_acl \
    @bucket, @file, entity,
    generation: generation, user_project: user_project
  @owners&.delete entity
  @readers&.delete entity
  true
end

#owner_full!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/google/cloud/storage/file/acl.rb', line 373

def owner_full! generation: nil,
                if_generation_match: nil,
                if_generation_not_match: nil,
                if_metageneration_match: nil,
                if_metageneration_not_match: nil
  update_predefined_acl! "bucketOwnerFullControl",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end

#owner_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



417
418
419
420
421
422
423
424
425
426
427
428
 
# File 'lib/google/cloud/storage/file/acl.rb', line 417

def owner_read! generation: nil,
                if_generation_match: nil,
                if_generation_not_match: nil,
                if_metageneration_match: nil,
                if_metageneration_not_match: nil
  update_predefined_acl! "bucketOwnerRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
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>) 


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

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

#private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



461
462
463
464
465
466
467
468
469
470
471
472
 
# File 'lib/google/cloud/storage/file/acl.rb', line 461

def private! generation: nil,
             if_generation_match: nil,
             if_generation_not_match: nil,
             if_metageneration_match: nil,
             if_metageneration_not_match: nil
  update_predefined_acl! "private",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end

#project_private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



504
505
506
507
508
509
510
511
512
513
514
515
 
# File 'lib/google/cloud/storage/file/acl.rb', line 504

def project_private! generation: nil,
                     if_generation_match: nil,
                     if_generation_not_match: nil,
                     if_metageneration_match: nil,
                     if_metageneration_not_match: nil
  update_predefined_acl! "projectPrivate",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
end

#public!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil) ⇒ 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!

Parameters:

  • generation (Integer) (defaults to: nil) —

    Select a specific revision of the file to update. The default is the latest version.

  • if_generation_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation matches the given value. Setting to 0 makes the operation succeed only if there are no live versions of the file.

  • if_generation_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current generation does not match the given value. If no live file exists, the precondition fails. Setting to 0 makes the operation succeed only if there is a live version of the file.

  • if_metageneration_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration matches the given value.

  • if_metageneration_not_match (Integer) (defaults to: nil) —

    Makes the operation conditional on whether the file's current metageneration does not match the given value.



548
549
550
551
552
553
554
555
556
557
558
559
 
# File 'lib/google/cloud/storage/file/acl.rb', line 548

def public! generation: nil,
            if_generation_match: nil,
            if_generation_not_match: nil,
            if_metageneration_match: nil,
            if_metageneration_not_match: nil
  update_predefined_acl! "publicRead",
                         generation: generation,
                         if_generation_match: if_generation_match,
                         if_generation_not_match: if_generation_not_match,
                         if_metageneration_match: if_metageneration_match,
                         if_metageneration_not_match: if_metageneration_not_match
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>) 


141
142
143
144
 
# File 'lib/google/cloud/storage/file/acl.rb', line 141

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!


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

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