Class: Google::Cloud::Storage::Policy

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

Overview

Policy

Represents a Cloud IAM Policy for the Cloud Storage service.

A common pattern for updating a resource's metadata, such as its Policy, is to read the current data from the service, update the data locally, and then send the modified data for writing. This pattern may result in a conflict if two or more processes attempt the sequence simultaneously. IAM solves this problem with the #etag property, which is used to verify whether the policy has changed since the last request. When you make a request to with an etag value, Cloud IAM compares the etag value in the request with the existing etag value associated with the policy. It writes the policy only if the etag values match.

When you update a policy, first read the policy (and its current etag) from the service, then modify the policy locally, and then write the modified policy to the service. See Bucket#policy and Bucket#policy=.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.policy do |p|
  p.remove "roles/storage.admin", "user:owner@example.com"
  p.add "roles/storage.admin", "user:newowner@example.com"
  p.roles["roles/storage.objectViewer"] = ["allUsers"]
end

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#etag ⇒ String

Used to verify whether the policy has changed since the last request. The policy will be written only if the etag values match.

Returns:

  • (String) —

    the current value of etag



72
73
74
 
# File 'lib/google/cloud/storage/policy.rb', line 72

def etag
  @etag
end

#roles ⇒ Hash{String => Array<String>}

The bindings that associate roles with an array of members. See Understanding Roles for a listing of primitive and curated roles. See Buckets: setIamPolicy for a listing of values and patterns for members.

Returns:

  • (Hash{String => Array<String>}) —

    the current value of roles



72
73
74
 
# File 'lib/google/cloud/storage/policy.rb', line 72

def roles
  @roles
end

Instance Method Details

#add(role_name, member) ⇒ Object

Convenience method for adding a member to a binding on this policy. See Understanding Roles for a listing of primitive and curated roles. See Buckets: setIamPolicy for a listing of values and patterns for members.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.policy do |p|
  p.add "roles/storage.admin", "user:newowner@example.com"
end

Parameters:

  • role_name (String) —

    A Cloud IAM role, such as "roles/storage.admin".

  • member (String) —

    A Cloud IAM identity, such as "user:owner@example.com".



106
107
108
 
# File 'lib/google/cloud/storage/policy.rb', line 106

def add role_name, member
  role(role_name) << member
end

#deep_dup ⇒ Policy

Deprecated.

Because the latest policy is now always retrieved by Bucket#policy.

Returns a deep copy of the policy.

Returns:



172
173
174
175
176
177
178
179
180
 
# File 'lib/google/cloud/storage/policy.rb', line 172

def deep_dup
  warn "DEPRECATED: Storage::Policy#deep_dup"
  dup.tap do |p|
    roles_dup = p.roles.each_with_object({}) do |(k, v), memo|
      memo[k] = v.dup rescue value
    end
    p.instance_variable_set "@roles", roles_dup
  end
end

#remove(role_name, member) ⇒ Object

Convenience method for removing a member from a binding on this policy. See Understanding Roles for a listing of primitive and curated roles. See Buckets: setIamPolicy for a listing of values and patterns for members.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.policy do |p|
  p.remove "roles/storage.admin", "user:owner@example.com"
end

Parameters:

  • role_name (String) —

    A Cloud IAM role, such as "roles/storage.admin".

  • member (String) —

    A Cloud IAM identity, such as "user:owner@example.com".



134
135
136
 
# File 'lib/google/cloud/storage/policy.rb', line 134

def remove role_name, member
  role(role_name).delete member
end

#role(role_name) ⇒ Array<String>

Convenience method returning the array of members bound to a role in this policy, or an empty array if no value is present for the role in #roles. See Understanding Roles for a listing of primitive and curated roles. See Buckets: setIamPolicy for a listing of values and patterns for members.

Examples:

require "google/cloud/storage"

storage = Google::Cloud::Storage.new

bucket = storage.bucket "my-todo-app"

bucket.policy do |p|
  p.role("roles/storage.admin") << "user:owner@example.com"
end

Returns:

  • (Array<String>) —

    The members strings, or an empty array.



160
161
162
 
# File 'lib/google/cloud/storage/policy.rb', line 160

def role role_name
  roles[role_name] ||= []
end