Class: Gcloud::Pubsub::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/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 Gcloud#pubsub

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(service) ⇒ Project 



52
53
54
 
# File 'lib/gcloud/pubsub/project.rb', line 52

def initialize service
  @service = service
end

Instance Attribute Details

#service ⇒ Object 



48
49
50
 
# File 'lib/gcloud/pubsub/project.rb', line 48

def service
  @service
end

Class Method Details

.default_project ⇒ Object 



73
74
75
76
77
78
 
# File 'lib/gcloud/pubsub/project.rb', line 73

def self.default_project
  ENV["PUBSUB_PROJECT"] ||
    ENV["GCLOUD_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"] ||
    Gcloud::GCE.project_id
end

Instance Method Details

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

Creates a new topic.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.create_topic "my-topic"



164
165
166
167
168
 
# File 'lib/gcloud/pubsub/project.rb', line 164

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 "gcloud"

gcloud = Gcloud.new "my-todo-project",
                    "/path/to/keyfile.json"
pubsub = gcloud.pubsub

pubsub.project #=> "my-todo-project"



67
68
69
 
# File 'lib/gcloud/pubsub/project.rb', line 67

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 "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

msg = pubsub.publish "my-topic", "new-message"

A message can be published using a File object:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Additionally, a message can be published with attributes:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

msg = pubsub.publish "my-topic", "new-message", foo: :bar,
                                                this: :that

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

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

With ‘autocreate`:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

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:



279
280
281
282
283
284
285
286
287
288
289
290
291
292
 
# File 'lib/gcloud/pubsub/project.rb', line 279

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

#subscribe(topic_name, subscription_name, deadline: nil, endpoint: nil, autocreate: nil) ⇒ Gcloud::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 "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

The name is optional, and will be generated if not given.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Wait 2 minutes for acknowledgement and push all to an endpoint:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

With ‘autocreate`:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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



351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'lib/gcloud/pubsub/project.rb', line 351

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

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

Retrieves subscription by name.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

subscription = pubsub.subscription "my-sub"
puts subscription.name

Skip the lookup against the service with ‘skip_lookup`:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

# No API call is made to retrieve the subscription information.
subscription = pubsub.subscription "my-sub", skip_lookup: true
puts subscription.name



404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/gcloud/pubsub/project.rb', line 404

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 Gcloud::NotFoundError
  nil
end

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

Retrieves a list of subscriptions for the given project.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

subscriptions = pubsub.subscriptions
subscriptions.each do |subscription|
  puts subscription.name
end

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

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

subscriptions = pubsub.subscriptions
subscriptions.all do |subscription|
  puts subscription.name
end



450
451
452
453
454
455
 
# File 'lib/gcloud/pubsub/project.rb', line 450

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) ⇒ Gcloud::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 "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "existing-topic"

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

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "non-existing-topic" #=> nil

With the ‘autocreate` option set to `true`.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "non-existing-topic", autocreate: true

Create a topic in a different project with the ‘project` flag.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "another-topic", project: "another-project"

Skip the lookup against the service with ‘skip_lookup`:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "another-topic", skip_lookup: true



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

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 Gcloud::NotFoundError
  return create_topic(topic_name) if autocreate
  nil
end

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

Retrieves a list of topics for the given project.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

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

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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



204
205
206
207
208
209
 
# File 'lib/gcloud/pubsub/project.rb', line 204

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