Topic
A Topic object allows you to interact with a Cloud Pub/Sub topic.
Constructor
Topic
new Topic(pubsub, name)
Parameter |
|
---|---|
pubsub |
PubSub object. |
name |
string Name of the topic. |
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
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
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
//-
// Get the IAM policy for your topic.
//-
topic.iam.getPolicy((err, policy) => {
console.log(policy);
});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.iam.getPolicy().then((data) => {
const policy = data[0];
const apiResponse = data[1];
});
name
string
The fully qualified name of this topic.
parent
The parent PubSub instance of this topic instance.
pubsub
The parent PubSub instance of this topic instance.
Methods
create
create(gaxOpts, callback) returns Promise containing CreateTopicResponse
Create a topic.
Parameter |
|
---|---|
gaxOpts |
Optional object Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html. |
callback |
Optional Callback function. |
- Returns
-
Promise containing CreateTopicResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.create((err, topic, apiResponse) => {
if (!err) {
// The topic was created successfully.
}
});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.create().then((data) => {
const topic = data[0];
const apiResponse = data[1];
});
createSubscription
createSubscription(name, options, callback) returns Promise containing CreateSubscriptionResponse
Create a subscription to this topic.
Parameter |
|
---|---|
name |
string The name of the subscription. |
options |
Optional See a Subscription resource. |
callback |
Optional Callback function. |
- See also
- Throws
-
Error
If subscription name is omitted.
- Returns
-
Promise containing CreateSubscriptionResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
const callback = function(err, subscription, apiResponse) {};
// Without specifying any options.
topic.createSubscription('newMessages', callback);
// With options.
topic.createSubscription('newMessages', {
ackDeadlineSeconds: 90
}, callback);
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.createSubscription('newMessages').then((data) => {
const subscription = data[0];
const apiResponse = data[1];
});
delete
delete(gaxOpts, callback)
Delete the topic. This will not delete subscriptions to this topic.
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
|
- See also
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.delete((err, apiResponse) => {});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.delete().then((data) => {
const apiResponse = data[0];
});
exists
exists(callback) returns Promise containing TopicExistsResponse
Check if a topic exists.
Parameter |
|
---|---|
callback |
Optional Callback function. |
- Returns
-
Promise containing TopicExistsResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.exists((err, exists) => {});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.exists().then((data) => {
const exists = data[0];
});
get
get(gaxOpts, callback) returns Promise containing GetTopicResponse
Get a topic 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 GetTopicResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.get((err, topic, apiResponse) => {
// The `topic` data has been populated.
});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.get().then((data) => {
const topic = data[0];
const apiResponse = data[1];
});
getMetadata
getMetadata(gaxOpts, callback) returns Promise containing GetTopicMetadataResponse
Get the official representation of this topic from the API.
Parameter |
|
---|---|
gaxOpts |
Optional object Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing GetTopicMetadataResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.getMetadata((err, apiResponse) => {});
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.getMetadata().then((data) => {
const apiResponse = data[0];
});
getSubscriptions
getSubscriptions(query, callback) returns Promise containing GetSubscriptionsResponse
Get a list of the subscriptions registered to this topic. You may optionally provide a query object as the first argument to customize the response.
Your provided callback will be invoked with an error object if an API error occurred or an array of {module:pubsub/subscription} objects.
Parameter |
|
---|---|
query |
Optional Query object for listing subscriptions. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing GetSubscriptionsResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.getSubscriptions((err, subscriptions) => {
// subscriptions is an array of `Subscription` objects.
});
// Customize the query.
topic.getSubscriptions({
pageSize: 3
}, callback);
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.getSubscriptions().then((data) => {
const subscriptions = data[0];
});
publish
publish(data, attributes, callback) returns Promise containing PublishResponse
Publish the provided message.
Parameter |
|
---|---|
data |
buffer The message data. This must come in the form of a Buffer object. |
attributes |
Optional Object with string properties Attributes for this message. |
callback |
Optional PublishCallback Callback function. |
- Throws
-
TypeError
If data is not a Buffer object.
-
TypeError
If any value in
attributes
object is not a string. - Returns
-
Promise containing PublishResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
const data = Buffer.from('Hello, world!');
const callback = (err, messageId) => {
if (err) {
// Error handling omitted.
}
};
topic.publish(data, callback);
//-
// Optionally you can provide an object containing attributes for the
// message. Note that all values in the object must be strings.
//-
const attributes = {
key: 'value'
};
topic.publish(data, attributes, callback);
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.publish(data).then((messageId) => {});
publishJSON
publishJSON(json, attributes, callback) returns Promise containing PublishResponse
Publish the provided JSON. It should be noted that all messages published are done so in the form of a Buffer. This is simply a convenience method that will transform JSON into a Buffer before publishing. Subscription objects will always return message data in the form of a Buffer, so any JSON published will require manual deserialization.
Parameter |
|
---|---|
json |
object The JSON data to publish. |
attributes |
Optional object Attributes for this message. |
callback |
Optional PublishCallback Callback function. |
- See also
- Topic#publish
- Throws
-
Error
If non-object data is provided.
- Returns
-
Promise containing PublishResponse
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
const data = {
foo: 'bar'
};
const callback = (err, messageId) => {
if (err) {
// Error handling omitted.
}
};
topic.publishJSON(data, callback);
//-
// Optionally you can provide an object containing attributes for the
// message. Note that all values in the object must be strings.
//-
const attributes = {
key: 'value'
};
topic.publishJSON(data, attributes, callback);
//-
// If the callback is omitted, we'll return a Promise.
//-
topic.publishJSON(data).then((messageId) => {});
setMetadata
setMetadata(metadata, gaxOpts, callback) returns Promise containing SetTopicMetadataResponse
Updates the topic.
Parameter |
|
---|---|
metadata |
object The fields to update. This should be structured like a Topic object. |
gaxOpts |
Optional object Request configuration options, outlined here: https://googleapis.github.io/gax-nodejs/CallSettings.html. |
callback |
Optional Callback function. |
- See also
- Returns
-
Promise containing SetTopicMetadataResponse
Examples
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
const metadata = {
labels: {foo: 'bar'}
};
topic.setMetadata(metadata, err => {
if (err) {
// Error handling omitted.
}
});
<caption>If the callback is omitted, we'll return a
Promise.</caption>
topic.setMetadata(metadata).then((data) => {
const apiResponse = data[0];
});
setPublishOptions
setPublishOptions(options)
Set the publisher options.
Parameter |
|
---|---|
options |
PublishOptions The publisher options. |
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
topic.setPublishOptions({
batching: {
maxMilliseconds: 10
}
});
subscription
subscription(name, options) returns Subscription
Create a Subscription object. This command by itself will not run any API requests. You will receive a {module:pubsub/subscription} object, which will allow you to interact with a subscription.
Parameter |
|||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
name |
string Name of the subscription. |
||||||||||
options |
Optional object Configuration object. Values in
|
- Throws
-
Error
If subscription name is omitted.
- Returns
Example
const {PubSub} = require('@google-cloud/pubsub');
const pubsub = new PubSub();
const topic = pubsub.topic('my-topic');
const subscription = topic.subscription('my-subscription');
// Register a listener for `message` events.
subscription.on('message', (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 = Timestamp when Pub/Sub received the message.
});