Class: Gcloud::Pubsub::Topic

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/pubsub/topic.rb,
lib/gcloud/pubsub/topic/list.rb

Overview

Topic

A named resource to which messages are published.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Defined Under Namespace

Classes: Batch, List

Instance Method Summary collapse

Instance Method Details

#deleteBoolean

Permanently deletes the topic.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
topic.delete

88
89
90
91
92
93
94
95
96
# File 'lib/gcloud/pubsub/topic.rb', line 88

def delete
  ensure_connection!
  resp = connection.delete_topic name
  if resp.success?
    true
  else
    fail ApiError.from_response(resp)
  end
end

#exists?Boolean

Determines whether the topic exists in the Pub/Sub service.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
topic.exists? #=> true

446
447
448
449
450
451
452
453
# File 'lib/gcloud/pubsub/topic.rb', line 446

def exists?
  # Always true if we have a gapi object
  return true unless @gapi.nil?
  # If we have a value, return it
  return @exists unless @exists.nil?
  ensure_gapi!
  @exists = !@gapi.nil?
end

#nameObject

The name of the topic in the form of "/projects/project-identifier/topics/topic-name".


70
71
72
# File 'lib/gcloud/pubsub/topic.rb', line 70

def name
  @gapi ? @gapi["name"] : @name
end

#policy(force: nil) ⇒ Hash

Gets the access control policy.

Examples:

Policy values are memoized to reduce the number of API calls:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
puts topic.policy["bindings"]
puts topic.policy["rules"]

Use force to retrieve the latest policy from the service:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
policy = topic.policy force: true

349
350
351
352
353
354
355
356
357
358
# File 'lib/gcloud/pubsub/topic.rb', line 349

def policy force: nil
  @policy = nil if force
  @policy ||= begin
    ensure_connection!
    resp = connection.get_topic_policy name
    policy = resp.data
    policy = policy.to_hash if policy.respond_to? :to_hash
    policy
  end
end

#policy=(new_policy) ⇒ Object

Sets the access control policy.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

viewer_policy = {
  "bindings" => [{
    "role" => "roles/viewer",
    "members" => ["serviceAccount:your-service-account"]
  }]
}
topic = pubsub.topic "my-topic"
topic.policy = viewer_policy

388
389
390
391
392
393
394
395
396
397
# File 'lib/gcloud/pubsub/topic.rb', line 388

def policy= new_policy
  ensure_connection!
  resp = connection.set_topic_policy name, new_policy
  if resp.success?
    @policy = resp.data["policy"]
    @policy = @policy.to_hash if @policy.respond_to? :to_hash
  else
    fail ApiError.from_response(resp)
  end
end

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

Publishes one or more messages to the topic.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Additionally, a message can be published with attributes:


require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
msg = topic.publish "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

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

Yields:

  • (batch)

304
305
306
307
308
309
310
# File 'lib/gcloud/pubsub/topic.rb', line 304

def publish data = nil, attributes = {}
  ensure_connection!
  batch = Batch.new data, attributes
  yield batch if block_given?
  return nil if batch.messages.count.zero?
  publish_batch_messages batch
end

#subscribe(subscription_name, deadline: nil, endpoint: nil) ⇒ Gcloud::Pubsub::Subscription Also known as: create_subscription, new_subscription

Creates a new Subscription object on the current Topic.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
sub = topic.subscribe "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

topic = pubsub.topic "my-topic"
sub = topic.subscribe "my-topic-sub"
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

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

147
148
149
150
151
152
153
154
155
156
# File 'lib/gcloud/pubsub/topic.rb', line 147

def subscribe subscription_name, deadline: nil, endpoint: nil
  ensure_connection!
  options = { deadline: deadline, endpoint: endpoint }
  resp = connection.create_subscription name, subscription_name, options
  if resp.success?
    Subscription.from_gapi resp.data, connection
  else
    fail ApiError.from_response(resp)
  end
end

#subscription(subscription_name, 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

topic = pubsub.topic "my-topic"
subscription = topic.subscription "my-topic-subscription"
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

192
193
194
195
196
197
198
199
200
201
# File 'lib/gcloud/pubsub/topic.rb', line 192

def subscription subscription_name, skip_lookup: nil
  ensure_connection!
  if skip_lookup
    return Subscription.new_lazy(subscription_name, connection)
  end
  resp = connection.get_subscription subscription_name
  return Subscription.from_gapi(resp.data, connection) if resp.success?
  return nil if resp.status == 404
  fail ApiError.from_response(resp)
end

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

Retrieves a list of subscription names for the given project.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
subscription = topic.subscriptions
subscriptions.each do |subscription|
  puts subscription.name
end

With pagination: (See Subscription::List#token)


require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
all_subs = []
tmp_subs = topic.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 = topic.subscriptions token: tmp_subs.token
end

247
248
249
250
251
252
253
254
255
256
# File 'lib/gcloud/pubsub/topic.rb', line 247

def subscriptions token: nil, max: nil
  ensure_connection!
  options = { token: token, max: max }
  resp = connection.list_topics_subscriptions name, options
  if resp.success?
    Subscription::List.from_response resp, connection
  else
    fail ApiError.from_response(resp)
  end
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the Cloud IAM access control policy.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub
topic = pubsub.topic "my-topic"
perms = topic.test_permissions "projects.topic.list",
                               "projects.topic.publish"
perms.include? "projects.topic.list" #=> true
perms.include? "projects.topic.publish" #=> false

See Also:


423
424
425
426
427
428
429
430
431
432
# File 'lib/gcloud/pubsub/topic.rb', line 423

def test_permissions *permissions
  permissions = Array(permissions).flatten
  ensure_connection!
  resp = connection.test_topic_permissions name, permissions
  if resp.success?
    Array(resp.data["permissions"])
  else
    fail ApiError.from_response(resp)
  end
end