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.
- ( AsyncPublisher
) — Returns publisher object if calls to #publish_async
have been made, returns
nilotherwise.
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 .
- (Boolean)
#name
def
name
()
-
>
String
The name of the publisher.
- (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.
- 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.
- (batch) — a block for publishing multiple messages in one request
- batch( BatchPublisher ) — the topic batch publisher object
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.
- 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.
- (result) — the callback for when the message has been published
- result( PublishResult ) — the result of the asynchronous publish
- ( Google::Cloud::PubSub::AsyncPublisherStopped ) — when the publisher is stopped. (See AsyncPublisher#stop and AsyncPublisher#stopped? .)
- ( Google::Cloud::PubSub::OrderedMessagesDisabled
) — when
publishing a message with an
ordering_keybut ordered messages are not enabled. (See #message_ordering? and #enable_message_ordering! .) - ( Google::Cloud::PubSub::OrderingKeyError
) — when publishing a
message with an
ordering_keythat has already failed when publishing. Use #resume_publish to allow thisordering_keyto be published again. - ( Google::Cloud::PubSub::FlowControlLimitError
) — when publish flow
control limits are exceeded, and the
asyncparameter keyflow_control.limit_exceeded_behavioris set to:erroror:block. Ifflow_control.limit_exceeded_behavioris set to:block, this error will be raised only when a limit would be exceeded by a single message.
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.
- ordering_key(String) — Identifies related messages for which publish order should be respected.
- (boolean) —
truewhen resumed,falseotherwise.
