Subscription - Documentation

Constructor

new Subscription(pubsub, name, optionsopt)

Parameters:

Name	Type	Attributes	Description
`pubsub`	PubSub		PubSub object.
`name`	string		The name of the subscription.
`options`	SubscriberOptions	<optional>	Options for handling messages.

Source:

subscription.js, line 152

Examples

From PubSub#getSubscriptions

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

pubsub.getSubscriptions((err, subscriptions) => {
  // `subscriptions` is an array of Subscription objects.
});

From Topic#getSubscriptions

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

Topic#createSubscription

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

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

To apply a fine level of flow control, consider the following configuration

const subscription = topic.subscription('my-sub', {
  flowControl: {
    maxMessages: 1,
    // this tells the client to manage and lock any excess messages
    allowExcessMessages: false
  }
});

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:

subscription.js, line 159

See:

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.

Source:

subscription.js, line 208

projectId :string

Source:

subscription.js, line 214

Methods

close(callbackopt)

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

Parameters:

Name Type Attributes Description

callback

function

The callback function.

Properties

Name	Type	Attributes	Description
`err`	error	<nullable>	An error returned while closing the Subscription.

Source:

subscription.js, line 236

Example

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

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

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

Create a subscription.

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:

subscription.js, line 271

See:

Subscriptions: create API Documentation

Throws:

If subscription name is omitted.
Type Error

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(name, gaxOptsopt, callbackopt) → {Promise.<CreateSnapshotResponse>}

Create a snapshot with the given name.

Parameters:

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

Source:

subscription.js, line 330

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(gaxOptsopt, callbackopt)

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

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:

subscription.js, line 384

See:

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(callbackopt) → {Promise.<SubscriptionExistsResponse>}

Check if a subscription exists.

Parameters:

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

Source:

subscription.js, line 431

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(gaxOptsopt, callbackopt) → {Promise.<GetSubscriptionResponse>}

Get a subscription 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 subscription if it does not already exist.

callback

GetSubscriptionCallback

Callback function.

Source:

subscription.js, line 484

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(gaxOptsopt, callbackopt) → {Promise.<GetSubscriptionMetadataResponse>}

Fetches the subscriptions metadata.

Parameters:

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

Source:

subscription.js, line 538

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(config, gaxOptsopt, callbackopt) → {Promise.<ModifyPushConfigResponse>}

Modify the push config for the subscription.

Parameters:

Name Type Attributes Description

config

object

The push config.

Properties

Name	Type	Description
`pushEndpoint`	string	A URL locating the endpoint to which messages should be published.
`attributes`	object	PushConfig attributes.

gaxOpts

object

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

callback

ModifyPushConfigCallback

Callback function.

Source:

subscription.js, line 604

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()

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.

Source:

subscription.js, line 639

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(snapshot, gaxOptsopt, callbackopt) → {Promise.<SeekResponse>}

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

Parameters:

Name	Type	Attributes	Description
`snapshot`	string \| date		The point to seek to. This will accept the name of the snapshot or a Date object.
`gaxOpts`	object	<optional>	Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html.
`callback`	SeekCallback	<optional>	Callback function.

Source:

subscription.js, line 681

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(metadata, gaxOptsopt, callbackopt) → {Promise.<SetSubscriptionMetadataResponse>}

Update the subscription object.

Parameters:

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

Source:

subscription.js, line 739

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(options)

Sets the Subscription options.

Parameters:

Name	Type	Description
`options`	SubscriberOptions	The options.

Source:

subscription.js, line 763

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:

subscription.js, line 778

Throws:

If a name is not provided.
Type Error

Example

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