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

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

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