Cloud Pub/Sub API - Class Google::Cloud::PubSub::Publisher (v3.0.2)

Reference documentation and code samples for the Cloud Pub/Sub API class Google::Cloud::PubSub::Publisher.

Publisher

A Publisher is the primary interface for data plane operations on a topic, including publishing messages, batching messages for higher throughput, and managing ordering keys.

Inherits

  • Object

Example

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic-only"

publisher.publish "task completed"

Methods

#async_publisher

def async_publisher() -> AsyncPublisher

AsyncPublisher object used to publish multiple messages in batches.

Returns
Example 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
publisher.publish_async "task completed" do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

publisher.async_publisher.stop!

#enable_message_ordering!

def enable_message_ordering!()

Enables message ordering for messages with ordering keys on the #async_publisher. When enabled, messages published with the same ordering_key will be delivered in the order they were published.

See #message_ordering?. See #publish_async, Subscriber#listen, and Message#ordering_key.

#message_ordering?

def message_ordering?() -> Boolean

Whether message ordering for messages with ordering keys has been enabled on the #async_publisher. When enabled, messages published with the same ordering_key will be delivered in the order they were published. When disabled, messages may be delivered in any order.

See #enable_message_ordering!. See #publish_async, Subscriber#listen, and Message#ordering_key.

Returns
  • (Boolean)

#name

def name() -> String

The name of the publisher.

Returns
  • (String) — A fully-qualified topic name in the form projects/{project_id}/topics/{topic_id}.

#publish

def publish(data = nil, attributes = nil, ordering_key: nil, compress: nil, compression_bytes_threshold: nil, **extra_attrs, &block) { |batch| ... } -> Message, Array<Message>

Publishes one or more messages to the publisher.

The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute.

Parameters
  • data (String, File) — The message payload. This will be converted to bytes encoded as ASCII-8BIT.
  • attributes (Hash) — Optional attributes for the message.
  • ordering_key (String) (defaults to: nil) — Identifies related messages for which publish order should be respected.
Yields
  • (batch) — a block for publishing multiple messages in one request
Yield Parameter
Returns
  • (Message, Array<Message>) — Returns the published message when called without a block, or an array of messages when called with a block.
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

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

A message can be published using a File object:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
file = File.open "message.txt", mode: "rb"
msg = publisher.publish file

Additionally, a message can be published with attributes:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
msg = publisher.publish "task completed",
                    foo: :bar,
                    this: :that

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

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"

msgs = publisher.publish do |p|
  p.publish "task 1 completed", foo: :bar
  p.publish "task 2 completed", foo: :baz
  p.publish "task 3 completed", foo: :bif
end

Ordered messages are supported using ordering_key:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-ordered-topic"

# Ensure that message ordering is enabled.
publisher.enable_message_ordering!

# Publish an ordered message with an ordering key.
publisher.publish "task completed",
              ordering_key: "task-key"

#publish_async

def publish_async(data = nil, attributes = nil, ordering_key: nil, **extra_attrs, &callback) { |result| ... }

Publishes a message asynchronously to the topic using #async_publisher.

The message payload must not be empty; it must contain either a non-empty data field, or at least one attribute.

Google Cloud Pub/Sub ordering keys provide the ability to ensure related messages are sent to subscribers in the order in which they were published. Messages can be tagged with an ordering key, a string that identifies related messages for which publish order should be respected. The service guarantees that, for a given ordering key and publisher, messages are sent to subscribers in the order in which they were published. Ordering does not require sacrificing high throughput or scalability, as the service automatically distributes messages for different ordering keys across subscribers.

To use ordering keys, specify ordering_key. Before specifying ordering_key on a message a call to #enable_message_ordering! must be made or an error will be raised.

Publisher flow control limits the number of outstanding messages that are allowed to wait to be published.

Parameters
  • data (String, File) — The message payload. This will be converted to bytes encoded as ASCII-8BIT.
  • attributes (Hash) — Optional attributes for the message.
  • ordering_key (String) (defaults to: nil) — Identifies related messages for which publish order should be respected.
Yields
  • (result) — the callback for when the message has been published
Yield Parameter
  • result (PublishResult) — the result of the asynchronous publish
Raises
Examples 
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
publisher.publish_async "task completed" do |result|
  if result.succeeded?
    log_publish_success result.data
  else
    log_publish_failure result.data, result.error
  end
end

# Shut down the publisher when ready to stop publishing messages.
publisher.async_publisher.stop!

A message can be published using a File object:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
file = File.open "message.txt", mode: "rb"
publisher.publish_async file

# Shut down the publisher when ready to stop publishing messages.
publisher.async_publisher.stop!

Additionally, a message can be published with attributes:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic"
publisher.publish_async "task completed",
                    foo: :bar, this: :that

# Shut down the publisher when ready to stop publishing messages.
publisher.async_publisher.stop!

Ordered messages are supported using ordering_key:

require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-ordered-topic"

# Ensure that message ordering is enabled.
publisher.enable_message_ordering!

# Publish an ordered message with an ordering key.
publisher.publish_async "task completed",
                    ordering_key: "task-key"

# Shut down the publisher when ready to stop publishing messages.
publisher.async_publisher.stop!

#resume_publish

def resume_publish(ordering_key) -> boolean

Resume publishing ordered messages for the provided ordering key.

Parameter
  • ordering_key (String) — Identifies related messages for which publish order should be respected.
Returns
  • (boolean) — true when resumed, false otherwise.