Gcloud::Pubsub::Topic

Topic ↑

A named resource to which messages are published.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
topic.publish "task completed"
Parent: Object
Methods: create_subscription delete exists? find_subscription find_subscriptions get_subscription list_subscriptions name new_subscription policy policy= publish subscribe subscription subscriptions

Methods

Public Instance Methods

create_subscription(subscription_name, options = {}) ↑

Alias for: subscribe

delete() ↑

Permanently deletes the topic.

Returns ↑

true if the topic was deleted.

Example ↑

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

exists?() ↑

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

Example ↑

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

find_subscription(subscription_name) ↑

Alias for: get_subscription

find_subscriptions(options = {}) ↑

Alias for: subscriptions

get_subscription(subscription_name) ↑

Retrieves a subscription by name. The difference between this method and #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 subscription does not exist

Example ↑

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

topic = pubsub.topic "my-topic"
subscription = topic.get_subscription "my-topic-subscription"
puts subscription.name
Also aliased as: find_subscription

list_subscriptions(options = {}) ↑

Alias for: subscriptions

name() ↑

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

new_subscription(subscription_name, options = {}) ↑

Alias for: subscribe

policy(options = {}) ↑

Gets the access control policy.

Parameters ↑

options

An optional Hash for controlling additional behavior. (Hash)

options[:force]

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

Returns ↑

A hash that conforms to the following structure:

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

Examples ↑

By default, the policy values are memoized to reduce the number of API calls to the Pub/Sub service.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

To retrieve the latest policy from the Pub/Sub service, use the force flag.

require "gcloud"

gcloud = Gcloud.new
pubsub = gcloud.pubsub

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

policy=(new_policy) ↑

Sets the access control policy.

Parameters ↑

new_policy

A hash that conforms to the following structure:

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

Example ↑

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

publish(data = nil, attributes = {}) ↑

Publishes one or more messages to the topic.

Parameters ↑

data

The message data. (String)

attributes

Optional attributes for the message. (Hash)

Returns ↑

Message object when called without a block, Array of Message objects when called with a block

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 published at the same time by passing 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

subscribe(subscription_name, options = {}) ↑

Creates a new Subscription object on the current Topic.

Parameters ↑

subscription_name

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

options

An optional Hash for controlling additional behavior. (Hash)

options[:deadline]

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

options[:endpoint]

A URL locating the endpoint to which messages should be pushed. e.g. “example.com/push” (String)

Returns ↑

Gcloud::Pubsub::Subscription

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"

The subscription can be created that waits two minutes for acknowledgement and pushed all messages 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"
Also aliased as: create_subscription, new_subscription

subscription(subscription_name) ↑

Retrieves subscription by name. The difference between this method and #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

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

subscriptions(options = {}) ↑

Retrieves a list of subscription names for the given project.

Parameters ↑

options

An optional Hash for controlling additional behavior. (Hash)

options[:token]

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

options[:max]

Maximum number of subscriptions to return. (Integer)

Returns ↑

Array of Subscription objects (Subscription::List)

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

If you have a significant number of subscriptions, you may need to paginate through them: (See Gcloud::Pubsub::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
Also aliased as: find_subscriptions, list_subscriptions