Class: Google::Cloud::Pubsub::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/pubsub/project.rb

Overview

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

Examples:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

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

Instance Method Summary collapse

Instance Method Details

#create_topic(topic_name) ⇒ Google::Cloud::Pubsub::Topic Also known as: new_topic

Creates a new topic.

Examples:

require "google/cloud/pubsub"

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

Parameters:

  • topic_name (String) —

    Name of a topic.

Returns:



162
163
164
165
166
 
# File 'lib/google/cloud/pubsub/project.rb', line 162

def create_topic topic_name
  ensure_service!
  grpc = service.create_topic topic_name
  Topic.from_grpc grpc, service
end

#project ⇒ Object

The Pub/Sub project connected to.

Examples:

require "google/cloud/pubsub"

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

pubsub.project #=> "my-project"


70
71
72
 
# File 'lib/google/cloud/pubsub/project.rb', line 70

def project
  service.project
end

#publish(topic_name, data = nil, attributes = {}) {|publisher| ... } ⇒ Message+

Publishes one or more messages to the given topic. The topic will be created if the topic does previously not exist and the autocreate option is provided.

A note about auto-creating the topic: Any message published to a topic without a subscription will be lost.

Examples:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

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

A message can be published using a File object:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

msg = pubsub.publish "my-topic", File.open("message.txt")

Additionally, a message can be published with attributes:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

msg = pubsub.publish "my-topic", "task completed", foo: :bar,
                                                this: :that

Multiple messages can be sent at the same time using a block:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

msgs = pubsub.publish "my-topic" do |p|
  p.publish "task 1 completed", foo: :bar
  p.publish "task 2 completed", foo: :baz
  p.publish "task 3 completed", foo: :bif
end

With autocreate:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

msg = pubsub.publish "new-topic", "task completed", autocreate: true

Parameters:

  • topic_name (String) —

    Name of a topic.

  • data (String, File) (defaults to: nil) —

    The message data.

  • attributes (Hash) (defaults to: {}) —

    Optional attributes for the message.

Options Hash (attributes):

  • :autocreate (Boolean) —

    Flag to control whether the provided topic will be created if it does not exist.

Yields:

  • (publisher) —

    a block for publishing multiple messages in one request

Yield Parameters:

Returns:

  • (Message, Array<Message>) —

    Returns the published message when called without a block, or an array of messages when called with a block.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/google/cloud/pubsub/project.rb', line 270

def publish topic_name, data = nil, attributes = {}
  # Fix parameters
  if data.is_a?(::Hash) && attributes.empty?
    attributes = data
    data = nil
  end
  # extract autocreate option
  autocreate = attributes.delete :autocreate
  ensure_service!
  publisher = Topic::Publisher.new data, attributes
  yield publisher if block_given?
  return nil if publisher.messages.count.zero?
  publish_batch_messages topic_name, publisher, autocreate
end

#snapshots(token: nil, max: nil) ⇒ Array<Google::Cloud::Pubsub::Snapshot> Also known as: find_snapshots, list_snapshots

Retrieves a list of snapshots for the given project.

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

Parameters:

  • token (String) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) —

    Maximum number of snapshots to return.

Returns:



480
481
482
483
484
485
 
# File 'lib/google/cloud/pubsub/project.rb', line 480

def snapshots token: nil, max: nil
  ensure_service!
  options = { token: token, max: max }
  grpc = service.list_snapshots options
  Snapshot::List.from_grpc grpc, service, max
end

#subscribe(topic_name, subscription_name, deadline: nil, retain_acked: false, retention: nil, endpoint: nil, autocreate: nil) ⇒ Google::Cloud::Pubsub::Subscription Also known as: create_subscription, new_subscription

Creates a new Subscription object for the provided topic. The topic will be created if the topic does previously not exist and the autocreate option is provided.

Examples:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

sub = pubsub.subscribe "my-topic", "my-topic-sub"
sub.name #=> "my-topic-sub"

Wait 2 minutes for acknowledgement and push all to endpoint:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

sub = pubsub.subscribe "my-topic", "my-topic-sub",
                       deadline: 120,
                       endpoint: "https://example.com/push"

With autocreate:

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new

sub = pubsub.subscribe "new-topic", "new-topic-sub",
                       autocreate: true

Parameters:

  • topic_name (String) —

    Name of a topic.

  • subscription_name (String) —

    Name of the new subscription. 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".

  • deadline (Integer) —

    The maximum number of seconds after a subscriber receives a message before the subscriber should acknowledge the message.

  • retain_acked (Boolean) —

    Indicates whether to retain acknowledged messages. If true, then messages are not expunged from the subscription's backlog, even if they are acknowledged, until they fall out of the retention_duration window. Default is false.

  • retention (Numeric) —

    How long to retain unacknowledged messages in the subscription's backlog, from the moment a message is published. If retain_acked is true, then this also configures the retention of acknowledged messages, and thus configures how far back in time a #seek can be done. Cannot be more than 604,800 seconds (7 days) or less than 600 seconds (10 minutes). Default is 604,800 seconds (7 days).

  • endpoint (String) —

    A URL locating the endpoint to which messages should be pushed.

  • autocreate (String) —

    Flag to control whether the topic will be created if it does not exist.

Returns:



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'lib/google/cloud/pubsub/project.rb', line 342

def subscribe topic_name, subscription_name, deadline: nil,
              retain_acked: false, retention: nil, endpoint: nil,
              autocreate: nil
  ensure_service!
  options = { deadline: deadline, retain_acked: retain_acked,
              retention: retention, endpoint: endpoint }
  grpc = service.create_subscription topic_name,
                                     subscription_name, options
  Subscription.from_grpc grpc, service
rescue Google::Cloud::NotFoundError => e
  if autocreate
    create_topic topic_name
    return subscribe(topic_name, subscription_name,
                     deadline: deadline, retain_acked: retain_acked,
                     retention: retention, endpoint: endpoint,
                     autocreate: false)
  end
  raise e
end

#subscription(subscription_name, project: nil, skip_lookup: nil) ⇒ Google::Cloud::Pubsub::Subscription? Also known as: get_subscription, find_subscription

Retrieves subscription by name.

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"

Parameters:

  • subscription_name (String) —

    Name of a subscription.

  • project (String) —

    If the subscription belongs to a project other than the one currently connected to, the alternate project ID can be specified here.

  • skip_lookup (Boolean) —

    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:



396
397
398
399
400
401
402
403
404
405
406
 
# File 'lib/google/cloud/pubsub/project.rb', line 396

def subscription subscription_name, project: nil, skip_lookup: nil
  ensure_service!
  options = { project: project }
  if skip_lookup
    return Subscription.new_lazy subscription_name, service, options
  end
  grpc = service.get_subscription subscription_name
  Subscription.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#subscriptions(token: nil, max: nil) ⇒ Array<Google::Cloud::Pubsub::Subscription> Also known as: find_subscriptions, list_subscriptions

Retrieves a list of subscriptions for the given project.

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

Parameters:

  • token (String) —

    A previously-returned page token representing part of the larger set of results to view.

  • max (Integer) —

    Maximum number of subscriptions to return.

Returns:



440
441
442
443
444
445
 
# File 'lib/google/cloud/pubsub/project.rb', line 440

def subscriptions token: nil, max: nil
  ensure_service!
  options = { token: token, max: max }
  grpc = service.list_subscriptions options
  Subscription::List.from_grpc grpc, service, max
end

#topic(topic_name, autocreate: nil, project: nil, skip_lookup: nil) ⇒ Google::Cloud::Pubsub::Topic? Also known as: get_topic, find_topic

Retrieves topic by name.

The topic will be created if the topic does not exist and the autocreate option is set to true.

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

With the autocreate option set to true.

require "google/cloud/pubsub"

pubsub = Google::Cloud::Pubsub.new
topic = pubsub.topic "non-existing-topic", autocreate: true

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

Parameters:

  • topic_name (String) —

    Name of a topic.

  • autocreate (Boolean) —

    Flag to control whether the requested topic will be created if it does not exist. Ignored if skip_lookup is true. The default value is false.

  • project (String) —

    If the topic belongs to a project other than the one currently connected to, the alternate project ID can be specified here.

  • skip_lookup (Boolean) —

    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.

Returns:

  • (Google::Cloud::Pubsub::Topic, nil) —

    Returns nil if topic does not exist. Will return a newly created{ Google::Cloud::Pubsub::Topic} if the topic does not exist and autocreate is set to true.



136
137
138
139
140
141
142
143
144
145
 
# File 'lib/google/cloud/pubsub/project.rb', line 136

def topic topic_name, autocreate: nil, project: nil, skip_lookup: nil
  ensure_service!
  options = { project: project }
  return Topic.new_lazy(topic_name, service, options) if skip_lookup
  grpc = service.get_topic topic_name
  Topic.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  return create_topic(topic_name) if autocreate
  nil
end

#topics(token: nil, max: nil) ⇒ Array<Google::Cloud::Pubsub::Topic> Also known as: find_topics, list_topics

Retrieves a list of topics for the given project.

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

Parameters:

  • token (String) —

    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) —

    Maximum number of topics to return.

Returns:



200
201
202
203
204
205
 
# File 'lib/google/cloud/pubsub/project.rb', line 200

def topics token: nil, max: nil
  ensure_service!
  options = { token: token, max: max }
  grpc = service.list_topics options
  Topic::List.from_grpc grpc, service, max
end