Subscription
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:
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 object. |
||||||||||
name |
string The name of the subscription. |
||||||||||
options |
Optional object See a Subscription resource Values in
|
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
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
|
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 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
|
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 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
|
||||
callback |
Optional 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
|
||||||
gaxOpts |
Optional object Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html. |
||||||
callback |
Optional 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 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
Example
var snapshot = subscription.snapshot('my-snapshot');