Properties

new Topic(pubsub, name)

Example

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

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

Parameters

Name Type Optional Description

pubsub

 

 

PubSub object.

name

 

 

Name of the topic.

Properties

iam

IAM (Identity and Access Management) 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.

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.

Example

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

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

//-
// Get the IAM policy for your topic.
//-
topic.iam.getPolicy((err, policy) => {
  console.log(policy);
});

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

Access Control Overview

What is Cloud IAM?

name  string

The fully qualified name of this topic.

parent  PubSub

The parent PubSub instance of this topic instance.

pubsub  PubSub

The parent PubSub instance of this topic instance.

Methods

create([gaxOpts][, callback]) → Promise containing CreateTopicResponse

Create a topic.

Example

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

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

topic.create((err, topic, apiResponse) => {
  if (!err) {
    // The topic was created successfully.
  }
});

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

Parameters

Name Type Optional Description

gaxOpts

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.

callback

CreateTopicCallback

Yes

Callback function.

Returns

Promise containing CreateTopicResponse 

createSubscription(name[, options][, callback]) → Promise containing CreateSubscriptionResponse

Create a subscription to this topic.

Example

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

const topic = pubsub.topic('my-topic');
const callback = function(err, subscription, apiResponse) {};

// Without specifying any options.
topic.createSubscription('newMessages', callback);

// With options.
topic.createSubscription('newMessages', {
  ackDeadlineSeconds: 90
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.createSubscription('newMessages').then((data) => {
  const subscription = data[0];
  const apiResponse = data[1];
});

Parameters

Name Type Optional Description

name

string

 

The name of the subscription.

options

CreateSubscriptionRequest

Yes

See a Subscription resource.

callback

CreateSubscriptionCallback

Yes

Callback function.

See also

Subscriptions: create API Documentation

Throws

Error 

If subscription name is omitted.

Returns

Promise containing CreateSubscriptionResponse 

delete([gaxOpts][, callback])

Delete the topic. This will not delete subscriptions to this topic.

Example

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

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

topic.delete((err, apiResponse) => {});

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

Parameters

Name Type Optional Description

gaxOpts

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.

callback

function()

Yes

The callback function.

Values in callback have the following properties:

Name Type Optional Description

err

error

 

An error returned while making this request.

Value can be null.

apiResponse

object

 

Raw API response.

See also

Topics: delete API Documentation

exists([callback]) → Promise containing TopicExistsResponse

Check if a topic exists.

Example

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

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

topic.exists((err, exists) => {});

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.exists().then((data) => {
  const exists = data[0];
});

Parameter

Name Type Optional Description

callback

TopicExistsCallback

Yes

Callback function.

Returns

Promise containing TopicExistsResponse 

get([gaxOpts][, callback]) → Promise containing GetTopicResponse

Get a topic if it exists.

Example

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

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

topic.get((err, topic, apiResponse) => {
  // The `topic` data has been populated.
});

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

Parameters

Name Type Optional Description

gaxOpts

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.

Values in gaxOpts have the following properties:

Name Type Optional Description

autoCreate

boolean

Yes

Automatically create the topic does not already exist.

Defaults to false.

callback

GetTopicCallback

Yes

Callback function.

Returns

Promise containing GetTopicResponse 

getMetadata([gaxOpts][, callback]) → Promise containing GetTopicMetadataResponse

Get the official representation of this topic from the API.

Example

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

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

topic.getMetadata((err, apiResponse) => {});

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

Parameters

Name Type Optional Description

gaxOpts

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.

callback

GetTopicMetadataCallback

Yes

Callback function.

See also

Topics: get API Documentation

Returns

Promise containing GetTopicMetadataResponse 

getSubscriptions([query][, callback]) → Promise containing GetSubscriptionsResponse

Get a list of the subscriptions registered to this topic. You may optionally provide a query object as the first argument to customize the response.

Your provided callback will be invoked with an error object if an API error occurred or an array of {module:pubsub/subscription} objects.

Example

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

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

topic.getSubscriptions((err, subscriptions) => {
  // subscriptions is an array of `Subscription` objects.
});

// Customize the query.
topic.getSubscriptions({
  pageSize: 3
}, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.getSubscriptions().then((data) => {
  const subscriptions = data[0];
});

Parameters

Name Type Optional Description

query

GetSubscriptionsRequest

Yes

Query object for listing subscriptions.

callback

GetSubscriptionsCallback

Yes

Callback function.

See also

Subscriptions: list API Documentation

Returns

Promise containing GetSubscriptionsResponse 

publish(data[, attributes][, callback]) → Promise containing PublishResponse

Publish the provided message.

Example

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

const topic = pubsub.topic('my-topic');
const data = Buffer.from('Hello, world!');

const callback = (err, messageId) => {
  if (err) {
    // Error handling omitted.
  }
};

topic.publish(data, callback);

//-
// Optionally you can provide an object containing attributes for the
// message. Note that all values in the object must be strings.
//-
const attributes = {
  key: 'value'
};

topic.publish(data, attributes, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.publish(data).then((messageId) => {});

Parameters

Name Type Optional Description

data

buffer

 

The message data. This must come in the form of a Buffer object.

attributes

Object with string properties

Yes

Attributes for this message.

callback

PublishCallback

Yes

Callback function.

Throws

TypeError 

If data is not a Buffer object.

TypeError 

If any value in attributes object is not a string.

Returns

Promise containing PublishResponse 

publishJSON(json[, attributes][, callback]) → Promise containing PublishResponse

Publish the provided JSON. It should be noted that all messages published are done so in the form of a Buffer. This is simply a convenience method that will transform JSON into a Buffer before publishing. Subscription objects will always return message data in the form of a Buffer, so any JSON published will require manual deserialization.

Example

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

const data = {
  foo: 'bar'
};

const callback = (err, messageId) => {
  if (err) {
    // Error handling omitted.
  }
};

topic.publishJSON(data, callback);

//-
// Optionally you can provide an object containing attributes for the
// message. Note that all values in the object must be strings.
//-
const attributes = {
  key: 'value'
};

topic.publishJSON(data, attributes, callback);

//-
// If the callback is omitted, we'll return a Promise.
//-
topic.publishJSON(data).then((messageId) => {});

Parameters

Name Type Optional Description

json

object

 

The JSON data to publish.

attributes

object

Yes

Attributes for this message.

callback

PublishCallback

Yes

Callback function.

See also
Topic#publish
Throws

Error 

If non-object data is provided.

Returns

Promise containing PublishResponse 

setMetadata(metadata[, gaxOpts][, callback]) → Promise containing SetTopicMetadataResponse

Updates the topic.

Examples

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

const topic = pubsub.topic('my-topic');
const metadata = {
  labels: {foo: 'bar'}
};

topic.setMetadata(metadata, err => {
  if (err) {
    // Error handling omitted.
  }
});
<caption>If the callback is omitted, we'll return a
Promise.</caption>
topic.setMetadata(metadata).then((data) => {
  const apiResponse = data[0];
});

Parameters

Name Type Optional Description

metadata

object

 

The fields to update. This should be structured like a Topic object.

gaxOpts

object

Yes

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.

callback

SetTopicMetadataCallback

Yes

Callback function.

See also

UpdateTopicRequest API Documentation

Returns

Promise containing SetTopicMetadataResponse 

setPublishOptions(options)

Set the publisher options.

Example

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

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

topic.setPublishOptions({
  batching: {
    maxMilliseconds: 10
  }
});

Parameter

Name Type Optional Description

options

PublishOptions

 

The publisher options.

subscription(name[, options]) → Subscription

Create a Subscription object. This command by itself will not run any API requests. You will receive a {module:pubsub/subscription} object, which will allow you to interact with a subscription.

Example

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

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

// Register a listener for `message` events.
subscription.on('message', (message) => {
  // Called every time a message is received.
  // message.id = ID of the message.
  // message.ackId = ID used to acknowledge the message receival.
  // message.data = Contents of the message.
  // message.attributes = Attributes of the message.
  // message.publishTime = Timestamp when Pub/Sub received the message.
});

Parameters

Name Type Optional Description

name

string

 

Name of the subscription.

options

object

Yes

Configuration object.

Values in options have the following properties:

Name Type Optional Description

flowControl

object

Yes

Flow control configurations for receiving messages. Note that these options do not persist across subscription instances.

flowControl.maxBytes

number

Yes

The maximum number of bytes in un-acked messages to allow before the subscription pauses incoming messages. Defaults to 20% of free memory.

flowControl.maxMessages

number

Yes

The maximum number of un-acked messages to allow before the subscription pauses incoming messages.

Defaults to Infinity.

maxConnections

number

Yes

Use this to limit the number of connections to be used when sending and receiving messages.

Defaults to 5.

Throws

Error 

If subscription name is omitted.

Returns

Subscription