Class: Gcloud::Pubsub::Topic

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/pubsub/topic.rb,
lib/gcloud/pubsub/topic/list.rb,
lib/gcloud/pubsub/topic/batch.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 Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Topic

Returns a new instance of Topic.



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

def initialize
  @service = nil
  @grpc = Google::Pubsub::V1::Topic.new
  @name = nil
  @exists = nil
end

Instance Attribute Details

#grpc ⇒ Object 



44
45
46
 
# File 'lib/gcloud/pubsub/topic.rb', line 44

def grpc
  @grpc
end

#service ⇒ Object 



40
41
42
 
# File 'lib/gcloud/pubsub/topic.rb', line 40

def service
  @service
end

Class Method Details

.from_grpc(grpc, service) ⇒ Object 



471
472
473
474
475
476
 
# File 'lib/gcloud/pubsub/topic.rb', line 471

def self.from_grpc grpc, service
  new.tap do |f|
    f.grpc = grpc
    f.service = service
  end
end

.new_lazy(name, service, options = {}) ⇒ Object 



57
58
59
60
61
62
63
64
65
 
# File 'lib/gcloud/pubsub/topic.rb', line 57

def self.new_lazy name, service, options = {}
  new.tap do |t|
    t.grpc = nil
    t.service = service
    t.instance_eval do
      @name = service.topic_path(name, options)
    end
  end
end

Instance Method Details

#delete ⇒ Boolean

Permanently deletes the topic.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

Returns:

  • (Boolean) —

    Returns ‘true` if the topic was deleted.



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

def delete
  ensure_service!
  service.delete_topic name
  return true
rescue GRPC::BadStatus => e
  raise Error.from_error(e)
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

Returns:

  • (Boolean) 


443
444
445
446
447
448
449
450
 
# File 'lib/gcloud/pubsub/topic.rb', line 443

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

#lazy? ⇒ Boolean

Determines whether the topic object was created with an HTTP call.

Examples:

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
topic.lazy? #=> false

Returns:

  • (Boolean) 


465
466
467
 
# File 'lib/gcloud/pubsub/topic.rb', line 465

def lazy?
  @grpc.nil?
end

#name ⇒ Object

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
  @grpc ? @grpc.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

Parameters:

  • force (Boolean) (defaults to: nil) —

    Force the latest policy to be retrieved from the Pub/Sub service when ‘true`. Otherwise the policy will be memoized to reduce the number of API calls made to the Pub/Sub service. The default is `false`.

Returns:

  • (Hash) —

    Returns a hash that conforms to the following structure:

    {

    "etag"=>"CAE=",
"bindings" => [{
  "role" => "roles/viewer",
  "members" => ["serviceAccount:your-service-account"]
}]

    }



340
341
342
343
344
345
346
347
348
349
 
# File 'lib/gcloud/pubsub/topic.rb', line 340

def policy force: nil
  @policy = nil if force
  @policy ||= begin
    ensure_service!
    grpc = service.get_topic_policy name
    JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
  rescue GRPC::BadStatus => e
    raise Error.from_error(e)
  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

Parameters:

  • new_policy (String) —

    A hash that conforms to the following structure:

    {
  "bindings" => [{
    "role" => "roles/viewer",
    "members" => ["serviceAccount:your-service-account"]
  }]
}



379
380
381
382
383
384
385
 
# File 'lib/gcloud/pubsub/topic.rb', line 379

def policy= new_policy
  ensure_service!
  grpc = service.set_topic_policy name, new_policy
  @policy = JSON.parse(Google::Iam::V1::Policy.encode_json(grpc))
rescue GRPC::BadStatus => e
  raise Error.from_error(e)
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

Parameters:

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

    The message data.

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

    Optional attributes for the message.

Yields:

  • (batch) —

    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.



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

def publish data = nil, attributes = {}
  ensure_service!
  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"

Parameters:

  • 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) (defaults to: nil) —

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

  • endpoint (String) (defaults to: nil) —

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

Returns:



143
144
145
146
147
148
149
150
 
# File 'lib/gcloud/pubsub/topic.rb', line 143

def subscribe subscription_name, deadline: nil, endpoint: nil
  ensure_service!
  options = { deadline: deadline, endpoint: endpoint }
  grpc = service.create_subscription name, subscription_name, options
  Subscription.from_grpc grpc, service
rescue GRPC::BadStatus => e
  raise Error.from_error(e)
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

Parameters:

  • subscription_name (String) —

    Name of a subscription.

  • 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:



186
187
188
189
190
191
192
193
194
 
# File 'lib/gcloud/pubsub/topic.rb', line 186

def subscription subscription_name, skip_lookup: nil
  ensure_service!
  return Subscription.new_lazy subscription_name, service if skip_lookup
  grpc = service.get_subscription subscription_name
  Subscription.from_grpc grpc, service
rescue GRPC::BadStatus => e
  return nil if e.code == 5
  raise Error.from_error(e)
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

Parameters:

  • token (String) (defaults to: nil) —

    The ‘token` value returned by the last call to `subscriptions`; 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 subscriptions to return.

Returns:



239
240
241
242
243
244
245
246
 
# File 'lib/gcloud/pubsub/topic.rb', line 239

def subscriptions token: nil, max: nil
  ensure_service!
  options = { token: token, max: max }
  grpc = service.list_topics_subscriptions name, options
  Subscription::List.from_grpc grpc, service
rescue GRPC::BadStatus => e
  raise Error.from_error(e)
end

#test_permissions(*permissions) ⇒ Array<Strings>

Tests the specified permissions against the [Cloud IAM](cloud.google.com/iam/) access control policy.

Examples:

require "gcloud"

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

Parameters:

  • permissions (String, Array<String>) —

    The set of permissions to check access for. Permissions with wildcards (such as ‘*` or `storage.*`) are not allowed.

    The permissions that can be checked on a topic are:

    • pubsub.topics.publish

    • pubsub.topics.attachSubscription

    • pubsub.topics.get

    • pubsub.topics.delete

    • pubsub.topics.update

    • pubsub.topics.getIamPolicy

    • pubsub.topics.setIamPolicy

Returns:

  • (Array<Strings>) —

    The permissions that have access.

See Also:



421
422
423
424
425
426
427
428
429
 
# File 'lib/gcloud/pubsub/topic.rb', line 421

def test_permissions *permissions
  permissions = Array(permissions).flatten
  permissions = Array(permissions).flatten
  ensure_service!
  grpc = service.test_topic_permissions name, permissions
  grpc.permissions
rescue GRPC::BadStatus => e
  raise Error.from_error(e)
end