Subscription

class

A Subscription object will give you access to your Cloud Pub/Sub subscription.

Subscriptions are sometimes retrieved when using various methods:

Subscription objects may be created directly with:

All Subscription objects are instances of an EventEmitter. The subscription will pull for messages automatically as long as there is at least one listener assigned for the message event.

By default Subscription objects allow you to process 100 messages at the same time. You can fine tune this value by adjusting the options.flowControl.maxMessages option.

If your subscription is seeing more re-deliveries than preferable, you might try increasing your options.ackDeadline value or decreasing the options.streamingOptions.maxStreams value.

Subscription objects handle ack management, by automatically extending the ack deadline while the message is being processed, to then issue the ack or nack of such message when the processing is done. Note: message redelivery is still possible.

Constructor

Subscription

new Subscription(pubsub, name, options)

Parameter

pubsub

PubSub

PubSub object.

name

string

The name of the subscription.

options

Optional

SubscriberOptions

Options for handling messages.

Example 

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

//-
// From {@link PubSub#getSubscriptions}:
//-
pubsub.getSubscriptions((err, subscriptions) => {
  // `subscriptions` is an array of Subscription objects.
});

//-
// From {@link Topic#getSubscriptions}:
//-
const topic = pubsub.topic('my-topic');
topic.getSubscriptions((err, subscriptions) => {
  // `subscriptions` is an array of Subscription objects.
});

//-
// From {@link Topic#createSubscription}:
//-
const topic = pubsub.topic('my-topic');
topic.createSubscription('new-subscription', (err, subscription) => {
  // `subscription` is a Subscription object.
});

//-
// From {@link Topic#subscription}:
//-
const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');
// `subscription` is a Subscription object.

//-
// Once you have obtained a subscription object, you may begin to register
// listeners. This will automatically trigger pulling for messages.
//-

// Register an error handler.
subscription.on('error', (err) => {});

// Register a close handler in case the subscriber closes unexpectedly
subscription.on('close', () => {});

// Register a listener for `message` events.
function onMessage(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.

  // Ack the message:
  // message.ack();

  // This doesn't ack the message, but allows more messages to be retrieved
  // if your limit was hit or if you don't want to ack the message.
  // message.nack();
}
subscription.on('message', onMessage);

// Remove the listener from receiving `message` events.
subscription.removeListener('message', onMessage);

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 

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

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

isOpen

boolean

Indicates if the Subscription is open and receiving messages.

projectId

string

Methods

close

close(callback)

Closes the Subscription, once this is called you will no longer receive message events unless you call {Subscription#open} or add new message listeners.

Parameter

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while closing the Subscription.

Value may be null.

Example 

subscription.close(err => {
  if (err) {
    // Error handling omitted.
  }
});

// If the callback is omitted a Promise will be returned.
subscription.close().then(() => {});

create

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

Create a subscription.

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 

Examples 

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

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

subscription.create(callback);

With options

subscription.create({
  ackDeadlineSeconds: 90
}, callback);
<caption>If the callback is omitted, we'll return a
Promise.</caption> const [sub, apiResponse] = await subscription.create();

createSnapshot

createSnapshot(name, gaxOpts, callback) returns Promise containing CreateSnapshotResponse

Create a snapshot with the given name.

Parameter

name

string

Name of the snapshot.

gaxOpts

Optional

object

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

callback

Optional

CreateSnapshotCallback

Callback function.
Returns

Promise containing CreateSnapshotResponse 

Example 

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

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

const callback = (err, snapshot, apiResponse) => {
  if (!err) {
    // The snapshot was created successfully.
  }
};

subscription.createSnapshot('my-snapshot', callback);

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

delete

delete(gaxOpts, callback)

Delete the subscription. Pull requests from the current subscription will be errored once unsubscription is complete.

Parameter

gaxOpts

Optional

object

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

callback

Optional

function()

The callback function.

Values in callback have the following properties:

Parameter

err

error

An error returned while making this request.

Value may be null.

apiResponse

object

Raw API response.
See also

Subscriptions: delete API Documentation

Example 

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

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

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

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

exists

exists(callback) returns Promise containing SubscriptionExistsResponse

Check if a subscription exists.

Parameter

callback

Optional

SubscriptionExistsCallback

Callback function.
Returns

Promise containing SubscriptionExistsResponse 

Example 

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

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

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

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

get

get(gaxOpts, callback) returns Promise containing GetSubscriptionResponse

Get a subscription if it exists.

Parameter

gaxOpts

Optional

object

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

Values in gaxOpts have the following properties:

Parameter

autoCreate

Optional

boolean

Automatically create the subscription if it does not already exist.

callback

Optional

GetSubscriptionCallback

Callback function.
Returns

Promise containing GetSubscriptionResponse 

Example 

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

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

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

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

getMetadata

getMetadata(gaxOpts, callback) returns Promise containing GetSubscriptionMetadataResponse

Fetches the subscriptions metadata.

Parameter

gaxOpts

Optional

object

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

callback

Optional

GetSubscriptionMetadataCallback

Callback function.
Returns

Promise containing GetSubscriptionMetadataResponse 

Example 

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

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

subscription.getMetadata((err, apiResponse) => {
  if (err) {
    // Error handling omitted.
  }
});

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

modifyPushConfig

modifyPushConfig(config, gaxOpts, callback) returns Promise containing ModifyPushConfigResponse

Modify the push config for the subscription.

Parameter

config

object

The push config.

Values in config have the following properties:

Parameter

pushEndpoint

string

A URL locating the endpoint to which messages should be published.

attributes

object

PushConfig attributes.

gaxOpts

Optional

object

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

callback

Optional

ModifyPushConfigCallback

Callback function.
Returns

Promise containing ModifyPushConfigResponse 

Example 

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

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

const pushConfig = {
  pushEndpoint: 'https://mydomain.com/push',
  attributes: {
    key: 'value'
  }
};

subscription.modifyPushConfig(pushConfig, (err, apiResponse) => {
  if (err) {
    // Error handling omitted.
  }
});

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

open

open()

Opens the Subscription to receive messages. In general this method shouldn't need to be called, unless you wish to receive messages after calling Subscription#close. Alternatively one could just assign a new message event listener which will also re-open the Subscription.

Example 

subscription.on('message', message => message.ack());

// Close the subscription.
subscription.close(err => {
  if (err) {
    // Error handling omitted.
  }

  The subscription has been closed and messages will no longer be received.
});

// Resume receiving messages.
subscription.open();

seek

seek(snapshot, gaxOpts, callback) returns Promise containing SeekResponse

Seeks an existing subscription to a point in time or a given snapshot.

Parameter

snapshot

(string or date)

The point to seek to. This will accept the name of the snapshot or a Date object.

gaxOpts

Optional

object

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

callback

Optional

SeekCallback

Callback function.
Returns

Promise containing SeekResponse 

Example 

const callback = (err, resp) => {
  if (!err) {
    // Seek was successful.
  }
};

subscription.seek('my-snapshot', callback);

//-
// Alternatively, to specify a certain point in time, you can provide a
Date
// object.
//-
const date = new Date('October 21 2015');

subscription.seek(date, callback);

setMetadata

setMetadata(metadata, gaxOpts, callback) returns Promise containing SetSubscriptionMetadataResponse

Update the subscription object.

Parameter

metadata

object

The subscription metadata.

gaxOpts

Optional

object

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

callback

Optional

SetSubscriptionMetadataCallback

Callback function.
Returns

Promise containing SetSubscriptionMetadataResponse 

Example 

const metadata = {
  key: 'value'
};

subscription.setMetadata(metadata, (err, apiResponse) => {
  if (err) {
    // Error handling omitted.
  }
});

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

setOptions

setOptions(options)

Sets the Subscription options.

Parameter

options

SubscriberOptions

The options.

snapshot

snapshot(name) returns Snapshot

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

Parameter

name

string

The name of the snapshot.
Throws

Error 

If a name is not provided.

Returns

Snapshot 

Example 

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