Topic - Documentation

Constructor

new Topic(pubsub, name)

Parameters:

Name	Type	Description
`pubsub`	PubSub	PubSub object.
`name`	string	Name of the topic.

Source:

topic.js, line 37

Example

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

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

Members

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:

Source:

topic.js, line 61

See:

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];
});

name :string

The fully qualified name of this topic.

Source:

topic.js, line 42

parent :PubSub

The parent PubSub instance of this topic instance.

Source:

topic.js, line 54

pubsub :PubSub

The parent PubSub instance of this topic instance.

Source:

topic.js, line 49

Methods

create(gaxOptsopt, callbackopt) → {Promise.<CreateTopicResponse>}

Create a topic.

Parameters:

Name	Type	Attributes	Description
`gaxOpts`	object	<optional>	Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
`callback`	CreateTopicCallback	<optional>	Callback function.

Source:

topic.js, line 132

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];
});

createSubscription(name, optionsopt, callbackopt) → {Promise.<CreateSubscriptionResponse>}

Create a subscription to this topic.

Parameters:

Name	Type	Attributes	Description
`name`	string		The name of the subscription.
`options`	CreateSubscriptionRequest	<optional>	See a Subscription resource.
`callback`	CreateSubscriptionCallback	<optional>	Callback function.

Source:

topic.js, line 174

See:

Subscriptions: create API Documentation

Throws:

If subscription name is omitted.
Type Error

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];
});

delete(gaxOptsopt, callbackopt)

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

Parameters:

Name Type Attributes Description

gaxOpts

object

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

callback

function

The callback function.

Properties

Name	Type	Attributes	Description
`err`	error	<nullable>	An error returned while making this request.
`apiResponse`	object		Raw API response.

Source:

topic.js, line 206

See:

Topics: delete API Documentation

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];
});

exists(callbackopt) → {Promise.<TopicExistsResponse>}

Check if a topic exists.

Parameters:

Name	Type	Attributes	Description
`callback`	TopicExistsCallback	<optional>	Callback function.

Source:

topic.js, line 249

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];
});

get(gaxOptsopt, callbackopt) → {Promise.<GetTopicResponse>}

Get a topic if it exists.

Parameters:

Name Type Attributes Description

gaxOpts

object

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

Properties

Name	Type	Attributes	Default	Description
`autoCreate`	boolean	<optional>	false	Automatically create the topic does not already exist.

callback

GetTopicCallback

Callback function.

Source:

topic.js, line 301

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];
});

getMetadata(gaxOptsopt, callbackopt) → {Promise.<GetTopicMetadataResponse>}

Get the official representation of this topic from the API.

Parameters:

Name	Type	Attributes	Description
`gaxOpts`	object	<optional>	Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
`callback`	GetTopicMetadataCallback	<optional>	Callback function.

Source:

topic.js, line 352

See:

Topics: get API Documentation

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];
});

getSubscriptions(queryopt, callbackopt) → {Promise.<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.

Parameters:

Name	Type	Attributes	Description
`query`	GetSubscriptionsRequest	<optional>	Query object for listing subscriptions.
`callback`	GetSubscriptionsCallback	<optional>	Callback function.

Source:

topic.js, line 406

See:

Subscriptions: list API Documentation

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];
});

publish(data, attributesopt, callbackopt) → {Promise.<PublishResponse>}

Publish the provided message.

Parameters:

Name	Type	Attributes	Description
`data`	buffer		The message data. This must come in the form of a Buffer object.
`attributes`	object.<string, string>	<optional>	Attributes for this message.
`callback`	PublishCallback	<optional>	Callback function.

Source:

topic.js, line 472

Throws:

If data is not a Buffer object.

Type

TypeError
If any value in attributes object is not a string.

Type

TypeError

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) => {});

publishJSON(json, attributesopt, callbackopt) → {Promise.<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.

Parameters:

Name	Type	Attributes	Description
`json`	object		The JSON data to publish.
`attributes`	object	<optional>	Attributes for this message.
`callback`	PublishCallback	<optional>	Callback function.

Source:

topic.js, line 525

See:

Topic#publish

Throws:

If non-object data is provided.
Type Error

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) => {});

setMetadata(metadata, gaxOptsopt, callbackopt) → {Promise.<SetTopicMetadataResponse>}

Updates the topic.

Parameters:

Name	Type	Attributes	Description
`metadata`	object		The fields to update. This should be structured like a Topic object.
`gaxOpts`	object	<optional>	Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
`callback`	SetTopicMetadataCallback	<optional>	Callback function.

Source:

topic.js, line 578

See:

UpdateTopicRequest API Documentation

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.
  }
});

If the callback is omitted, we'll return a Promise.

topic.setMetadata(metadata).then((data) => {
  const apiResponse = data[0];
});

setPublishOptions(options)

Set the publisher options.

Parameters:

Name	Type	Description
`options`	PublishOptions	The publisher options.

Source:

topic.js, line 608

Example

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

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

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

subscription(name, optionsopt) → {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.

Parameters:

Name	Type	Attributes	Description
`name`	string		Name of the subscription.
`options`	SubscriberOptions	<optional>	Configuration object.

Source:

topic.js, line 639

Throws:

If subscription name is omitted.
Type Error

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.
});