Cloud Pub/Sub API - Class Google::Cloud::PubSub::Project (v2.15.1)

Reference documentation and code samples for the Cloud Pub/Sub API class Google::Cloud::PubSub::Project.

Project

Represents the project that pubsub messages are pushed to and pulled from. Topic is a named resource to which messages are sent by publishers. Subscription is a named resource representing the stream of messages from a single, specific topic, to be delivered to the subscribing application. Message is a combination of data and attributes that a publisher sends to a topic and is eventually delivered to subscribers.

See Google::Cloud#pubsub

Inherits

  • Object

Example

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topic = pubsub.topic "my-topic"
topic.publish "task completed"

Methods

#create_schema

def create_schema(schema_id, type, definition, project: nil) -> Google::Cloud::PubSub::Schema
Aliases

Creates a new schema.

Parameters
  • schema_id (String) — The ID to use for the schema, which will become the final component of the schema's resource name. Required.

    The schema ID (relative name) 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.

  • type (String, Symbol) —

    The type of the schema. Required. Possible values are case-insensitive and include:

    • PROTOCOL_BUFFER - A Protocol Buffer schema definition.
    • AVRO - An Avro schema definition.
  • definition (String) — The definition of the schema. Required. This should be a string representing the full definition of the schema that is a valid schema definition of the type specified in type.
  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional.
Returns
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

definition = "..."
schema = pubsub.create_schema "my-schema", :avro, definition
schema.name #=> "projects/my-project/schemas/my-schema"

#create_topic

def create_topic(topic_name, labels: nil, kms_key: nil, persistence_regions: nil, async: nil, schema_name: nil, message_encoding: nil, retention: nil) -> Google::Cloud::PubSub::Topic
Aliases

Creates a new topic.

Parameters
  • topic_name (String) — Name of a topic. Required. The value can be a simple topic ID (relative name), in which case the current project ID will be supplied, or a fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.

    The topic ID (relative name) 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 (Hash) (defaults to: nil) — A hash of user-provided labels associated with the topic. You can use these to organize and group your topics. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter and each label in the list must have a different key. See Creating and Managing Labels.
  • kms_key (String) (defaults to: nil) — The Cloud KMS encryption key that will be used to protect access to messages published on this topic. Optional. For example: projects/a/locations/b/keyRings/c/cryptoKeys/d
  • persistence_regions (Array<String>) (defaults to: nil) — The list of GCP region IDs where messages that are published to the topic may be persisted in storage. Optional.
  • async (Hash) (defaults to: nil) —

    A hash of values to configure the topic's AsyncPublisher that is created when Topic#publish_async is called. Optional.

    Hash keys and values may include the following:

    • :max_bytes (Integer) The maximum size of messages to be collected before the batch is published. Default is 1,000,000 (1MB).
    • :max_messages (Integer) The maximum number of messages to be collected before the batch is published. Default is 100.
    • :interval (Numeric) The number of seconds to collect messages before the batch is published. Default is 0.01.
    • :threads (Hash) The number of threads to create to handle concurrent calls by the publisher:
      • :publish (Integer) The number of threads used to publish messages. Default is 2.
      • :callback (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
    • :compress (Boolean) The flag that enables publisher compression. Default is false
    • :compression_bytes_threshold (Integer) The number of bytes above which compress should be enabled. Default is 240.
    • :flow_control (Hash) The client flow control settings for message publishing:
      • :message_limit (Integer) The maximum number of messages allowed to wait to be published. Default is 10 * max_messages.
      • :byte_limit (Integer) The maximum total size of messages allowed to wait to be published. Default is 10 * max_bytes.
      • :limit_exceeded_behavior (Symbol) The action to take when publish flow control limits are exceeded. Possible values include: :ignore - Flow control is disabled. :error - Calls to Topic#publish_async will raise FlowControlLimitError when publish flow control limits are exceeded. :block - Calls to Topic#publish_async will block until capacity is available when publish flow control limits are exceeded. The default value is :ignore.
  • schema_name (String) (defaults to: nil) — The name of the schema that messages published should be validated against. Optional. The value can be a simple schema ID (relative name), in which case the current project ID will be supplied, or a fully-qualified schema name in the form projects/{project_id}/schemas/{schema_id}. If provided, message_encoding must also be provided.
  • message_encoding (String, Symbol) (defaults to: nil) —

    The encoding of messages validated against the schema identified by schema_name. Optional. Values include:

    • JSON - JSON encoding.
    • BINARY - Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be available.
  • retention (Numeric) (defaults to: nil) — Indicates the minimum number of seconds to retain a message after it is published to the topic. If this field is set, messages published to the topic within the retention number of seconds are always available to subscribers. For instance, it allows any attached subscription to seek to a timestamp that is up to retention number of seconds in the past. If this field is not set, message retention is controlled by settings on individual subscriptions. Cannot be less than 600 (10 minutes) or more than 604,800 (7 days).
Returns
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.create_topic "my-topic"

#find_schema

def find_schema(schema_name, view: nil, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Schema, nil
Alias Of: #schema

Retrieves schema by name.

Parameters
  • schema_name (String) — Name of a schema. The value can be a simple schema ID, in which case the current project ID will be supplied, or a fully-qualified schema name in the form projects/{project_id}/schemas/{schema_id}.
  • view (Symbol, String, nil) (defaults to: nil) — Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.

    The default value is FULL.

  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified schema name is provided for schema_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Schema object without verifying the schema resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema"
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition # The schema definition

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the schema information.
# The default project is used in the name.
schema = pubsub.schema "my-schema", skip_lookup: true
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> nil
schema.definition #=> nil

Omit the schema definition with view: :basic:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema", view: :basic
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition #=> nil

#find_schemas

def find_schemas(view: nil, token: nil, max: nil) -> Array<Google::Cloud::PubSub::Schema>
Alias Of: #schemas

Retrieves a list of schemas for the given project.

The default value is FULL.

Parameters
  • view (String, Symbol, nil) (defaults to: nil) —

    The set of fields to return in the response. Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of schemas to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.each do |schema|
  puts schema.name
end

Retrieve all schemas: (See Schema::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.all do |schema|
  puts schema.name
end

#find_snapshots

def find_snapshots(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Snapshot>
Alias Of: #snapshots

Retrieves a list of snapshots for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of snapshots to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.each do |snapshot|
  puts snapshot.name
end

Retrieve all snapshots: (See Snapshot::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.all do |snapshot|
  puts snapshot.name
end

#find_subscription

def find_subscription(subscription_name, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Subscription, nil
Alias Of: #subscription

Retrieves subscription by name.

Parameters
  • subscription_name (String) — Name of a subscription. The value can be a simple subscription ID, in which case the current project ID will be supplied, or a fully-qualified subscription name in the form projects/{project_id}/subscriptions/{subscription_id}.
  • project (String) (defaults to: nil) — If the subscription belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified subscription name is provided for subscription_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Subscription object without verifying the subscription resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

sub = pubsub.subscription "my-sub"
sub.name #=> "projects/my-project/subscriptions/my-sub"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the subscription information.
sub = pubsub.subscription "my-sub", skip_lookup: true
sub.name #=> "projects/my-project/subscriptions/my-sub"

#find_subscriptions

def find_subscriptions(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Subscription>
Alias Of: #subscriptions

Retrieves a list of subscriptions for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of subscriptions to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.each do |sub|
  puts sub.name
end

Retrieve all subscriptions: (See Subscription::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.all do |sub|
  puts sub.name
end

#find_topic

def find_topic(topic_name, project: nil, skip_lookup: nil, async: nil) -> Google::Cloud::PubSub::Topic, nil
Alias Of: #topic

Retrieves topic by name.

Parameters
  • topic_name (String) — Name of a topic. The value can be a simple topic ID (relative name), in which case the current project ID will be supplied, or a fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.
  • project (String) (defaults to: nil) — If the topic belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional. Not used if a fully-qualified topic name is provided for topic_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Topic object without verifying the topic resource exists on the Pub/Sub service. Calls made on this object will raise errors if the topic resource does not exist. Default is false. Optional.
  • async (Hash) (defaults to: nil) —

    A hash of values to configure the topic's AsyncPublisher that is created when Topic#publish_async is called. Optional.

    Hash keys and values may include the following:

    • :max_bytes (Integer) The maximum size of messages to be collected before the batch is published. Default is 1,000,000 (1MB).
    • :max_messages (Integer) The maximum number of messages to be collected before the batch is published. Default is 100.
    • :interval (Numeric) The number of seconds to collect messages before the batch is published. Default is 0.01.
    • :threads (Hash) The number of threads to create to handle concurrent calls by the publisher:
      • :publish (Integer) The number of threads used to publish messages. Default is 2.
      • :callback (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
    • :compress (Boolean) The flag that enables publisher compression. Default is false
    • :compression_bytes_threshold (Integer) The number of bytes above which compress should be enabled. Default is 240.
    • :flow_control (Hash) The client flow control settings for message publishing:
      • :message_limit (Integer) The maximum number of messages allowed to wait to be published. Default is 10 * max_messages.
      • :byte_limit (Integer) The maximum total size of messages allowed to wait to be published. Default is 10 * max_bytes.
      • :limit_exceeded_behavior (Symbol) The action to take when publish flow control limits are exceeded. Possible values include: :ignore - Flow control is disabled. :error - Calls to Topic#publish_async will raise FlowControlLimitError when publish flow control limits are exceeded. :block - Calls to Topic#publish_async will block until capacity is available when publish flow control limits are exceeded. The default value is :ignore.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "existing-topic"

By default nil will be returned if topic does not exist.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "non-existing-topic" # nil

Create topic in a different project with the project flag.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", project: "another-project"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", skip_lookup: true

Configuring AsyncPublisher to increase concurrent callbacks:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "my-topic",
                     async: { threads: { callback: 16 } }

topic.publish_async "task completed" do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

topic.async_publisher.stop!

#find_topics

def find_topics(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Topic>
Alias Of: #topics

Retrieves a list of topics for the given project.

Parameters
  • token (String) (defaults to: nil) — The token value returned by the last call to topics; indicates that this is a continuation of a call, and that the system should return the next page of data.
  • max (Integer) (defaults to: nil) — Maximum number of topics to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.each do |topic|
  puts topic.name
end

Retrieve all topics: (See Topic::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.all do |topic|
  puts topic.name
end

#get_schema

def get_schema(schema_name, view: nil, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Schema, nil
Alias Of: #schema

Retrieves schema by name.

Parameters
  • schema_name (String) — Name of a schema. The value can be a simple schema ID, in which case the current project ID will be supplied, or a fully-qualified schema name in the form projects/{project_id}/schemas/{schema_id}.
  • view (Symbol, String, nil) (defaults to: nil) — Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.

    The default value is FULL.

  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified schema name is provided for schema_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Schema object without verifying the schema resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema"
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition # The schema definition

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the schema information.
# The default project is used in the name.
schema = pubsub.schema "my-schema", skip_lookup: true
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> nil
schema.definition #=> nil

Omit the schema definition with view: :basic:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema", view: :basic
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition #=> nil

#get_subscription

def get_subscription(subscription_name, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Subscription, nil
Alias Of: #subscription

Retrieves subscription by name.

Parameters
  • subscription_name (String) — Name of a subscription. The value can be a simple subscription ID, in which case the current project ID will be supplied, or a fully-qualified subscription name in the form projects/{project_id}/subscriptions/{subscription_id}.
  • project (String) (defaults to: nil) — If the subscription belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified subscription name is provided for subscription_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Subscription object without verifying the subscription resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

sub = pubsub.subscription "my-sub"
sub.name #=> "projects/my-project/subscriptions/my-sub"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the subscription information.
sub = pubsub.subscription "my-sub", skip_lookup: true
sub.name #=> "projects/my-project/subscriptions/my-sub"

#get_topic

def get_topic(topic_name, project: nil, skip_lookup: nil, async: nil) -> Google::Cloud::PubSub::Topic, nil
Alias Of: #topic

Retrieves topic by name.

Parameters
  • topic_name (String) — Name of a topic. The value can be a simple topic ID (relative name), in which case the current project ID will be supplied, or a fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.
  • project (String) (defaults to: nil) — If the topic belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional. Not used if a fully-qualified topic name is provided for topic_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Topic object without verifying the topic resource exists on the Pub/Sub service. Calls made on this object will raise errors if the topic resource does not exist. Default is false. Optional.
  • async (Hash) (defaults to: nil) —

    A hash of values to configure the topic's AsyncPublisher that is created when Topic#publish_async is called. Optional.

    Hash keys and values may include the following:

    • :max_bytes (Integer) The maximum size of messages to be collected before the batch is published. Default is 1,000,000 (1MB).
    • :max_messages (Integer) The maximum number of messages to be collected before the batch is published. Default is 100.
    • :interval (Numeric) The number of seconds to collect messages before the batch is published. Default is 0.01.
    • :threads (Hash) The number of threads to create to handle concurrent calls by the publisher:
      • :publish (Integer) The number of threads used to publish messages. Default is 2.
      • :callback (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
    • :compress (Boolean) The flag that enables publisher compression. Default is false
    • :compression_bytes_threshold (Integer) The number of bytes above which compress should be enabled. Default is 240.
    • :flow_control (Hash) The client flow control settings for message publishing:
      • :message_limit (Integer) The maximum number of messages allowed to wait to be published. Default is 10 * max_messages.
      • :byte_limit (Integer) The maximum total size of messages allowed to wait to be published. Default is 10 * max_bytes.
      • :limit_exceeded_behavior (Symbol) The action to take when publish flow control limits are exceeded. Possible values include: :ignore - Flow control is disabled. :error - Calls to Topic#publish_async will raise FlowControlLimitError when publish flow control limits are exceeded. :block - Calls to Topic#publish_async will block until capacity is available when publish flow control limits are exceeded. The default value is :ignore.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "existing-topic"

By default nil will be returned if topic does not exist.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "non-existing-topic" # nil

Create topic in a different project with the project flag.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", project: "another-project"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", skip_lookup: true

Configuring AsyncPublisher to increase concurrent callbacks:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "my-topic",
                     async: { threads: { callback: 16 } }

topic.publish_async "task completed" do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

topic.async_publisher.stop!

#list_schemas

def list_schemas(view: nil, token: nil, max: nil) -> Array<Google::Cloud::PubSub::Schema>
Alias Of: #schemas

Retrieves a list of schemas for the given project.

The default value is FULL.

Parameters
  • view (String, Symbol, nil) (defaults to: nil) —

    The set of fields to return in the response. Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of schemas to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.each do |schema|
  puts schema.name
end

Retrieve all schemas: (See Schema::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.all do |schema|
  puts schema.name
end

#list_snapshots

def list_snapshots(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Snapshot>
Alias Of: #snapshots

Retrieves a list of snapshots for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of snapshots to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.each do |snapshot|
  puts snapshot.name
end

Retrieve all snapshots: (See Snapshot::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.all do |snapshot|
  puts snapshot.name
end

#list_subscriptions

def list_subscriptions(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Subscription>
Alias Of: #subscriptions

Retrieves a list of subscriptions for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of subscriptions to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.each do |sub|
  puts sub.name
end

Retrieve all subscriptions: (See Subscription::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.all do |sub|
  puts sub.name
end

#list_topics

def list_topics(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Topic>
Alias Of: #topics

Retrieves a list of topics for the given project.

Parameters
  • token (String) (defaults to: nil) — The token value returned by the last call to topics; indicates that this is a continuation of a call, and that the system should return the next page of data.
  • max (Integer) (defaults to: nil) — Maximum number of topics to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.each do |topic|
  puts topic.name
end

Retrieve all topics: (See Topic::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.all do |topic|
  puts topic.name
end

#new_schema

def new_schema(schema_id, type, definition, project: nil) -> Google::Cloud::PubSub::Schema
Alias Of: #create_schema

Creates a new schema.

Parameters
  • schema_id (String) — The ID to use for the schema, which will become the final component of the schema's resource name. Required.

    The schema ID (relative name) 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.

  • type (String, Symbol) —

    The type of the schema. Required. Possible values are case-insensitive and include:

    • PROTOCOL_BUFFER - A Protocol Buffer schema definition.
    • AVRO - An Avro schema definition.
  • definition (String) — The definition of the schema. Required. This should be a string representing the full definition of the schema that is a valid schema definition of the type specified in type.
  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional.
Returns
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

definition = "..."
schema = pubsub.create_schema "my-schema", :avro, definition
schema.name #=> "projects/my-project/schemas/my-schema"

#new_topic

def new_topic(topic_name, labels: nil, kms_key: nil, persistence_regions: nil, async: nil, schema_name: nil, message_encoding: nil, retention: nil) -> Google::Cloud::PubSub::Topic
Alias Of: #create_topic

Creates a new topic.

Parameters
  • topic_name (String) — Name of a topic. Required. The value can be a simple topic ID (relative name), in which case the current project ID will be supplied, or a fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.

    The topic ID (relative name) 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 (Hash) (defaults to: nil) — A hash of user-provided labels associated with the topic. You can use these to organize and group your topics. Label keys and values can be no longer than 63 characters, can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter and each label in the list must have a different key. See Creating and Managing Labels.
  • kms_key (String) (defaults to: nil) — The Cloud KMS encryption key that will be used to protect access to messages published on this topic. Optional. For example: projects/a/locations/b/keyRings/c/cryptoKeys/d
  • persistence_regions (Array<String>) (defaults to: nil) — The list of GCP region IDs where messages that are published to the topic may be persisted in storage. Optional.
  • async (Hash) (defaults to: nil) —

    A hash of values to configure the topic's AsyncPublisher that is created when Topic#publish_async is called. Optional.

    Hash keys and values may include the following:

    • :max_bytes (Integer) The maximum size of messages to be collected before the batch is published. Default is 1,000,000 (1MB).
    • :max_messages (Integer) The maximum number of messages to be collected before the batch is published. Default is 100.
    • :interval (Numeric) The number of seconds to collect messages before the batch is published. Default is 0.01.
    • :threads (Hash) The number of threads to create to handle concurrent calls by the publisher:
      • :publish (Integer) The number of threads used to publish messages. Default is 2.
      • :callback (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
    • :compress (Boolean) The flag that enables publisher compression. Default is false
    • :compression_bytes_threshold (Integer) The number of bytes above which compress should be enabled. Default is 240.
    • :flow_control (Hash) The client flow control settings for message publishing:
      • :message_limit (Integer) The maximum number of messages allowed to wait to be published. Default is 10 * max_messages.
      • :byte_limit (Integer) The maximum total size of messages allowed to wait to be published. Default is 10 * max_bytes.
      • :limit_exceeded_behavior (Symbol) The action to take when publish flow control limits are exceeded. Possible values include: :ignore - Flow control is disabled. :error - Calls to Topic#publish_async will raise FlowControlLimitError when publish flow control limits are exceeded. :block - Calls to Topic#publish_async will block until capacity is available when publish flow control limits are exceeded. The default value is :ignore.
  • schema_name (String) (defaults to: nil) — The name of the schema that messages published should be validated against. Optional. The value can be a simple schema ID (relative name), in which case the current project ID will be supplied, or a fully-qualified schema name in the form projects/{project_id}/schemas/{schema_id}. If provided, message_encoding must also be provided.
  • message_encoding (String, Symbol) (defaults to: nil) —

    The encoding of messages validated against the schema identified by schema_name. Optional. Values include:

    • JSON - JSON encoding.
    • BINARY - Binary encoding, as defined by the schema type. For some schema types, binary encoding may not be available.
  • retention (Numeric) (defaults to: nil) — Indicates the minimum number of seconds to retain a message after it is published to the topic. If this field is set, messages published to the topic within the retention number of seconds are always available to subscribers. For instance, it allows any attached subscription to seek to a timestamp that is up to retention number of seconds in the past. If this field is not set, message retention is controlled by settings on individual subscriptions. Cannot be less than 600 (10 minutes) or more than 604,800 (7 days).
Returns
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.create_topic "my-topic"

#project

def project()
Alias Of: #project_id

The Pub/Sub project connected to.

Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

pubsub.project_id #=> "my-project"

#project_id

def project_id()
Aliases

The Pub/Sub project connected to.

Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

pubsub.project_id #=> "my-project"

#schema

def schema(schema_name, view: nil, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Schema, nil
Aliases

Retrieves schema by name.

Parameters
  • schema_name (String) — Name of a schema. The value can be a simple schema ID, in which case the current project ID will be supplied, or a fully-qualified schema name in the form projects/{project_id}/schemas/{schema_id}.
  • view (Symbol, String, nil) (defaults to: nil) — Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.

    The default value is FULL.

  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified schema name is provided for schema_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Schema object without verifying the schema resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema"
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition # The schema definition

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the schema information.
# The default project is used in the name.
schema = pubsub.schema "my-schema", skip_lookup: true
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> nil
schema.definition #=> nil

Omit the schema definition with view: :basic:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schema = pubsub.schema "my-schema", view: :basic
schema.name #=> "projects/my-project/schemas/my-schema"
schema.type #=> :PROTOCOL_BUFFER
schema.definition #=> nil

#schemas

def schemas(view: nil, token: nil, max: nil) -> Array<Google::Cloud::PubSub::Schema>
Aliases

Retrieves a list of schemas for the given project.

The default value is FULL.

Parameters
  • view (String, Symbol, nil) (defaults to: nil) —

    The set of fields to return in the response. Possible values:

    • BASIC - Include the name and type of the schema, but not the definition.
    • FULL - Include all Schema object fields.
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of schemas to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.each do |schema|
  puts schema.name
end

Retrieve all schemas: (See Schema::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

schemas = pubsub.schemas
schemas.all do |schema|
  puts schema.name
end

#snapshots

def snapshots(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Snapshot>
Aliases

Retrieves a list of snapshots for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of snapshots to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.each do |snapshot|
  puts snapshot.name
end

Retrieve all snapshots: (See Snapshot::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

snapshots = pubsub.snapshots
snapshots.all do |snapshot|
  puts snapshot.name
end

#subscription

def subscription(subscription_name, project: nil, skip_lookup: nil) -> Google::Cloud::PubSub::Subscription, nil
Aliases

Retrieves subscription by name.

Parameters
  • subscription_name (String) — Name of a subscription. The value can be a simple subscription ID, in which case the current project ID will be supplied, or a fully-qualified subscription name in the form projects/{project_id}/subscriptions/{subscription_id}.
  • project (String) (defaults to: nil) — If the subscription belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Not used if a fully-qualified subscription name is provided for subscription_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Subscription object without verifying the subscription resource exists on the Pub/Sub service. Calls made on this object will raise errors if the service resource does not exist. Default is false.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

sub = pubsub.subscription "my-sub"
sub.name #=> "projects/my-project/subscriptions/my-sub"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

# No API call is made to retrieve the subscription information.
sub = pubsub.subscription "my-sub", skip_lookup: true
sub.name #=> "projects/my-project/subscriptions/my-sub"

#subscriptions

def subscriptions(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Subscription>
Aliases

Retrieves a list of subscriptions for the given project.

Parameters
  • token (String) (defaults to: nil) — A previously-returned page token representing part of the larger set of results to view.
  • max (Integer) (defaults to: nil) — Maximum number of subscriptions to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.each do |sub|
  puts sub.name
end

Retrieve all subscriptions: (See Subscription::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

subs = pubsub.subscriptions
subs.all do |sub|
  puts sub.name
end

#topic

def topic(topic_name, project: nil, skip_lookup: nil, async: nil) -> Google::Cloud::PubSub::Topic, nil
Aliases

Retrieves topic by name.

Parameters
  • topic_name (String) — Name of a topic. The value can be a simple topic ID (relative name), in which case the current project ID will be supplied, or a fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.
  • project (String) (defaults to: nil) — If the topic belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional. Not used if a fully-qualified topic name is provided for topic_name.
  • skip_lookup (Boolean) (defaults to: nil) — Optionally create a Topic object without verifying the topic resource exists on the Pub/Sub service. Calls made on this object will raise errors if the topic resource does not exist. Default is false. Optional.
  • async (Hash) (defaults to: nil) —

    A hash of values to configure the topic's AsyncPublisher that is created when Topic#publish_async is called. Optional.

    Hash keys and values may include the following:

    • :max_bytes (Integer) The maximum size of messages to be collected before the batch is published. Default is 1,000,000 (1MB).
    • :max_messages (Integer) The maximum number of messages to be collected before the batch is published. Default is 100.
    • :interval (Numeric) The number of seconds to collect messages before the batch is published. Default is 0.01.
    • :threads (Hash) The number of threads to create to handle concurrent calls by the publisher:
      • :publish (Integer) The number of threads used to publish messages. Default is 2.
      • :callback (Integer) The number of threads to handle the published messages' callbacks. Default is 4.
    • :compress (Boolean) The flag that enables publisher compression. Default is false
    • :compression_bytes_threshold (Integer) The number of bytes above which compress should be enabled. Default is 240.
    • :flow_control (Hash) The client flow control settings for message publishing:
      • :message_limit (Integer) The maximum number of messages allowed to wait to be published. Default is 10 * max_messages.
      • :byte_limit (Integer) The maximum total size of messages allowed to wait to be published. Default is 10 * max_bytes.
      • :limit_exceeded_behavior (Symbol) The action to take when publish flow control limits are exceeded. Possible values include: :ignore - Flow control is disabled. :error - Calls to Topic#publish_async will raise FlowControlLimitError when publish flow control limits are exceeded. :block - Calls to Topic#publish_async will block until capacity is available when publish flow control limits are exceeded. The default value is :ignore.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "existing-topic"

By default nil will be returned if topic does not exist.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "non-existing-topic" # nil

Create topic in a different project with the project flag.

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", project: "another-project"

Skip the lookup against the service with skip_lookup:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "another-topic", skip_lookup: true

Configuring AsyncPublisher to increase concurrent callbacks:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new
topic = pubsub.topic "my-topic",
                     async: { threads: { callback: 16 } }

topic.publish_async "task completed" do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

topic.async_publisher.stop!

#topics

def topics(token: nil, max: nil) -> Array<Google::Cloud::PubSub::Topic>
Aliases

Retrieves a list of topics for the given project.

Parameters
  • token (String) (defaults to: nil) — The token value returned by the last call to topics; indicates that this is a continuation of a call, and that the system should return the next page of data.
  • max (Integer) (defaults to: nil) — Maximum number of topics to return.
Returns
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.each do |topic|
  puts topic.name
end

Retrieve all topics: (See Topic::List#all)

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

topics = pubsub.topics
topics.all do |topic|
  puts topic.name
end

#valid_schema?

def valid_schema?(type, definition, project: nil) -> Boolean
Aliases

Validates a schema type and definition.

Parameters
  • type (String, Symbol) —

    The type of the schema. Required. Possible values are case-insensitive and include:

    • PROTOCOL_BUFFER - A Protocol Buffer schema definition.
    • AVRO - An Avro schema definition.
  • definition (String) — The definition of the schema. Required. This should be a string representing the full definition of the schema that is a valid schema definition of the type specified in type.
  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional.
Returns
  • (Boolean) — true if the schema is valid, false otherwise.
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

definition = "..."
pubsub.validate_schema :avro, definition #=> true

#validate_schema

def validate_schema(type, definition, project: nil) -> Boolean
Alias Of: #valid_schema?

Validates a schema type and definition.

Parameters
  • type (String, Symbol) —

    The type of the schema. Required. Possible values are case-insensitive and include:

    • PROTOCOL_BUFFER - A Protocol Buffer schema definition.
    • AVRO - An Avro schema definition.
  • definition (String) — The definition of the schema. Required. This should be a string representing the full definition of the schema that is a valid schema definition of the type specified in type.
  • project (String) (defaults to: nil) — If the schema belongs to a project other than the one currently connected to, the alternate project ID can be specified here. Optional.
Returns
  • (Boolean) — true if the schema is valid, false otherwise.
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

definition = "..."
pubsub.validate_schema :avro, definition #=> true