Methods

getPolicy

getPolicy(options, callback) returns Promise containing GetPolicyResponse

Get the IAM policy.

Parameter

options

Optional

GetPolicyRequest

Request options.

callback

Optional

GetPolicyCallback

Callback function.

See also

Buckets: setIamPolicy API Documentation

Returns

Promise containing GetPolicyResponse 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');
bucket.iam.getPolicy(function(err, policy, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.iam.getPolicy().then(function(data) {
  const policy = data[0];
  const apiResponse = data[1];
});

Example of retrieving a bucket's IAM policy:

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage();

/**
 * TODO(developer): Uncomment the following line before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';

// Gets and displays the bucket's IAM policy
const results = await storage.bucket(bucketName).iam.getPolicy();

const policy = results[0].bindings;

// Displays the roles in the bucket's IAM policy
console.log(`Roles for bucket ${bucketName}:`);
policy.forEach(role => {
  console.log(`  Role: ${role.role}`);
  console.log(`  Members:`);

  const members = role.members;
  members.forEach(member => {
    console.log(`    ${member}`);
  });
});

setPolicy

setPolicy(policy, options, callback) returns Promise containing SetPolicyResponse

Set the IAM policy.

Parameter

policy

Policy

The policy.

options

Optional

SetPolicyOptions

Configuration opbject.

callback

SetPolicyCallback

Callback function.

See also

Buckets: setIamPolicy API Documentation

IAM Roles

Throws

Error 

If no policy is provided.

Returns

Promise containing SetPolicyResponse 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');

const myPolicy = {
  bindings: [
    {
      role: 'roles/storage.admin',
      members:
['serviceAccount:myotherproject@appspot.gserviceaccount.com']
    }
  ]
};

bucket.iam.setPolicy(myPolicy, function(err, policy, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.iam.setPolicy(myPolicy).then(function(data) {
  const policy = data[0];
  const apiResponse = data[1];
});

Example of adding to a bucket's IAM policy:

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const roleName = 'Role to grant, e.g. roles/storage.objectViewer';
// const members = [
//   'user:jdoe@example.com',    // Example members to grant
//   'group:admins@example.com', // the new role to
// ];

// Creates a client
const storage = new Storage();

// Get a reference to a Google Cloud Storage bucket
const bucket = storage.bucket(bucketName);

// Gets and updates the bucket's IAM policy
const [policy] = await bucket.iam.getPolicy();

// Adds the new roles to the bucket's IAM policy
policy.bindings.push({
  role: roleName,
  members: members,
});

// Updates the bucket's IAM policy
await bucket.iam.setPolicy(policy);

console.log(
  `Added the following member(s) with role ${roleName} to ${bucketName}:`
);

members.forEach(member => {
  console.log(`  ${member}`);
});

Example of removing from a bucket's IAM policy:

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const bucketName = 'Name of a bucket, e.g. my-bucket';
// const roleName = 'Role to grant, e.g. roles/storage.objectViewer';
// const members = [
//   'user:jdoe@example.com',    // Example members to grant
//   'group:admins@example.com', // the new role to
// ];

// Creates a client
const storage = new Storage();

// Get a reference to a Google Cloud Storage bucket
const bucket = storage.bucket(bucketName);

// Gets and updates the bucket's IAM policy
const [policy] = await bucket.iam.getPolicy();

// Finds and updates the appropriate role-member group
const index = policy.bindings.findIndex(role => role.role === roleName);
const role = policy.bindings[index];
if (role) {
  role.members = role.members.filter(
    member => members.indexOf(member) === -1
  );

  // Updates the policy object with the new (or empty) role-member group
  if (role.members.length === 0) {
    policy.bindings.splice(index, 1);
  } else {
    policy.bindings.index = role;
  }

  // Updates the bucket's IAM policy
  await bucket.iam.setPolicy(policy);
} else {
  // No matching role-member group(s) were found
  throw new Error('No matching role-member group(s) found.');
}

console.log(
  `Removed the following member(s) with role ${roleName} from ${bucketName}:`
);
members.forEach(member => {
  console.log(`  ${member}`);
});

testPermissions

testPermissions(permissions, options, callback) returns Promise containing TestIamPermissionsResponse

Test a set of permissions for a resource.

Parameter

permissions

(string or Array of string)

The permission(s) to test for.

options

Optional

TestIamPermissionsOptions

Configuration object.

callback

Optional

TestIamPermissionsCallback

Callback function.

See also

Buckets: testIamPermissions API Documentation

Throws

Error 

If permissions are not provided.

Returns

Promise containing TestIamPermissionsResponse 

Example

const {Storage} = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('my-bucket');

//-
// Test a single permission.
//-
const test = 'storage.buckets.delete';

bucket.iam.testPermissions(test, function(err, permissions, apiResponse) {
  console.log(permissions);
  // {
  //   "storage.buckets.delete": true
  // }
});

//-
// Test several permissions at once.
//-
const tests = [
  'storage.buckets.delete',
  'storage.buckets.get'
];

bucket.iam.testPermissions(tests, function(err, permissions) {
  console.log(permissions);
  // {
  //   "storage.buckets.delete": false,
  //   "storage.buckets.get": true
  // }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
bucket.iam.testPermissions(test).then(function(data) {
  const permissions = data[0];
  const apiResponse = data[1];
});