Constructor

Topic

new Topic(pubsub, name)

A Topic object allows you to interact with a Cloud Pub/Sub topic.

Parameter

pubsub

PubSub

PubSub object.

name

string

Name of the topic.

Example

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

const topic = pubsub.topic('my-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.

Mixes in
IAM
See also

Access Control Overview

What is Cloud IAM?

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(function(err, policy) {
  console.log(policy);
});

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

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

create(gaxOpts, callback) returns Promise containing CreateTopicResponse

Create a topic.

Parameter

gaxOpts

Optional

object

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

callback

Optional

CreateTopicCallback

Callback function.

Returns

Promise containing CreateTopicResponse 

Example

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

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

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

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

createSubscription

createSubscription(name, options, callback) returns Promise containing CreateSubscriptionResponse

Create a subscription to this topic.

Parameter

name

string

The name of the subscription.

options

Optional

CreateSubscriptionRequest

See a Subscription resource.

callback

Optional

CreateSubscriptionCallback

Callback function.

See also

Subscriptions: create API Documentation

Throws

Error 

If subscription name is omitted.

Returns

Promise containing CreateSubscriptionResponse 

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', {
  ackDeadline: 90000 // 90 seconds
}, callback);

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

delete

delete(gaxOpts, callback)

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

Parameter

gaxOpts

Optional

object

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

callback

Optional

function()

The callback function.

See also

Topics: delete API Documentation

Example

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

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

topic.delete(function(err, apiResponse) {});

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

exists

exists(callback) returns Promise containing TopicExistsResponse

Check if a topic exists.

Parameter

callback

Optional

TopicExistsCallback

Callback function.

Returns

Promise containing TopicExistsResponse 

Example

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

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

topic.exists(function(err, exists) {});

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

get

get(gaxOpts, callback) returns Promise containing GetTopicResponse

Get a topic if it exists.

Parameter

gaxOpts

Optional

object

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

callback

Optional

GetTopicCallback

Callback function.

Returns

Promise containing GetTopicResponse 

Example

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

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

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

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

getMetadata

getMetadata(gaxOpts, callback) returns Promise containing GetTopicMetadataResponse

Get the official representation of this topic from the API.

Parameter

gaxOpts

Optional

object

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

callback

Optional

GetTopicMetadataCallback

Callback function.

See also

Topics: get API Documentation

Returns

Promise containing GetTopicMetadataResponse 

Example

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

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

topic.getMetadata(function(err, apiResponse) {});

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

getSubscriptions

getSubscriptions(query, callback) returns 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.

Parameter

query

Optional

GetSubscriptionsRequest

Query object for listing subscriptions.

callback

Optional

GetSubscriptionsCallback

Callback function.

See also

Subscriptions: list API Documentation

Returns

Promise containing GetSubscriptionsResponse 

Example

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

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

topic.getSubscriptions(function(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(function(data) {
  const subscriptions = data[0];
});

publisher

publisher(options)

Creates a Publisher object that allows you to publish messages to this topic.

Parameter

options

Optional

object

Configuration object.

Example

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

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

publisher.publish(Buffer.from('Hello, world!'), function(err, messageId) {
  if (err) {
    // Error handling omitted.
  }
});

subscription

subscription(name, options) returns 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.

Parameter

name

string

Name of the subscription.

options

Optional

object

Configuration object.

Throws

Error 

If subscription name is omitted.

Returns

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', function(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.
});