@google-cloud/pubsub 0.26.0 » Class: PublisherClient

v1.PublisherClient

class   static

The service that an application uses to manipulate topics, and to send messages to a topic.

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 using 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 below 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. See the resource name rules.

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 See Creating and managing labels. messageStoragePolicy Optional Object Policy constraining how messages published to the topic may be stored. It is determined when the topic is created based on the policy configured at the project level. It must not be set by the caller in the request to CreateTopic or to UpdateTopic. This field will be populated in the responses for GetTopic, CreateTopic, and UpdateTopic: if not present in the response, then no constraints are in effect. This object should have the same structure as MessageStoragePolicy
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');

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

const formattedName = client.topicPath('[PROJECT]', '[TOPIC]');
client.createTopic({name: formattedName})
  .then(responses => {
    const 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');

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

const 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');

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

const formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
client.getIamPolicy({resource: formattedResource})
  .then(responses => {
    const 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');

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

const formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
client.getTopic({topic: formattedTopic})
  .then(responses => {
    const 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 project in which to list topics. Format is projects/{project-id}. 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');

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

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

client.listTopics({project: formattedProject})
  .then(responses => {
    const resources = responses[0];
    for (const resource of resources) {
      // doThingsWith(resource)
    }
  })
  .catch(err => {
    console.error(err);
  });

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


const options = {autoPaginate: false};
const callback = responses => {
  // The actual resources in a response.
  const resources = responses[0];
  // The next request if the response shows that there are more responses.
  const nextRequest = responses[1];
  // The actual response object, if necessary.
  // const rawResponse = responses[2];
  for (const resource of resources) {
    // doThingsWith(resource);
  }
  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 project in which to list topics. Format is projects/{project-id}. 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');

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

const 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 names of the subscriptions on 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');

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

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

client.listTopicSubscriptions({topic: formattedTopic})
  .then(responses => {
    const resources = responses[0];
    for (const resource of resources) {
      // doThingsWith(resource)
    }
  })
  .catch(err => {
    console.error(err);
  });

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


const options = {autoPaginate: false};
const callback = responses => {
  // The actual resources in a response.
  const resources = responses[0];
  // The next request if the response shows that there are more responses.
  const nextRequest = responses[1];
  // The actual response object, if necessary.
  // const rawResponse = responses[2];
  for (const resource of resources) {
    // doThingsWith(resource);
  }
  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');

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

const 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.

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');

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

const formattedTopic = client.topicPath('[PROJECT]', '[TOPIC]');
const data = '';
const messagesElement = {
  data: data,
};
const messages = [messagesElement];
const request = {
  topic: formattedTopic,
  messages: messages,
};
client.publish(request)
  .then(responses => {
    const 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');

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

const formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
const policy = {};
const request = {
  resource: formattedResource,
  policy: policy,
};
client.setIamPolicy(request)
  .then(responses => {
    const 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');

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

const formattedResource = client.topicPath('[PROJECT]', '[TOPIC]');
const permissions = [];
const request = {
  resource: formattedResource,
  permissions: permissions,
};
client.testIamPermissions(request)
  .then(responses => {
    const 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.

Parameter
request	Object The request object that will be sent. Values in request have the following properties: Parameter topic Object The updated topic object. 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. Note that if update_mask contains "message_storage_policy" then the new value will be determined based on the policy configured at the project or organization level. The message_storage_policy must not be set in the topic provided above. 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');

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

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