@google-cloud/pubsub

constructor

constructor(errorCode: AckResponse, message?: string);

property errorCode

errorCode: AckResponse;

constructor

constructor(message: string, error?: Error);

property error

error?: Error;

property message

message: string;

property hours

readonly hours: number;

• Equivalent to total('hour').

property milliseconds

readonly milliseconds: number;

• Equivalent to total('millisecond').

property minutes

readonly minutes: number;

• Equivalent to total('minute').

property seconds

readonly seconds: number;

• Equivalent to total('second').

method add

add: (other: DurationLike | Duration) => Duration;

• Adds another Duration to this one and returns a new Duration.

  Parameter other

  A Duration or Duration-like object, like from() takes.

  Returns

  A new Duration.

method compare

static compare: (first: Duration, second: Duration) => 0 | 1 | -1;

• Compare two Duration objects. Returns -1 if the first is less than the second, zero if they are equal, 1 if the first is greater than the second.

  Unlike tc39, this version does not accept options for relativeTo.

method from

static from: (durationLike: DurationLike | Duration) => Duration;

• Creates a Duration from a DurationLike, which is an object containing zero or more of the following: hours, seconds, minutes, millis.

method subtract

subtract: (other: DurationLike | Duration) => Duration;

• Subtracts another Duration from this one and returns a new Duration.

  Parameter other

  A Duration or Duration-like object, like from() takes.

  Returns

  A new Duration.

method total

total: (totalOf: TotalOfUnit) => number;

• Calculates the total number of units of type 'totalOf' that would fit inside this duration. The tc39 options parameter is not supported.

method totalOf

totalOf: (totalOf: TotalOfUnit) => number;

• Calculates the total number of units of type 'totalOf' that would fit inside this duration.

  No longer part of the tc39 spec, superseded by total().

  Deprecated

constructor

constructor(pubsub: PubSub, nameOrNameable: string | Nameable);

property id

readonly id: string;

property pubsub

pubsub: PubSub;

property request

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

method getPolicy

getPolicy: {
    (gaxOpts?: CallOptions): Promise<GetPolicyResponse>;
    (callback: NormalCallback<Policy>): void;
    (gaxOpts: CallOptions, callback: NormalCallback<Policy>): void;
};

• Get the IAM policy

  Parameter gaxOptions

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  topic.iam.getPolicy(function(err, policy, apiResponse) {});
  
  subscription.iam.getPolicy(function(err, policy, apiResponse) {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  topic.iam.getPolicy().then(function(data) {
    const policy = data[0];
    const apiResponse = data[1];
  });

  See Also

  • [Topics: getIamPolicy API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/getIamPolicy

  • [Subscriptions: getIamPolicy API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/getIamPolicy

method setPolicy

setPolicy: {
    (policy: Policy, gaxOpts?: CallOptions): Promise<SetPolicyResponse>;
    (
        policy: Policy,
        gaxOpts: CallOptions,
        callback: NormalCallback<Policy>
    ): void;
    (policy: Policy, callback: NormalCallback<Policy>): void;
};

• Set the IAM policy

  Parameter policy

  The [policy](https://cloud.google.com/pubsub/docs/reference/rest/v1/Policy).

  Parameter

  {array} [policy.bindings] Bindings associate members with roles.

  Parameter

  {Array} [policy.rules] Rules to be applied to the policy.

  Parameter

  {string} [policy.etag] Etags are used to perform a read-modify-write.

  Parameter gaxOptions

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Throws

  {Error} If no policy is provided.

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  const myPolicy = {
    bindings: [
      {
        role: 'roles/pubsub.subscriber',
        members:
  ['serviceAccount:myotherproject@appspot.gserviceaccount.com']
      }
    ]
  };
  
  topic.iam.setPolicy(myPolicy, function(err, policy, apiResponse) {});
  
  subscription.iam.setPolicy(myPolicy, function(err, policy, apiResponse)
  {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  topic.iam.setPolicy(myPolicy).then(function(data) {
    const policy = data[0];
    const apiResponse = data[1];
  });

  See Also

  • [Topics: setIamPolicy API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/setIamPolicy

  • [Subscriptions: setIamPolicy API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/setIamPolicy

  • [Policy]https://cloud.google.com/pubsub/docs/reference/rest/v1/Policy

method testPermissions

testPermissions: {
    (
        permissions: string | string[],
        gaxOpts?: CallOptions
    ): Promise<TestIamPermissionsResponse>;
    (
        permissions: string | string[],
        gaxOpts: CallOptions,
        callback: TestIamPermissionsCallback
    ): void;
    (permissions: string | string[], callback: TestIamPermissionsCallback): void;
};

• Test a set of permissions for a resource.

  Permissions with wildcards such as * or storage.* are not allowed.

  Parameter permissions

  The permission(s) to test for.

  Parameter gaxOptions

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Throws

  {Error} If permissions are not provided.

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  //-
  // Test a single permission.
  //-
  const test = 'pubsub.topics.update';
  
  topic.iam.testPermissions(test, function(err, permissions, apiResponse) {
    console.log(permissions);
    // {
    //   "pubsub.topics.update": true
    // }
  });
  
  //-
  // Test several permissions at once.
  //-
  const tests = [
    'pubsub.subscriptions.consume',
    'pubsub.subscriptions.update'
  ];
  
  subscription.iam.testPermissions(tests, function(err, permissions) {
    console.log(permissions);
    // {
    //   "pubsub.subscriptions.consume": true,
    //   "pubsub.subscriptions.update": false
    // }
  });
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  topic.iam.testPermissions(test).then(function(data) {
    const permissions = data[0];
    const apiResponse = data[1];
  });

  See Also

  • [Topics: testIamPermissions API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/testIamPermissions

  • [Subscriptions: testIamPermissions API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/testIamPermissions

  • [Permissions Reference]https://cloud.google.com/pubsub/access_control#permissions

constructor

constructor(
    sub: Subscriber,
    { ackId, message, deliveryAttempt }: google.pubsub.v1.IReceivedMessage
);

• Parameter sub

  The parent subscriber.

  Parameter message

  The raw message response.

property ackId

ackId: string;

property attributes

attributes: { [key: string]: string };

property data

data: Buffer;

property deliveryAttempt

deliveryAttempt: number;

property handledPromise

readonly handledPromise: Promise<void>;

• Resolves when the message has been handled fully; a handled message may not have any further operations performed on it.

property id

id: string;

property length

readonly length: number;

• The length of the message data.

  {number}

property orderingKey

orderingKey?: string;

property parentSpan

parentSpan?: tracing.Span;

• Tracks a telemetry tracing parent span through the receive process. This will be the original publisher-side span if we have one; otherwise we'll create a "publisher" span to hang new subscriber spans onto.

  This needs to be declared explicitly here, because having a public class implement a private interface seems to confuse TypeScript. (And it's needed in unit tests.)

property publishTime

publishTime: PreciseDate;

property received

received: number;

property subSpans

subSpans: SubscriberSpans;

• Tracks subscriber-specific telemetry objects through the library.

method ack

ack: () => void;

• Acknowledges the message.

  Example 1

  subscription.on('message', message => {
    message.ack();
  });

method ackFailed

ackFailed: (error: AckError) => void;

• Sets this message's exactly once delivery acks to permanent failure. This is meant for internal library use only.

method ackWithResponse

ackWithResponse: () => Promise<AckResponse>;

• Acknowledges the message, expecting a response (for exactly-once delivery subscriptions). If exactly-once delivery is not enabled, this will immediately resolve successfully.

  Example 1

  subscription.on('message', async (message) => {
    const response = await message.ackWithResponse();
  });

method dispatched

dispatched: () => void;

• When this message is dispensed to user callback code, this should be called. The time between the dispatch and the handledPromise resolving is when the message is with the user.

method endParentSpan

endParentSpan: () => void;

• Ends any open subscribe telemetry tracing span.

method isDispatched

isDispatched: () => boolean;

• Returns

  True if this message has been dispatched to user callback code.

method modAck

modAck: (deadline: number) => void;

• Modifies the ack deadline. At present time, this should generally not be called by users.

  Parameter deadline

  The number of seconds to extend the deadline.

method modAckWithResponse

modAckWithResponse: (deadline: number) => Promise<AckResponse>;

• Modifies the ack deadline, expecting a response (for exactly-once delivery subscriptions). If exactly-once delivery is not enabled, this will immediately resolve successfully. At present time, this should generally not be called by users.

  Parameter deadline

  The number of seconds to extend the deadline.

method nack

nack: () => void;

• Removes the message from our inventory and schedules it to be redelivered.

  Example 1

  subscription.on('message', message => {
    message.nack();
  });

method nackWithResponse

nackWithResponse: () => Promise<AckResponse>;

• Removes the message from our inventory and schedules it to be redelivered, with the modAck response being returned (for exactly-once delivery subscriptions). If exactly-once delivery is not enabled, this will immediately resolve successfully.

  Example 1

  subscription.on('message', async (message) => {
    const response = await message.nackWithResponse();
  });

constructor

constructor(key: string, err: grpc.ServiceError);

property code

code: grpc.status;

property details

details: string;

property error

error: grpc.ServiceError;

property metadata

metadata: grpc.Metadata;

property orderingKey

orderingKey: string;

constructor

constructor(options?: ClientConfig);

property api

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

property auth

auth: GoogleAuth;

property getSnapshotsStream

getSnapshotsStream: () => ObjectStream<Snapshot>;

property getSubscriptionsStream

getSubscriptionsStream: () => ObjectStream<Subscription>;

property getTopicsStream

getTopicsStream: () => ObjectStream<Topic>;

property isEmulator

isEmulator: boolean;

property isIdResolved

readonly isIdResolved: boolean;

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

  Returns

  {boolean} true if the name is resolved.

property isOpen

isOpen: boolean;

property name

name?: string;

property options

options: ClientConfig;

property projectId

projectId: string;

property Promise

Promise?: PromiseConstructor;

method close

close: {
    (): Promise<void>;
    (callback: NormalCallback<google.protobuf.IEmpty>): void;
};

• Closes the PubSub client, releasing any underlying gRPC 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.

  Note that this method primarily closes the gRPC clients (Publisher and Subscriber) used for API requests. It does **not** automatically handle the graceful shutdown of active subscriptions.

  For graceful shutdown of subscriptions with specific timeout behavior (e.g., ensuring buffered messages are nacked before closing), please refer to the Subscription#close method. It is recommended to call Subscription.close({timeout: ...}) directly on your active Subscription objects *before* calling PubSub.close() if you require that specific shutdown behavior.

  Calling PubSub.close() without first closing active subscriptions might result in abrupt termination of message processing for those subscriptions. Any pending operations on associated Topic or Subscription objects (e.g., queued publish messages or unacked subscriber messages) may fail after PubSub.close() is called.

  EmptyCallback

  Parameter err

  Request error, if any.

  Returns

  {Promise} Resolves when the clients are closed.

method closeAllClients_

closeAllClients_: () => Promise<void>;

• Close all open client objects.

  Returns

  {Promise}

method createSchema

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

• Create a schema in the project.

  Parameter schemaId

  The name or ID of the subscription.

  Parameter type

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

  Parameter definition

  The text describing the schema in terms of the type.

  Parameter options

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

  Returns

  {Promise}

  Throws

  {Error} If a schema ID or name is not provided.

  Throws

  {Error} If an invalid SchemaType is provided.

  Throws

  {Error} If an invalid schema definition is provided.

  Example 1

  Create a schema.

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

  See Also

  • [Schemas: create API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/create

  • Schema#create

method createSubscription

createSubscription: {
    (
        topic: Topic | string,
        name: string,
        options?: CreateSubscriptionOptions
    ): Promise<CreateSubscriptionResponse>;
    (topic: string | Topic, name: string, callback: SubscriptionCallback): void;
    (
        topic: string | Topic,
        name: string,
        options: CreateSubscriptionOptions,
        callback: SubscriptionCallback
    ): void;
};

• Create a subscription to a topic.

  Parameter topic

  The Topic to create a subscription to.

  Parameter name

  The name of the subscription.

  Parameter options

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Throws

  {Error} If a Topic instance or topic name is not provided.

  Throws

  {Error} If a subscription name is not provided.

  Example 1

  Subscribe to a topic.

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

  Example 2

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

  pubsub.createSubscription(topic, name)
    .then(function(data) {
      const subscription = data[0];
      const apiResponse = data[1];
    });

  See Also

  • [Subscriptions: create API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create

  • Topic#createSubscription

method createTopic

createTopic: {
    (
        name: string | TopicMetadata,
        gaxOpts?: CallOptions
    ): Promise<CreateTopicResponse>;
    (name: any, callback: TopicCallback): void;
    (name: any, gaxOpts: CallOptions, callback: TopicCallback): void;
};

• Create a topic with the given name.

  Parameter name

  Name of the topic.

  Parameter gaxOpts

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  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) {
    const topic = data[0];
    const apiResponse = data[1];
  });

  See Also

  • [Topics: create API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/create

method detachSubscription

detachSubscription: {
    (name: string, gaxOpts?: CallOptions): Promise<DetachSubscriptionResponse>;
    (name: string, callback: NormalCallback<google.protobuf.IEmpty>): void;
    (
        name: string,
        gaxOpts: CallOptions,
        callback: NormalCallback<google.protobuf.IEmpty>
    ): void;
};

• Detach a subscription with the given name.

  Parameter name

  Name of the subscription.

  Parameter gaxOpts

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  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 => {
    const apiResponse = data[0];
  });

  See Also

  • [Admin: Pub/Sub administration API Documentation]https://cloud.google.com/pubsub/docs/admin

method determineBaseUrl_

determineBaseUrl_: () => void;

• Determine the appropriate endpoint to use for API requests, first trying the apiEndpoint 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 standard gcloud 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.

method formatName_

static formatName_: (name: string) => string;

method getClient_

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

• Get the PubSub client object.

  Parameter config

  Configuration object.

  Parameter

  {object} config.gaxOpts GAX options.

  Parameter

  {function} config.method The gax method to call.

  Parameter

  {object} config.reqOpts Request options.

  Parameter callback

  The callback function.

method getClientAsync_

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

• Get the PubSub client object.

  Parameter config

  Configuration object.

  Parameter

  {object} config.gaxOpts GAX options.

  Parameter

  {function} config.method The gax method to call.

  Parameter

  {object} config.reqOpts Request options.

  Returns

  {Promise}

method 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

  {Promise} the filled client configuration.

method getSchemaClient

getSchemaClient: () => Promise<SchemaServiceClient>;

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

  Returns

  {Promise}

method getSnapshots

getSnapshots: {
    (options?: PageOptions): Promise<GetSnapshotsResponse>;
    (
        callback:
            | NormalCallback<Snapshot>
            | PagedCallback<Snapshot, google.pubsub.v1.IListSnapshotsResponse>
    ): void;
    (
        options: PageOptions,
        callback:
            | NormalCallback<Snapshot>
            | PagedCallback<Snapshot, google.pubsub.v1.IListSnapshotsResponse>
    ): void;
};

• Get a list of snapshots.

  Parameter query

  Query object for listing snapshots.

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  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) {
    const snapshots = data[0];
  });

method getSubscriptions

getSubscriptions: {
    (options?: GetSubscriptionsOptions): Promise<GetSubscriptionsResponse>;
    (callback: GetSubscriptionsCallback): void;
    (options: GetSubscriptionsOptions, callback: GetSubscriptionsCallback): void;
};

• 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 Subscription objects.

  To get subscriptions for a topic, see Topic.

  Parameter query

  Query object for listing subscriptions.

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  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) {
    const subscriptions = data[0];
  });

  See Also

  • [Subscriptions: list API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/list

method getTopics

getTopics: {
    (options?: PageOptions): Promise<GetTopicsResponse>;
    (
        callback:
            | NormalCallback<Topic>
            | PagedCallback<Topic, google.pubsub.v1.IListTopicsResponse>
    ): void;
    (
        options: PageOptions,
        callback:
            | NormalCallback<Topic>
            | PagedCallback<Topic, google.pubsub.v1.IListTopicsResponse>
    ): void;
};

• 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 query

  Query object for listing topics.

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  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) {
    const topics = data[0];
  });

  See Also

  • [Topics: list API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.topics/list

method listSchemas

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 google.pubsub.v1.ISchema 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.

  Parameter view

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

  Parameter options

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

  Returns

  {AsyncIterable}

  Example 1

  for await (const s of pubsub.listSchemas()) {
    const moreInfo = await s.get();
  }

  See Also

  • [Schemas: list API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/list

  • [More about async iterators]https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of

method request

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.

  Parameter config

  Configuration object.

  Parameter

  {object} config.gaxOpts GAX options.

  Parameter

  {function} config.method The gax method to call.

  Parameter

  {object} config.reqOpts Request options.

  Parameter callback

  The callback function.

method schema

schema: (idOrName: string) => Schema;

• Create a Schema object, representing a schema within the project. See PubSub#createSchema or Schema#create to create a schema.

  Parameter name

  The ID or name of the schema.

  Returns

  {Schema} A Schema instance.

  Throws

  {Error} If a name is not provided.

  Example 1

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

method snapshot

snapshot: (name: string) => Snapshot;

• Create a Snapshot object. See Subscription#createSnapshot to create a snapshot.

  Parameter name

  The name of the snapshot.

  Returns

  {Snapshot} A Snapshot instance.

  Throws

  {Error} If a name is not provided.

  Example 1

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

method subscription

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

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

  Parameter name

  Name of the subscription.

  Parameter options

  Configuration object.

  Returns

  {Subscription} A Subscription instance.

  Throws

  {Error} If subscription name is omitted.

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const subscription = 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.
  });

method topic

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

• Create a Topic object. See PubSub#createTopic to create a topic.

  Parameter name

  The name of the topic.

  Parameter options

  Publisher configuration object.

  Returns

  {Topic} A Topic instance.

  Throws

  {Error} If a name is not provided.

  Example 1

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

method validateSchema

validateSchema: (
    schema: google.pubsub.v1.ISchema,
    gaxOpts?: CallOptions
) => Promise<void>;

• Validate a schema definition.

  Parameter schema

  The schema definition you wish to validate.

  Parameter options

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

  Returns

  {Promise}

  Throws

  {Error} if the validation fails.

  See Also

  • [Schemas: validateSchema API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/validate

constructor

constructor(pubsub: PubSub, idOrName: string);

property id

id: string;

property name_

name_?: string;

property pubsub

pubsub: PubSub;

method create

create: (
    type: SchemaType,
    definition: string,
    gaxOpts?: CallOptions
) => Promise<void>;

• Create a schema.

  Parameter type

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

  Parameter definition

  The text describing the schema in terms of the type.

  Parameter options

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

  Returns

  {Promise}

  Throws

  {Error} if the schema type is incorrect.

  Throws

  {Error} if the definition is invalid.

  Example 1

  Create a schema.

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const schema = pubsub.schema('messageType');
  await schema.create(
    SchemaTypes.Avro,
    '{...avro definition...}'
  );

  See Also

  • [Schemas: create API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/create

method delete

delete: (gaxOpts?: CallOptions) => Promise<void>;

• Delete the schema from the project.

  Parameter options

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

  Returns

  {Promise}

  See Also

  • [Schemas: deleteSchema API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/delete

method formatName_

static formatName_: (projectId: string, nameOrId: string) => string;

method get

get: (view?: SchemaView, gaxOpts?: CallOptions) => Promise<ISchema>;

• Get full information about the schema from the service.

  Parameter view

  The type of schema object requested, which should be an enum value from SchemaViews. Defaults to Full.

  Parameter options

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

  Returns

  {Promise}

  See Also

  • [Schemas: getSchema API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/get

method getName

getName: () => Promise<string>;

• Return the fully qualified name of this schema.

  Note that we have to verify that we have a projectId before returning this, so we have to check that first.

  {Promise} a Promise that resolves to the full schema name

method metadataFromMessage

static metadataFromMessage: (attributes: Attributes) => SchemaMessageMetadata;

• Translates the schema attributes in messages delivered from Pub/Sub. All resulting fields may end up being blank.

method validateMessage

validateMessage: (
    message: string,
    encoding: google.pubsub.v1.Encoding | keyof typeof google.pubsub.v1.Encoding,
    gaxOpts?: CallOptions
) => Promise<void>;

• Validate a message against this schema's definition.

  If you would like to validate a message against an arbitrary schema, please use the SchemaServiceClient GAPIC class directly, using your PubSub instance's configuration, via PubSub#getClientConfig.

  Parameter message

  The message to validate.

  Parameter encoding

  The encoding of the message to validate.

  Parameter options

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

  Returns

  {Promise}

  Throws

  {Error} if the validation fails.

  Throws

  {Error} if other parameters are invalid.

  See Also

  • [Schemas: validateMessage API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.schemas/validateMessage

constructor

constructor(parent: PubSub | Subscription, name: string);

property metadata

metadata?: google.pubsub.v1.ISnapshot;

property name

name: string;

property parent

parent: PubSub | Subscription;

method create

create: {
    (gaxOpts?: CallOptions): Promise<CreateSnapshotResponse>;
    (callback: CreateSnapshotCallback): void;
    (gaxOpts: CallOptions, callback: CreateSnapshotCallback): void;
};

• Create a snapshot with the given name.

  **This is only available if you accessed this object through Subscription#snapshot.**

  Snapshot#create

  Parameter name

  Name of the snapshot.

  Parameter callback

  The callback function.

  Parameter

  {?error} callback.err An error from the API call, may be null.

  Parameter

  {Snapshot} callback.snapshot The newly created snapshot.

  Parameter

  {object} callback.apiResponse The full API response from the service.

  Example 1

  const subscription = pubsub.subscription('my-subscription');
  const snapshot = subscription.snapshot('my-snapshot');
  
  const callback = (err, snapshot, apiResponse) => {
    if (!err) {
      // The snapshot was created successfully.
    }
  };
  
  snapshot.create('my-snapshot', callback);
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  snapshot.create('my-snapshot').then((data) => {
    const snapshot = data[0];
    const apiResponse = data[1];
  });

method delete

delete: {
    (): Promise<EmptyResponse>;
    (callback: NormalCallback<google.protobuf.IEmpty>): void;
};

• Delete the snapshot.

  Parameter callback

  The callback function.

  Parameter

  {?error} callback.err An error returned while making this request.

  Parameter

  {object} callback.apiResponse The full API response from the service.

  Example 1

  snapshot.delete((err, apiResponse) => {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  snapshot.delete().then((data) => {
    const apiResponse = data[0];
  });

method formatName_

static formatName_: (projectId: string, name: string) => string;

method seek

seek: {
    (gaxOpts?: CallOptions): Promise<SeekResponse>;
    (callback: NormalCallback<google.pubsub.v1.ISeekResponse>): void;
    (
        gaxOpts: CallOptions,
        callback: NormalCallback<google.pubsub.v1.ISeekResponse>
    ): void;
};

• Seeks an existing subscription to the snapshot.

  **This is only available if you accessed this object through Subscription#snapshot.**

  Snapshot#seek

  Parameter callback

  The callback function.

  Parameter

  {?error} callback.err An error from the API call, may be null.

  Parameter

  {object} callback.apiResponse The full API response from the service.

  Example 1

  const subscription = pubsub.subscription('my-subscription');
  const snapshot = subscription.snapshot('my-snapshot');
  
  snapshot.seek((err, apiResponse) => {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  snapshot.seek().then((data) => {
    const apiResponse = data[0];
  });

constructor

constructor(status: grpc.StatusObject);

property code

code: grpc.status;

property details

details: string;

property metadata

metadata: grpc.Metadata;

constructor

constructor(pubsub: PubSub, name: string, options?: SubscriptionOptions);

property iam

iam: IAM;

property isOpen

readonly isOpen: boolean;

• Indicates if the Subscription is open and receiving messages.

  {boolean}

property metadata

metadata?: google.pubsub.v1.ISubscription;

property name

readonly name: string;

property projectId

readonly projectId: string;

• {string}

property pubsub

pubsub: PubSub;

property request

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

property topic

topic?: string | Topic;

method close

close: { (): Promise<void>; (callback: SubscriptionCloseCallback): void };

• Closes the Subscription. Once this is called you will no longer receive message events unless you call {Subscription#open} or add new message listeners.

  Parameter callback

  The callback function, if not using the Promise-based call signature.

  Parameter

  {?error} [callback.err] An error returned while closing the Subscription.

  Example 1

  await subscription.close();

method create

create: {
    (options?: CreateSubscriptionOptions): Promise<CreateSubscriptionResponse>;
    (callback: SubscriptionCallback): void;
    (options: CreateSubscriptionOptions, callback: SubscriptionCallback): void;
};

• Create a subscription.

  Parameter name

  The name of the subscription.

  Parameter options

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Throws

  {Error} If subscription name is omitted.

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('newMessages');
  const callback = function(err, subscription, apiResponse) {};
  
  subscription.create(callback);

  Example 2

  With options

  subscription.create({
    ackDeadlineSeconds: 90
  }, callback);

  Example 3

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

  const [sub, apiResponse] = await subscription.create();

  See Also

  • [Subscriptions: create API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/create

method createSnapshot

createSnapshot: {
    (name: string, gaxOpts?: CallOptions): Promise<CreateSnapshotResponse>;
    (name: string, callback: CreateSnapshotCallback): void;
    (name: string, gaxOpts: CallOptions, callback: CreateSnapshotCallback): void;
};

• Create a snapshot with the given name.

  Parameter name

  Name of the snapshot.

  Parameter gaxOpts

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

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  const callback = (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((data) => {
    const snapshot = data[0];
    const apiResponse = data[1];
  });

method delete

delete: {
    (gaxOpts?: CallOptions): Promise<EmptyResponse>;
    (callback: NormalCallback<google.protobuf.IEmpty>): void;
    (
        gaxOpts: CallOptions,
        callback: NormalCallback<google.protobuf.IEmpty>
    ): void;
};

• Delete the subscription. Pull requests from the current subscription will be errored once unsubscription is complete.

  Parameter gaxOpts

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

  Parameter callback

  The callback function.

  Parameter

  {?error} callback.err An error returned while making this request.

  Parameter

  {object} callback.apiResponse Raw API response.

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  subscription.delete((err, apiResponse) => {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  subscription.delete().then((data) => {
    const apiResponse = data[0];
  });

  See Also

  • [Subscriptions: delete API Documentation]https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions/delete

method detached

detached: {
    (): Promise<DetachedResponse>;
    (callback: NormalCallback<boolean>): void;
};

• Check if a subscription is detached.

  Parameter callback

  Callback function.

  Returns

  {Promise}

  Example 1

  const {PubSub} = require('@google-cloud/pubsub');
  const pubsub = new PubSub();
  
  const topic = pubsub.topic('my-topic');
  const subscription = topic.subscription('my-subscription');
  
  subscription.detached((err, exists) => {});
  
  //-
  // If the callback is omitted, we'll return a Promise.
  //-
  subscription.detached().then((data) => {
    const detached = data[0];
  });

method exists

exists: {
    (): Promise<ExistsResponse>;
    (callback: NormalCallback<boolean>): void;
};