Cloud Storage API - Class Google::Cloud::Storage::File::Acl (v1.37.0)

Reference documentation and code samples for the Cloud Storage API class Google::Cloud::Storage::File::Acl.

File Access Control List

Represents a File's Access Control List.

Inherits

  • Object

Example

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 }

Methods

#add_owner

def add_owner(entity, generation: nil) -> String

Grants owner permission to the file.

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

#add_reader

def add_reader(entity, generation: nil) -> String

Grants reader permission to the file.

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

#auth!

def auth!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Aliases

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

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.
Example 
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!

#auth_read!

def auth_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #auth!

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

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.
Example 
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!

#authenticated!

def authenticated!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #auth!

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

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.
Example 
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!

#authenticatedRead!

def authenticatedRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #auth!

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

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.
Example 
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!

#authenticated_read!

def authenticated_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #auth!

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

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.
Example 
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!

#bucketOwnerFullControl!

def bucketOwnerFullControl!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #owner_full!

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

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.
Example 
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!

#bucketOwnerRead!

def bucketOwnerRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #owner_read!

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

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.
Example 
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!

#delete

def delete(entity, generation: nil) -> Boolean

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

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

#owner_full!

def owner_full!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Aliases

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

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.
Example 
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!

#owner_read!

def owner_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Aliases

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

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.
Example 
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!

#owners

def owners() -> Array<String>

Lists the owners of the file.

Returns
  • (Array<String>)
Example 
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 }

#private!

def private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)

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

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.
Example 
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!

#projectPrivate!

def projectPrivate!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #project_private!

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

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.
Example 
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!

#project_private!

def project_private!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Aliases

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

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.
Example 
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!

#public!

def public!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Aliases

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

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.
Example 
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!

#publicRead!

def publicRead!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #public!

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

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.
Example 
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!

#public_read!

def public_read!(generation: nil, if_generation_match: nil, if_generation_not_match: nil, if_metageneration_match: nil, if_metageneration_not_match: nil)
Alias Of: #public!

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

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.
Example 
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!

#readers

def readers() -> Array<String>

Lists the readers of the file.

Returns
  • (Array<String>)
Example 
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 }

#refresh!

def refresh!()
Alias Of: #reload!

Reloads all Access Control List data for the file.

Example 
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!

#reload!

def reload!()
Aliases

Reloads all Access Control List data for the file.

Example 
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!

#user_project

def user_project()

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.

#user_project=

def user_project=(value)

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.