Class IAM (4.3.1)

[IAM (Identity and Access Management)](https://cloud.google.com/pubsub/access_control) allows you to set permissions on individual resources and offers a wider range of roles: editor, owner, publisher, subscriber, and viewer. This gives you greater flexibility and allows you to set more fine-grained access control.

For example: * Grant access on a per-topic or per-subscription basis, rather than for the whole Cloud project. * Grant access with limited capabilities, such as to only publish messages to a topic, or to only to consume messages from a subscription, but not to delete the topic or subscription.

*The IAM access control features described in this document are Beta, including the API methods to get and set IAM policies, and to test IAM permissions. Cloud Pub/Sub's use of IAM features is not covered by any SLA or deprecation policy, and may be subject to backward-incompatible changes.*

Package

@google-cloud/pubsub

Example


const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
// topic.iam

const subscription = pubsub.subscription('my-subscription');
// subscription.iam

Constructors

(constructor)(pubsub, id)

constructor(pubsub: PubSub, id: string);

Constructs a new instance of the IAM class

Parameters
Name	Description
`pubsub`	`PubSub`
`id`	`string`

Properties

id

id: string;

pubsub

pubsub: PubSub;

request

request: typeof PubSub.prototype.request;

Methods

getPolicy(gaxOpts)

getPolicy(gaxOpts?: CallOptions): Promise<GetPolicyResponse>;

Get the IAM policy

Parameter
Name	Description
`gaxOpts`	`CallOptions`

Returns

Type Description

Promise<GetPolicyResponse>

{Promise

Example


const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

topic.iam.getPolicy(function(err, policy, apiResponse) {});

subscription.iam.getPolicy(function(err, policy, apiResponse) {});

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

getPolicy(callback)

getPolicy(callback: GetPolicyCallback): void;

Parameter
Name	Description
`callback`	`GetPolicyCallback`

Returns
Type	Description
`void`

getPolicy(gaxOpts, callback)

getPolicy(gaxOpts: CallOptions, callback: GetPolicyCallback): void;

Parameters
Name	Description
`gaxOpts`	`CallOptions`
`callback`	`GetPolicyCallback`

Returns
Type	Description
`void`

setPolicy(policy, gaxOpts)

setPolicy(policy: Policy, gaxOpts?: CallOptions): Promise<SetPolicyResponse>;

Set the IAM policy

Parameters
Name	Description
`policy`	`Policy` The [policy](https://cloud.google.com/pubsub/docs/reference/rest/v1/Policy).
`gaxOpts`	`CallOptions`

Returns

Type Description

Promise<SetPolicyResponse>

{Promise

Example


const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

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

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

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

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

setPolicy(policy, gaxOpts, callback)

setPolicy(policy: Policy, gaxOpts: CallOptions, callback: SetPolicyCallback): void;

Parameters
Name	Description
`policy`	`Policy`
`gaxOpts`	`CallOptions`
`callback`	`SetPolicyCallback`

Returns
Type	Description
`void`

setPolicy(policy, callback)

setPolicy(policy: Policy, callback: SetPolicyCallback): void;

Parameters
Name	Description
`policy`	`Policy`
`callback`	`SetPolicyCallback`

Returns
Type	Description
`void`

testPermissions(permissions, gaxOpts)

testPermissions(permissions: string | string[], gaxOpts?: CallOptions): Promise<TestIamPermissionsResponse>;

Test a set of permissions for a resource.

Permissions with wildcards such as * or storage.* are not allowed.

Parameters
Name	Description
`permissions`	`string \| string[]` The permission(s) to test for.
`gaxOpts`	`CallOptions`

Returns

Type Description

Promise<TestIamPermissionsResponse>

{Promise

Example


const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');

//-
// Test a single permission.
//-
const test = 'pubsub.topics.update';

topic.iam.testPermissions(test, function(err, permissions, apiResponse) {
  console.log(permissions);
  // {
  //   "pubsub.topics.update": true
  // }
});

//-
// Test several permissions at once.
//-
const tests = [
  'pubsub.subscriptions.consume',
  'pubsub.subscriptions.update'
];

subscription.iam.testPermissions(tests, function(err, permissions) {
  console.log(permissions);
  // {
  //   "pubsub.subscriptions.consume": true,
  //   "pubsub.subscriptions.update": false
  // }
});

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

testPermissions(permissions, gaxOpts, callback)

testPermissions(permissions: string | string[], gaxOpts: CallOptions, callback: TestIamPermissionsCallback): void;

Parameters
Name	Description
`permissions`	`string \| string[]`
`gaxOpts`	`CallOptions`
`callback`	`TestIamPermissionsCallback`

Returns
Type	Description
`void`

testPermissions(permissions, callback)

testPermissions(permissions: string | string[], callback: TestIamPermissionsCallback): void;

Parameters
Name	Description
`permissions`	`string \| string[]`
`callback`	`TestIamPermissionsCallback`

Returns
Type	Description
`void`