PubSub

PubSub

Cloud Pub/Sub is a reliable, many-to-many, asynchronous messaging service from Cloud Platform.

Constructor

new PubSub(optionsopt)

Parameters:
Name Type Attributes Description
options ClientConfig <optional>

Configuration options.
Source:
See:
Examples

Import the client library 

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

Create a client that uses Application Default Credentials (ADC): 

const pubsub = new PubSub();

Create a client with explicit credentials: 

const pubsub = new PubSub({
  projectId: 'your-project-id',
  keyFilename: '/path/to/keyfile.json'
});

include:samples/quickstart.js 

region_tag:pubsub_quickstart_create_topic
Full quickstart example:

Members

(static) v1 :object

Reference to internal generated clients, advanced use only.

Properties:
Name Type Description
PublisherClient constructor

Reference to v1.PublisherClient.
SubscriberClient constructor

Reference to v1.SubscriberClient.
Source:
See:

isEmulator :boolean

Source:

Methods

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

Create a subscription to a topic.

Parameters:
Name Type Attributes Description
topic Topic | string

The Topic to create a subscription to.
name string

The name of the subscription.
options CreateSubscriptionRequest <optional>

See a Subscription resource.
callback CreateSubscriptionCallback <optional>

Callback function.
Source:
See:
Throws:

  • If a Topic instance or topic name is not provided.

    Type
    Error

  • If a subscription name is not provided.

    Type
    Error
Examples

Subscribe to a topic. 

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

const topic = 'messageCenter';
const name = 'newMessages';

const callback = function(err, subscription, apiResponse) {};

pubsub.createSubscription(topic, name, callback);

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

pubsub.createSubscription(topic, name)
  .then(function(data) {
    const subscription = data[0];
    const apiResponse = data[1];
  });

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

Create a topic with the given name.

Parameters:
Name Type Attributes Description
name string

Name of the topic.
gaxOpts object <optional>

Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
callback CreateTopicCallback <optional>

Callback function.
Source:
See:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.createTopic('my-new-topic', function(err, topic, apiResponse) {
  if (!err) {
    // The topic was created successfully.
  }
});

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

getSnapshots(queryopt, callbackopt) → {Promise.<GetSnapshotsResponse>}

Get a list of snapshots.

Parameters:
Name Type Attributes Description
query GetSnapshotsRequest <optional>

Query object for listing snapshots.
callback GetSnapshotsCallback <optional>

Callback function.
Source:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getSnapshots(function(err, snapshots) {
  if (!err) {
    // snapshots is an array of Snapshot objects.
  }
});

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

getSnapshotsStream(optionsopt) → {ReadableStream}

Get a list of the Snapshot objects as a readable object stream.

Parameters:
Name Type Attributes Description
options GetSnapshotsRequest <optional>

Configuration object. See PubSub#getSnapshots for a complete list of options.
Source:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getSnapshotsStream()
  .on('error', console.error)
  .on('data', function(snapshot) {
    // snapshot is a Snapshot object.
  })
  .on('end', function() {
    // All snapshots retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
pubsub.getSnapshotsStream()
  .on('data', function(snapshot) {
    this.end();
  });

getSubscriptions(queryopt, callbackopt) → {Promise.<GetSubscriptionsResponse>}

Get a list of the subscriptions registered to all of your project's topics. 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 Subscription objects.

To get subscriptions for a topic, see Topic.

Parameters:
Name Type Attributes Description
query GetSubscriptionsRequest <optional>

Query object for listing subscriptions.
callback GetSubscriptionsCallback <optional>

Callback function.
Source:
See:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getSubscriptions(function(err, subscriptions) {
  if (!err) {
    // subscriptions is an array of Subscription objects.
  }
});

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

getSubscriptionsStream(optionsopt) → {ReadableStream}

Get a list of the Subscription objects registered to all of your project's topics as a readable object stream.

Parameters:
Name Type Attributes Description
options GetSubscriptionsRequest <optional>

Configuration object. See PubSub#getSubscriptions for a complete list of options.
Source:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getSubscriptionsStream()
  .on('error', console.error)
  .on('data', function(subscription) {
    // subscription is a Subscription object.
  })
  .on('end', function() {
    // All subscriptions retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
pubsub.getSubscriptionsStream()
  .on('data', function(subscription) {
    this.end();
  });

getSubscriptionsStream(optionsopt) → {ReadableStream}

Get a list of the {module:pubsub/subscription} objects registered to this topic as a readable object stream.

Parameters:
Name Type Attributes Description
options GetSubscriptionsRequest <optional>

Configuration object. See PubSub#getSubscriptions for a complete list of options.
Source:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

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

topic.getSubscriptionsStream()
  .on('error', console.error)
  .on('data', (subscription) => {
    // subscription is a Subscription object.
  })
  .on('end', () => {
    // All subscriptions retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
topic.getSubscriptionsStream()
  .on('data', function(subscription) {
    this.end();
  });

getTopics(queryopt, callbackopt) → {Promise.<GetTopicsResponse>}

Get a list of the topics registered to your project. You may optionally provide a query object as the first argument to customize the response.

Parameters:
Name Type Attributes Description
query GetTopicsRequest <optional>

Query object for listing topics.
callback GetTopicsCallback <optional>

Callback function.
Source:
See:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getTopics(function(err, topics) {
  if (!err) {
    // topics is an array of Topic objects.
  }
});

//-
// Customize the query.
//-
pubsub.getTopics({
  pageSize: 3
}, function(err, topics) {});

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

getTopicsStream(optionsopt) → {ReadableStream}

Get a list of the {module:pubsub/topic} objects registered to your project as a readable object stream.

Parameters:
Name Type Attributes Description
options GetTopicsRequest <optional>

Configuration object. See PubSub#getTopics for a complete list of options.
Source:
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();

pubsub.getTopicsStream()
  .on('error', console.error)
  .on('data', function(topic) {
    // topic is a Topic object.
  })
  .on('end', function() {
    // All topics retrieved.
  });

//-
// If you anticipate many results, you can end a stream early to prevent
// unnecessary processing and API requests.
//-
pubsub.getTopicsStream()
  .on('data', function(topic) {
    this.end();
  });

snapshot(name) → {Snapshot}

Create a Snapshot object. See Subscription#createSnapshot to create a snapshot.

Parameters:
Name Type Description
name string

The name of the snapshot.
Source:
Throws:

If a name is not provided.

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

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

subscription(name, optionsopt) → {Subscription}

Create a Subscription object. This command by itself will not run any API requests. You will receive a 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:
Throws:

If subscription name is omitted.

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

const subscription = pubsub.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 = Date when Pub/Sub received the message.
});

topic(name) → {Topic}

Create a Topic object. See PubSub#createTopic to create a topic.

Parameters:
Name Type Description
name string

The name of the topic.
Source:
Throws:

If a name is not provided.

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

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