Class PubSub (4.8.0)

[Cloud Pub/Sub](https://developers.google.com/pubsub/overview) is a reliable, many-to-many, asynchronous messaging service from Cloud Platform.

Package

@google-cloud/pubsub

Examples

Import the client library

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

Create a client that usesApplication Default Credentials (ADC):

constpubsub=newPubSub();

Create a client withexplicit credentials:

constpubsub=newPubSub({projectId:'your-project-id',keyFilename:'/path/to/keyfile.json'});

Full quickstart example:

// Imports the Google Cloud client libraryimport{PubSub}from'@google-cloud/pubsub';asyncfunctionquickstart(projectId='your-project-id',// Your Google Cloud Platform project IDtopicNameOrId='my-topic',// Name for the new topic to createsubscriptionName='my-sub'// Name for the new subscription to create){// Instantiates a clientconstpubsub=newPubSub({projectId});// Creates a new topicconst[topic]=awaitpubsub.createTopic(topicNameOrId);console.log(`Topic${topic.name} created.`);// Creates a subscription on that new topicconst[subscription]=awaittopic.createSubscription(subscriptionName);// Receive callbacks for new messages on the subscriptionsubscription.on('message',message=>{console.log('Received message:',message.data.toString());process.exit(0);});// Receive callbacks for errors on the subscriptionsubscription.on('error',error=>{console.error('Received error:',error);process.exit(1);});// Send a message to the topictopic.publishMessage({data:Buffer.from('Test message!')});}

Constructors

(constructor)(options)

constructor(options?:ClientConfig);

Constructs a new instance of thePubSub class

Parameter
NameDescription
optionsClientConfig

Properties

api

api:{[key:string]:gax.ClientStub;};

auth

auth:GoogleAuth;

getSnapshotsStream

getSnapshotsStream:()=>ObjectStream<Snapshot>;

getSubscriptionsStream

getSubscriptionsStream:()=>ObjectStream<Subscription>;

getTopicsStream

getTopicsStream:()=>ObjectStream<Topic>;

isEmulator

isEmulator:boolean;

isIdResolved

getisIdResolved():boolean;

Returns true if we have actually resolved the full project name.

isOpen

isOpen:boolean;

name

name?:string;

options

options:ClientConfig;

projectId

projectId:string;

Promise

Promise?:PromiseConstructor;

Methods

close()

close():Promise<void>;

Closes out this object, releasing any server connections. Note that once you close a PubSub object, it may not be used again. Any pending operations (e.g. queued publish messages) will fail. If you have topic or subscription objects that may have pending operations, you should call close() on those first if you want any pending messages to be delivered correctly. The PubSub class doesn't track those.

EmptyCallback

Returns
TypeDescription
Promise<void>

{Promise

close(callback)

close(callback:EmptyCallback):void;
Parameter
NameDescription
callbackEmptyCallback
Returns
TypeDescription
void

closeAllClients_()

closeAllClients_():Promise<void>;

Close all open client objects.

Returns
TypeDescription
Promise<void>

{Promise}

createSchema(schemaId, type, definition, gaxOpts)

createSchema(schemaId:string,type:SchemaType,definition:string,gaxOpts?:CallOptions):Promise<Schema>;

Create a schema in the project.

Parameters
NameDescription
schemaIdstring

The name or ID of the subscription.

typeSchemaType

The type of the schema (Protobuf, Avro, etc).

definitionstring

The text describing the schema in terms of the type.

gaxOptsCallOptions
Returns
TypeDescription
Promise<Schema>

{Promise

Example

Create a schema.

const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();awaitpubsub.createSchema('messageType',SchemaTypes.Avro,'{...avro definition...}');

createSubscription(topic, name, options)

createSubscription(topic:Topic|string,name:string,options?:CreateSubscriptionOptions):Promise<CreateSubscriptionResponse>;

Create a subscription to a topic.

Parameters
NameDescription
topicTopic | string

The Topic to create a subscription to.

namestring

The name of the subscription.

optionsCreateSubscriptionOptions

See a [Subscription resource](https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions).

Returns
TypeDescription
Promise<CreateSubscriptionResponse>

{Promise

Examples

Subscribe to a topic.

const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();consttopic='messageCenter';constname='newMessages';constcallback=function(err,subscription,apiResponse){};pubsub.createSubscription(topic,name,callback);

If the callback is omitted, we'll return a Promise.

pubsub.createSubscription(topic,name).then(function(data){constsubscription=data[0];constapiResponse=data[1];});

createSubscription(topic, name, callback)

createSubscription(topic:Topic|string,name:string,callback:CreateSubscriptionCallback):void;
Parameters
NameDescription
topicTopic | string
namestring
callbackCreateSubscriptionCallback
Returns
TypeDescription
void

createSubscription(topic, name, options, callback)

createSubscription(topic:Topic|string,name:string,options:CreateSubscriptionOptions,callback:CreateSubscriptionCallback):void;
Parameters
NameDescription
topicTopic | string
namestring
optionsCreateSubscriptionOptions
callbackCreateSubscriptionCallback
Returns
TypeDescription
void

createTopic(name, gaxOpts)

createTopic(name:string|TopicMetadata,gaxOpts?:CallOptions):Promise<CreateTopicResponse>;

Create a topic with the given name.

Parameters
NameDescription
namestring |TopicMetadata

Name of the topic.

gaxOptsCallOptions

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

Returns
TypeDescription
Promise<CreateTopicResponse>

{Promise

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();pubsub.createTopic('my-new-topic',function(err,topic,apiResponse){if(!err){// The topic was created successfully.}});//-// If the callback is omitted, we'll return a Promise.//-pubsub.createTopic('my-new-topic').then(function(data){consttopic=data[0];constapiResponse=data[1];});

createTopic(name, callback)

createTopic(name:string|TopicMetadata,callback:CreateTopicCallback):void;
Parameters
NameDescription
namestring |TopicMetadata
callbackCreateTopicCallback
Returns
TypeDescription
void

createTopic(name, gaxOpts, callback)

createTopic(name:string|TopicMetadata,gaxOpts:CallOptions,callback:CreateTopicCallback):void;
Parameters
NameDescription
namestring |TopicMetadata
gaxOptsCallOptions
callbackCreateTopicCallback
Returns
TypeDescription
void

detachSubscription(name, gaxOpts)

detachSubscription(name:string,gaxOpts?:CallOptions):Promise<DetachSubscriptionResponse>;

Detach a subscription with the given name.

Parameters
NameDescription
namestring

Name of the subscription.

gaxOptsCallOptions

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

Returns
TypeDescription
Promise<DetachSubscriptionResponse>

{Promise

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();pubsub.detachSubscription('my-sub',(err,topic,apiResponse)=>{if(!err){// The topic was created successfully.}});//-// If the callback is omitted, we'll return a Promise.//-pubsub.detachSubscription('my-sub').then(data=>{constapiResponse=data[0];});

detachSubscription(name, callback)

detachSubscription(name:string,callback:DetachSubscriptionCallback):void;
Parameters
NameDescription
namestring
callbackDetachSubscriptionCallback
Returns
TypeDescription
void

detachSubscription(name, gaxOpts, callback)

detachSubscription(name:string,gaxOpts:CallOptions,callback:DetachSubscriptionCallback):void;
Parameters
NameDescription
namestring
gaxOptsCallOptions
callbackDetachSubscriptionCallback
Returns
TypeDescription
void

determineBaseUrl_()

determineBaseUrl_():void;

Determine the appropriate endpoint to use for API requests, first trying theapiEndpoint parameter. If that isn't set, we try the Pub/Sub emulator environment variable (PUBSUB_EMULATOR_HOST). If that is also null, we try the standardgcloud alpha pubsub environment variable (CLOUDSDK_API_ENDPOINT_OVERRIDES_PUBSUB). Otherwise the default production API is used.

Note that if the URL doesn't end in '.googleapis.com', we will assume that it's an emulator and disable strict SSL checks.

Returns
TypeDescription
void

formatName_(name)

staticformatName_(name:string):string;
Parameter
NameDescription
namestring
Returns
TypeDescription
string

getClient_(config, callback)

getClient_(config:GetClientConfig,callback:GetClientCallback):void;

Get the PubSub client object.

Parameters
NameDescription
configGetClientConfig

Configuration object.

callbackGetClientCallback

The callback function.

Returns
TypeDescription
void

getClientAsync_(config)

getClientAsync_(config:GetClientConfig):Promise<gax.ClientStub>;

Get the PubSub client object.

Parameter
NameDescription
configGetClientConfig

Configuration object.

Returns
TypeDescription
Promise<ClientStub>

{Promise}

getClientConfig()

getClientConfig():Promise<ClientConfig>;

Retrieve a client configuration, suitable for passing into a GAPIC 'v1' class constructor. This will fill out projectId, emulator URLs, and so forth.

Returns
TypeDescription
Promise<ClientConfig>

{Promise

getSchemaClient()

getSchemaClient():Promise<SchemaServiceClient>;

Gets a schema client, creating one if needed. This is a shortcut fornew v1.SchemaServiceClient(await pubsub.getClientConfig()).

Returns
TypeDescription
Promise<SchemaServiceClient>

{Promise

getSnapshots(options)

getSnapshots(options?:PageOptions):Promise<GetSnapshotsResponse>;

Get a list of snapshots.

Parameter
NameDescription
optionsPageOptions
Returns
TypeDescription
Promise<GetSnapshotsResponse>

{Promise

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();pubsub.getSnapshots(function(err,snapshots){if(!err){// snapshots is an array of Snapshot objects.}});//-// If the callback is omitted, we'll return a Promise.//-pubsub.getSnapshots().then(function(data){constsnapshots=data[0];});

getSnapshots(callback)

getSnapshots(callback:GetSnapshotsCallback):void;
Parameter
NameDescription
callbackGetSnapshotsCallback
Returns
TypeDescription
void

getSnapshots(options, callback)

getSnapshots(options:PageOptions,callback:GetSnapshotsCallback):void;
Parameters
NameDescription
optionsPageOptions
callbackGetSnapshotsCallback
Returns
TypeDescription
void

getSubscriptions(options)

getSubscriptions(options?:GetSubscriptionsOptions):Promise<GetSubscriptionsResponse>;

Get a list of the subscriptions registered to all of your project's topics. 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 objects.

To get subscriptions for a topic, seeTopic.

Parameter
NameDescription
optionsGetSubscriptionsOptions
Returns
TypeDescription
Promise<GetSubscriptionsResponse>

{Promise

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();pubsub.getSubscriptions(function(err,subscriptions){if(!err){// subscriptions is an array of Subscription objects.}});//-// If the callback is omitted, we'll return a Promise.//-pubsub.getSubscriptions().then(function(data){constsubscriptions=data[0];});

getSubscriptions(callback)

getSubscriptions(callback:GetSubscriptionsCallback):void;
Parameter
NameDescription
callbackGetSubscriptionsCallback
Returns
TypeDescription
void

getSubscriptions(options, callback)

getSubscriptions(options:GetSubscriptionsOptions,callback:GetSubscriptionsCallback):void;
Parameters
NameDescription
optionsGetSubscriptionsOptions
callbackGetSubscriptionsCallback
Returns
TypeDescription
void

getTopics(options)

getTopics(options?:PageOptions):Promise<GetTopicsResponse>;

Get a list of the topics registered to your project. You may optionally provide a query object as the first argument to customize the response.

Parameter
NameDescription
optionsPageOptions
Returns
TypeDescription
Promise<GetTopicsResponse>

{Promise

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();pubsub.getTopics(function(err,topics){if(!err){// topics is an array of Topic objects.}});//-// Customize the query.//-pubsub.getTopics({pageSize:3},function(err,topics){});//-// If the callback is omitted, we'll return a Promise.//-pubsub.getTopics().then(function(data){consttopics=data[0];});

getTopics(callback)

getTopics(callback:GetTopicsCallback):void;
Parameter
NameDescription
callbackGetTopicsCallback
Returns
TypeDescription
void

getTopics(options, callback)

getTopics(options:PageOptions,callback:GetTopicsCallback):void;
Parameters
NameDescription
optionsPageOptions
callbackGetTopicsCallback
Returns
TypeDescription
void

listSchemas(view, options)

listSchemas(view?:SchemaView,options?:CallOptions):AsyncIterable<google.pubsub.v1.ISchema>;

Get a list of schemas associated with your project.

The returned AsyncIterable will resolve to objects.

This method returns an async iterable. These objects can be adapted to work in a Promise/then framework, as well as with callbacks, but this discussion is considered out of scope for these docs.

Parameters
NameDescription
viewSchemaView

The type of schema objects requested, which should be an enum value fromSchemaViews. Defaults to Full.

optionsCallOptions

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

Returns
TypeDescription
AsyncIterable<google.pubsub.v1.ISchema>

{AsyncIterable

Example
forawait(constsofpubsub.listSchemas()){constmoreInfo=awaits.get();}

request(config, callback)

request<T,R=void>(config:RequestConfig,callback:RequestCallback<T,R>):void;

Funnel all API requests through this method, to be sure we have a project ID.

Parameters
NameDescription
configRequestConfig

Configuration object.

callbackRequestCallback<T, R>

The callback function.

Returns
TypeDescription
void
Type Parameters
NameDescription
T
R

schema(idOrName)

schema(idOrName:string):Schema;

Create a Schema object, representing a schema within the project. See or to create a schema.

Parameter
NameDescription
idOrNamestring
Returns
TypeDescription
Schema

{Schema} ASchema instance.

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();constschema=pubsub.schema('my-schema');

snapshot(name)

snapshot(name:string):Snapshot;

Create a Snapshot object. See to create a snapshot.

Parameter
NameDescription
namestring

The name of the snapshot.

Returns
TypeDescription
Snapshot

{Snapshot} ASnapshot instance.

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();constsnapshot=pubsub.snapshot('my-snapshot');

subscription(name, options)

subscription(name:string,options?:SubscriptionOptions):Subscription;

Create a Subscription object. This command by itself will not run any API requests. You will receive a object, which will allow you to interact with a subscription.

Parameters
NameDescription
namestring

Name of the subscription.

optionsSubscriptionOptions

Configuration object.

Returns
TypeDescription
Subscription

{Subscription} A instance.

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();constsubscription=pubsub.subscription('my-subscription');// Register a listener for `message` events.subscription.on('message',function(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.});

topic(name, options)

topic(name:string,options?:PublishOptions):Topic;

Create a Topic object. See to create a topic.

Parameters
NameDescription
namestring

The name of the topic.

optionsPublishOptions

Publisher configuration object.

Returns
TypeDescription
Topic

{Topic} ATopic instance.

Example
const{PubSub}=require('@google-cloud/pubsub');constpubsub=newPubSub();consttopic=pubsub.topic('my-topic');

validateSchema(schema, gaxOpts)

validateSchema(schema:ISchema,gaxOpts?:CallOptions):Promise<void>;

Validate a schema definition.

Parameters
NameDescription
schemaISchema

The schema definition you wish to validate.

gaxOptsCallOptions
Returns
TypeDescription
Promise<void>

{Promise

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-10-30 UTC.