Class Topic (4.4.0)

Package

Examples

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

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

To enable message ordering, set enableMessageOrdering to true. Please note that this does not persist to an actual topic.

const topic = pubsub.topic('ordered-topic', {enableMessageOrdering: true});

Constructors

(constructor)(pubsub, name, options)

constructor(pubsub: PubSub, name: string, options?: PublishOptions);

Properties

getSubscriptionsStream

getSubscriptionsStream: () => ObjectStream<Subscription>;

iam

iam: IAM;

metadata

metadata?: TopicMetadata;

name

name: string;

parent

parent: PubSub;

publisher

publisher: Publisher;

pubsub

pubsub: PubSub;

request

request: typeof PubSub.prototype.request;

Methods

create(gaxOpts)

create(gaxOpts?: CallOptions): Promise<CreateTopicResponse>;

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

create(callback)

create(callback: CreateTopicCallback): void;

create(gaxOpts, callback)

create(gaxOpts: CallOptions, callback: CreateTopicCallback): void;

createSubscription(name, callback)

createSubscription(name: string, callback: CreateSubscriptionCallback): void;

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

createSubscription(name, options)

createSubscription(name: string, options?: CreateSubscriptionOptions): Promise<CreateSubscriptionResponse>;

createSubscription(name, options, callback)

createSubscription(name: string, options: CreateSubscriptionOptions, callback: CreateSubscriptionCallback): void;

delete(callback)

delete(callback: EmptyCallback): void;

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

delete(gaxOpts)

delete(gaxOpts?: CallOptions): Promise<EmptyResponse>;

delete(gaxOpts, callback)

delete(gaxOpts: CallOptions, callback: EmptyCallback): void;

exists()

exists(): Promise<ExistsResponse>;

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

exists(callback)

exists(callback: ExistsCallback): void;

flowControlled()

flowControlled(): FlowControlledPublisher;

flush()

flush(): Promise<void>;

flush(callback)

flush(callback: EmptyCallback): void;

formatName_(projectId, name)

static formatName_(projectId: string, name: string): string;

get(callback)

get(callback: GetTopicCallback): void;

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

get(gaxOpts)

get(gaxOpts?: GetTopicOptions): Promise<GetTopicResponse>;

get(gaxOpts, callback)

get(gaxOpts: GetTopicOptions, callback: GetTopicCallback): void;

getMetadata(callback)

getMetadata(callback: GetTopicMetadataCallback): void;

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

getMetadata(gaxOpts, callback)

getMetadata(gaxOpts: CallOptions, callback: GetTopicMetadataCallback): void;

getMetadata(gaxOpts)

getMetadata(gaxOpts?: CallOptions): Promise<GetTopicMetadataResponse>;

getPublishOptionDefaults()

getPublishOptionDefaults(): PublishOptions;

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

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

const defaults = topic.getPublishOptionDefaults();
defaults.batching.maxMilliseconds = 10;
topic.setPublishOptions(defaults);

getSubscriptions(callback)

getSubscriptions(callback: GetTopicSubscriptionsCallback): void;

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

getSubscriptions(options, callback)

getSubscriptions(options: PageOptions, callback: GetTopicSubscriptionsCallback): void;

getSubscriptions(options)

getSubscriptions(options?: PageOptions): Promise<GetTopicSubscriptionsResponse>;

publish(data, attributes)

publish(data: Buffer, attributes?: Attributes): Promise<string>;

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

publish(data, callback)

publish(data: Buffer, callback: PublishCallback): void;

publish(data, attributes, callback)

publish(data: Buffer, attributes: Attributes, callback: PublishCallback): void;

publishJSON(json, attributes)

publishJSON(json: object, attributes?: Attributes): Promise<string>;

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

publishJSON(json, callback)

publishJSON(json: object, callback: PublishCallback): void;

publishJSON(json, attributes, callback)

publishJSON(json: object, attributes: Attributes, callback: PublishCallback): void;

publishMessage(message)

publishMessage(message: MessageOptions): Promise<string>;

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.publishMessage({data}, callback);

Publish JSON message data.

const json = {foo: 'bar'};

topic.publishMessage({json}, callback);

To publish messages in order (this is still experimental), make sure message ordering is enabled and provide an ordering key

const topic = pubsub.topic('ordered-topic', {messageOrdering: true});
const orderingKey = 'my-key';

topic.publishMessage({data, orderingKey}, callback);

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

const messageId = await topic.publishMessage({data});

publishMessage(message, callback)

publishMessage(message: MessageOptions, callback: PublishCallback): void;

resumePublishing(orderingKey)

resumePublishing(orderingKey: string): void;

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

const orderingKey = 'foo';
const data = Buffer.from('Hello, order!');

topic.publishMessage({data, orderingKey}, err => {
  if (err) {
    topic.resumePublishing(orderingKey);
  }
});

setMetadata(options, gaxOpts)

setMetadata(options: TopicMetadata, gaxOpts?: CallOptions): Promise<SetTopicMetadataResponse>;

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

setMetadata(options, callback)

setMetadata(options: TopicMetadata, callback: SetTopicMetadataCallback): void;

setMetadata(options, gaxOpts, callback)

setMetadata(options: TopicMetadata, gaxOpts: CallOptions, callback: SetTopicMetadataCallback): void;

setPublishOptions(options)

setPublishOptions(options: PublishOptions): void;

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

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

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

subscription(name, options)

subscription(name: string, options?: SubscriptionOptions): Subscription;

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