@google-cloud/pubsub 0.17.0 » Class: Subscription

Subscription

class

Constructor

Subscription

new Subscription(pubsub, name, options)

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

Subscriptions are sometimes retrieved when using various methods:

• Pubsub#getSubscriptions
• Topic#getSubscriptions
• Topic#createSubscription

Subscription objects may be created directly with:

• Topic#subscription

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.

Parameter
pubsub	PubSub PubSub object.
name	string The name of the subscription.
options	Optional object See a Subscription resource Values in options have the following properties: Parameter flowControl Optional object Flow control configurations for receiving messages. Note that these options do not persist across subscription instances. flowControl.maxBytes Optional number The maximum number of bytes in un-acked messages to allow before the subscription pauses incoming messages. Defaults to 20% of free memory. flowControl.maxMessages Optional number The maximum number of un-acked messages to allow before the subscription pauses incoming messages. Default: Infinity. maxConnections Optional number Use this to limit the number of connections to be used when sending and receiving messages. Default: 5.

Example

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

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

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

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

//-
// From {@link Topic#subscription}:
//-
var topic = pubsub.topic('my-topic');
var 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', function(err) {});

// 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.timestamp = Timestamp 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);

Property

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(function(err, policy) {
  console.log(policy);
});

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

Methods

close

close(callback)

Closes the subscription, once this is called you will no longer receive message events unless you add a new message listener.

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(function(err) {
  if (err) {
    // Error handling omitted.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
subscription.close().then(function() {});

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 = function(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(function(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(function(err, apiResponse) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
subscription.delete().then(function(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(function(err, exists) {});

//-
// If the callback is omitted, we'll return a Promise.
//-
subscription.exists().then(function(data) {
  var 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(function(err, subscription, apiResponse) {
  // The `subscription` data has been populated.
});

//-
// If the callback is omitted, we'll return a Promise.
//-
subscription.get().then(function(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(function(err, apiResponse) {
  if (err) {
    // Error handling omitted.
  }
});

//-
// If the callback is omitted, we'll return a Promise.
//-
subscription.getMetadata().then(function(data) {
  var 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');

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

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

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

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

var callback = function(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.
//-
var 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

var metadata = {
  key: 'value'
};

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

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

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

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