Constructor

PublisherClient

new PublisherClient(options)

Construct an instance of PublisherClient.

Parameter

options

Optional

object

The configuration object. See the subsequent parameters for more details.

Values in options have the following properties:

Parameter

credentials

Optional

object

Credentials object.

credentials.client_email

Optional

string

credentials.private_key

Optional

string

email

Optional

string

Account email address. Required when usaing a .pem or .p12 keyFilename.

keyFilename

Optional

string

Full path to the a .json, .pem, or .p12 key downloaded from the Google Developers Console. If you provide a path to a JSON file, the projectId option above is not necessary. NOTE: .pem and .p12 require you to specify options.email as well.

port

Optional

number

The port on which to connect to the remote host.

projectId

Optional

string

The project ID from the Google Developer's Console, e.g. 'grape-spaceship-123'. We will also check the environment variable GCLOUD_PROJECT for your project ID. If your app is running in an environment which supports Application Default Credentials, your project ID will be detected automatically.

promise

Optional

function()

Custom promise module to use instead of native Promises.

servicePath

Optional

string

The domain name of the API remote host.

Properties

port

static

The port for this API service.

scopes

static

The scopes needed to make gRPC calls for every method defined in this service.

servicePath

static

The DNS address for this API service.

Methods

createTopic

createTopic(request, options, callback) returns Promise

Creates the given topic with the given name.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

name

string

The name of the topic. It must have the format "projects/{project}/topics/{topic}". {topic} must start with a letter, and contain only letters ([A-Za-z]), numbers ([0-9]), dashes (-), underscores (_), periods (.), tildes (~), plus (+) or percent signs (%). It must be between 3 and 255 characters in length, and it must not start with "goog".

labels

Optional

Object with string properties

User labels.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Topic.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing Topic. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedName = client.topicPath('[PROJECT]', '[TOPIC]');
client.createTopic({name: formattedName})
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

deleteTopic

deleteTopic(request, options, callback) returns Promise

Deletes the topic with the given name. Returns NOT_FOUND if the topic does not exist. After a topic is deleted, a new topic may be created with the same name; this is an entirely new topic with none of the old configuration or subscriptions. Existing subscriptions to this topic are not deleted, but their topic field is set to deleted-topic.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

string

Name of the topic to delete. Format is projects/{project}/topics/{topic}.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error)

The function which will be called with the result of the API call.

Returns

Promise 

  • The promise which resolves when API call finishes. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
client.deleteTopic({topic: formattedTopic}).catch(err => {
  console.error(err);
});

getIamPolicy

getIamPolicy(request, options, callback) returns Promise

Gets the access control policy for a resource. Returns an empty policy if the resource exists and does not have a policy set.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

resource

string

REQUIRED: The resource for which the policy is being requested. resource is usually specified as a path. For example, a Project resource is specified as projects/{project}.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Policy.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing Policy. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
client.getIamPolicy({resource: formattedResource})
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

getProjectId

getProjectId(callback)

Return the project ID used by this class.

Parameter

callback

function(Error, string)

the callback to be called with the current project Id.

getTopic

getTopic(request, options, callback) returns Promise

Gets the configuration of a topic.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

string

The name of the topic to get. Format is projects/{project}/topics/{topic}.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Topic.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing Topic. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
client.getTopic({topic: formattedTopic})
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

listTopics

listTopics(request, options, callback) returns Promise

Lists matching topics.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

project

string

The name of the cloud project that topics belong to. Format is projects/{project}.

pageSize

Optional

number

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Array, nullable Object, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is Array of Topic.

When autoPaginate: false is specified through options, it contains the result in a single response. If the response indicates the next page exists, the third parameter is set to be used for the next request object. The fourth parameter keeps the raw response object of an object representing ListTopicsResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is Array of Topic.

    When autoPaginate: false is specified through options, the array has three elements. The first element is Array of Topic in a single response. The second element is the next request object if the response indicates the next page exists, or null. The third element is an object representing ListTopicsResponse.

    The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

// Iterate over all elements.
var formattedProject = client.projectPath('[PROJECT]');

client.listTopics({project: formattedProject})
  .then(responses => {
    var resources = responses[0];
    for (let i = 0; i < resources.length; i += 1) {
      // doThingsWith(resources[i])
    }
  })
  .catch(err => {
    console.error(err);
  });

// Or obtain the paged response.
var formattedProject = client.projectPath('[PROJECT]');


var options = {autoPaginate: false};
var callback = responses => {
  // The actual resources in a response.
  var resources = responses[0];
  // The next request if the response shows that there are more responses.
  var nextRequest = responses[1];
  // The actual response object, if necessary.
  // var rawResponse = responses[2];
  for (let i = 0; i < resources.length; i += 1) {
    // doThingsWith(resources[i]);
  }
  if (nextRequest) {
    // Fetch the next page.
    return client.listTopics(nextRequest, options).then(callback);
  }
}
client.listTopics({project: formattedProject}, options)
  .then(callback)
  .catch(err => {
    console.error(err);
  });

listTopicsStream

listTopicsStream(request, options) returns Stream

Equivalent to listTopics, but returns a NodeJS Stream object.

This fetches the paged responses for listTopics continuously and invokes the callback registered for 'data' event for each element in the responses.

The returned object has 'end' method when no more elements are required.

autoPaginate option will be ignored.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

project

string

The name of the cloud project that topics belong to. Format is projects/{project}.

pageSize

Optional

number

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

See also
https://nodejs.org/api/stream.html
Returns

Stream 

An object stream which emits an object representing Topic on 'data' event.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedProject = client.projectPath('[PROJECT]');
client.listTopicsStream({project: formattedProject})
  .on('data', element => {
    // doThingsWith(element)
  }).on('error', err => {
    console.log(err);
  });

listTopicSubscriptions

listTopicSubscriptions(request, options, callback) returns Promise

Lists the name of the subscriptions for this topic.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

string

The name of the topic that subscriptions are attached to. Format is projects/{project}/topics/{topic}.

pageSize

Optional

number

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Array, nullable Object, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is Array of string.

When autoPaginate: false is specified through options, it contains the result in a single response. If the response indicates the next page exists, the third parameter is set to be used for the next request object. The fourth parameter keeps the raw response object of an object representing ListTopicSubscriptionsResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is Array of string.

    When autoPaginate: false is specified through options, the array has three elements. The first element is Array of string in a single response. The second element is the next request object if the response indicates the next page exists, or null. The third element is an object representing ListTopicSubscriptionsResponse.

    The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

// Iterate over all elements.
var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');

client.listTopicSubscriptions({topic: formattedTopic})
  .then(responses => {
    var resources = responses[0];
    for (let i = 0; i < resources.length; i += 1) {
      // doThingsWith(resources[i])
    }
  })
  .catch(err => {
    console.error(err);
  });

// Or obtain the paged response.
var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');


var options = {autoPaginate: false};
var callback = responses => {
  // The actual resources in a response.
  var resources = responses[0];
  // The next request if the response shows that there are more responses.
  var nextRequest = responses[1];
  // The actual response object, if necessary.
  // var rawResponse = responses[2];
  for (let i = 0; i < resources.length; i += 1) {
    // doThingsWith(resources[i]);
  }
  if (nextRequest) {
    // Fetch the next page.
    return client.listTopicSubscriptions(nextRequest, options).then(callback);
  }
}
client.listTopicSubscriptions({topic: formattedTopic}, options)
  .then(callback)
  .catch(err => {
    console.error(err);
  });

listTopicSubscriptionsStream

listTopicSubscriptionsStream(request, options) returns Stream

Equivalent to listTopicSubscriptions, but returns a NodeJS Stream object.

This fetches the paged responses for listTopicSubscriptions continuously and invokes the callback registered for 'data' event for each element in the responses.

The returned object has 'end' method when no more elements are required.

autoPaginate option will be ignored.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

string

The name of the topic that subscriptions are attached to. Format is projects/{project}/topics/{topic}.

pageSize

Optional

number

The maximum number of resources contained in the underlying API response. If page streaming is performed per-resource, this parameter does not affect the return value. If page streaming is performed per-page, this determines the maximum number of resources in a page.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

See also
https://nodejs.org/api/stream.html
Returns

Stream 

An object stream which emits a string on 'data' event.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
client.listTopicSubscriptionsStream({topic: formattedTopic})
  .on('data', element => {
    // doThingsWith(element)
  }).on('error', err => {
    console.log(err);
  });

matchProjectFromProjectName

matchProjectFromProjectName(projectName) returns String

Parse the projectName from a project resource.

Parameter

projectName

String

A fully-qualified path representing a project resources.

Returns

String 

  • A string representing the project.

matchProjectFromTopicName

matchProjectFromTopicName(topicName) returns String

Parse the topicName from a topic resource.

Parameter

topicName

String

A fully-qualified path representing a topic resources.

Returns

String 

  • A string representing the project.

matchTopicFromTopicName

matchTopicFromTopicName(topicName) returns String

Parse the topicName from a topic resource.

Parameter

topicName

String

A fully-qualified path representing a topic resources.

Returns

String 

  • A string representing the topic.

projectPath

projectPath(project) returns String

Return a fully-qualified project resource name string.

Parameter

project

String

Returns

String 

publish

publish(request, options, callback) returns Promise

Adds one or more messages to the topic. Returns NOT_FOUND if the topic does not exist. The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

string

The messages in the request will be published on this topic. Format is projects/{project}/topics/{topic}.

messages

Array of Object

The messages to publish.

This object should have the same structure as PubsubMessage

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing PublishResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing PublishResponse. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
var data = '';
var messagesElement = {
  data: data,
};
var messages = [messagesElement];
var request = {
  topic: formattedTopic,
  messages: messages,
};
client.publish(request)
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

setIamPolicy

setIamPolicy(request, options, callback) returns Promise

Sets the access control policy on the specified resource. Replaces any existing policy.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

resource

string

REQUIRED: The resource for which the policy is being specified. resource is usually specified as a path. For example, a Project resource is specified as projects/{project}.

policy

Object

REQUIRED: The complete policy to be applied to the resource. The size of the policy is limited to a few 10s of KB. An empty policy is a valid policy but certain Cloud Platform services (such as Projects) might reject them.

This object should have the same structure as Policy

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Policy.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing Policy. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
var policy = {};
var request = {
  resource: formattedResource,
  policy: policy,
};
client.setIamPolicy(request)
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

testIamPermissions

testIamPermissions(request, options, callback) returns Promise

Returns permissions that a caller has on the specified resource. If the resource does not exist, this will return an empty set of permissions, not a NOT_FOUND error.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

resource

string

REQUIRED: The resource for which the policy detail is being requested. resource is usually specified as a path. For example, a Project resource is specified as projects/{project}.

permissions

Array of string

The set of permissions to check for the resource. Permissions with wildcards (such as '' or 'storage.') are not allowed. For more information see IAM Overview.

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing TestIamPermissionsResponse.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing TestIamPermissionsResponse. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
var permissions = [];
var request = {
  resource: formattedResource,
  permissions: permissions,
};
client.testIamPermissions(request)
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });

topicPath

topicPath(project, topic) returns String

Return a fully-qualified topic resource name string.

Parameter

project

String

topic

String

Returns

String 

updateTopic

updateTopic(request, options, callback) returns Promise

Updates an existing topic. Note that certain properties of a topic are not modifiable. Options settings follow the style guide: NOTE: The style guide requires body: "topic" instead of body: "*". Keeping the latter for internal consistency in V1, however it should be corrected in V2. See https://cloud.google.com/apis/design/standard_methods#update for details.

Parameter

request

Object

The request object that will be sent.

Values in request have the following properties:

Parameter

topic

Object

The topic to update.

This object should have the same structure as Topic

updateMask

Object

Indicates which fields in the provided topic to update. Must be specified and non-empty.

This object should have the same structure as FieldMask

options

Optional

Object

Optional parameters. You can override the default settings for this call, e.g, timeout, retries, paginations, etc. See gax.CallOptions for the details.

callback

Optional

function(nullable Error, nullable Object)

The function which will be called with the result of the API call.

The second parameter to the callback is an object representing Topic.

Returns

Promise 

  • The promise which resolves to an array. The first element of the array is an object representing Topic. The promise has a method named "cancel" which cancels the ongoing API call.

Example

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

var client = new pubsub.v1.PublisherClient({
  // optional auth parameters.
});

var topic = {};
var updateMask = {};
var request = {
  topic: topic,
  updateMask: updateMask,
};
client.updateTopic(request)
  .then(responses => {
    var response = responses[0];
    // doThingsWith(response)
  })
  .catch(err => {
    console.error(err);
  });