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.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

See Gcloud#pubsub

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(project, credentials) ⇒ Project

Creates a new Connection instance.



49
50
51
52
53
 
# File 'lib/gcloud/pubsub/project.rb', line 49

def initialize project, credentials #:nodoc:
  project = project.to_s # Always cast to a string
  fail ArgumentError, "project is missing" if project.empty?
  @connection = Connection.new project, credentials
end

Instance Attribute Details

#connection ⇒ Object

The Connection object.



45
46
47
 
# File 'lib/gcloud/pubsub/project.rb', line 45

def connection
  @connection
end

Class Method Details

.default_project ⇒ Object

Default project.



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

def self.default_project #:nodoc:
  ENV["PUBSUB_PROJECT"] ||
    ENV["GCLOUD_PROJECT"] ||
    ENV["GOOGLE_CLOUD_PROJECT"]
end

Instance Method Details

#create_topic(topic_name) ⇒ Object Also known as: new_topic

Creates a new topic.

Parameters

topic_name

Name of a topic. (String)

Returns

Gcloud::Pubsub::Topic

Examples

require "gcloud"

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



197
198
199
200
201
202
203
204
205
 
# File 'lib/gcloud/pubsub/project.rb', line 197

def create_topic topic_name
  ensure_connection!
  resp = connection.create_topic topic_name
  if resp.success?
    Topic.from_gapi resp.data, connection
  else
    fail ApiError.from_response(resp)
  end
end

#get_subscription(subscription_name) ⇒ Object Also known as: find_subscription

Retrieves subscription by name. The difference between this method and Project#subscription is that this method makes an API call to Pub/Sub to verify the subscription exists.

Parameters

subscription_name

Name of a subscription. (String)

Returns

Gcloud::Pubsub::Subscription or nil if the subscription does not exist

Example

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

subscription = pubsub.get_subscription "my-topic-subscription"
puts subscription.name



327
328
329
330
331
332
333
334
335
 
# File 'lib/gcloud/pubsub/project.rb', line 327

def get_subscription subscription_name
  ensure_connection!
  resp = connection.get_subscription subscription_name
  if resp.success?
    Subscription.from_gapi resp.data, connection
  else
    nil
  end
end

#get_topic(topic_name) ⇒ Object Also known as: find_topic

Retrieves topic by name. The difference between this method and Project#topic is that this method makes an API call to Pub/Sub to verify the topic exists.

Parameters

topic_name

Name of a topic. (String)

Returns

Gcloud::Pubsub::Topic or nil if topic does not exist

Example

require "gcloud"

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



101
102
103
104
105
106
107
108
109
110
 
# File 'lib/gcloud/pubsub/project.rb', line 101

def get_topic topic_name
  ensure_connection!
  resp = connection.get_topic topic_name
  if resp.success?
    Topic.from_gapi resp.data, connection
  else
    return nil if resp.data["error"]["code"] == 404
    fail ApiError.from_response(resp)
  end
end

#project ⇒ Object

The Pub/Sub project connected to.

Example

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
  connection.project
end

#subscription(subscription_name) ⇒ Object

Retrieves subscription by name. The difference between this method and Project#get_subscription is that this method does not make an API call to Pub/Sub to verify the subscription exists.

Parameters

subscription_name

Name of a subscription. (String)

Returns

Gcloud::Pubsub::Subscription

Example

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

subscription = pubsub.get_subscription "my-topic-subscription"
puts subscription.name



296
297
298
299
300
 
# File 'lib/gcloud/pubsub/project.rb', line 296

def subscription subscription_name
  ensure_connection!

  Subscription.new_lazy subscription_name, connection
end

#subscriptions(options = {}) ⇒ Object Also known as: find_subscriptions, list_subscriptions

Retrieves a list of subscriptions for the given project.

Parameters

options

An optional Hash for controlling additional behavior. (Hash)

options[:prefix]

Filter results to subscriptions whose names begin with this prefix. (String)

options[:token]

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

options[:max]

Maximum number of subscriptions to return. (Integer)

Returns

Array of Gcloud::Pubsub::Subscription (Gcloud::Pubsub::Subscription::List)

Examples

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

If you have a significant number of subscriptions, you may need to paginate through them: (See Subscription::List#token)

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

all_subs = []
tmp_subs = pubsub.subscriptions
while tmp_subs.any? do
  tmp_subs.each do |subscription|
    all_subs << subscription
  end
  # break loop if no more subscriptions available
  break if tmp_subs.token.nil?
  # get the next group of subscriptions
  tmp_subs = pubsub.subscriptions token: tmp_subs.token
end



391
392
393
394
395
396
397
398
399
 
# File 'lib/gcloud/pubsub/project.rb', line 391

def subscriptions options = {}
  ensure_connection!
  resp = connection.list_subscriptions options
  if resp.success?
    Subscription::List.from_resp resp, connection
  else
    fail ApiError.from_response(resp)
  end
end

#topic(topic_name, options = {}) ⇒ Object

Retrieves topic by name. The difference between this method and Project#get_topic is that this method does not make an API call to Pub/Sub to verify the topic exists.

Parameters

topic_name

Name of a topic. (String)

options

An optional Hash for controlling additional behavior. (Hash)

options[:autocreate]

Flag to control whether the topic should be created when needed. The default value is true. (Boolean)

options[:project]

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

Returns

Gcloud::Pubsub::Topic

Examples

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "existing-topic"
msg = topic.publish "This is the first API call to Pub/Sub."

By default the topic will be created in Pub/Sub when needed.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "non-existing-topic"
msg = topic.publish "This will create the topic in Pub/Sub."

Setting the autocomplete flag to false will not create the topic.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "non-existing-topic"
msg = topic.publish "This raises." #=> Gcloud::Pubsub::NotFoundError

A topic in a different project can be created using the project flag.

require "gcloud"

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



171
172
173
174
175
 
# File 'lib/gcloud/pubsub/project.rb', line 171

def topic topic_name, options = {}
  ensure_connection!

  Topic.new_lazy topic_name, connection, options
end

#topics(options = {}) ⇒ Object Also known as: find_topics, list_topics

Retrieves a list of topics for the given project.

Parameters

options

An optional Hash for controlling additional behavior. (Hash) (String)

options[:token]

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. (String)

options[:max]

Maximum number of topics to return. (Integer)

Returns

Array of Gcloud::Pubsub::Topic (Gcloud::Pubsub::Topic::List)

Examples

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

If you have a significant number of topics, you may need to paginate through them: (See Topic::List#token)

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

all_topics = []
tmp_topics = pubsub.topics
while tmp_topics.any? do
  tmp_topics.each do |topic|
    all_topics << topic
  end
  # break loop if no more topics available
  break if tmp_topics.token.nil?
  # get the next group of topics
  tmp_topics = pubsub.topics token: tmp_topics.token
end



259
260
261
262
263
264
265
266
267
 
# File 'lib/gcloud/pubsub/project.rb', line 259

def topics options = {}
  ensure_connection!
  resp = connection.list_topics options
  if resp.success?
    Topic::List.from_resp resp, connection
  else
    fail ApiError.from_response(resp)
  end
end