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

3.3.0 (latest) 3.2.1 3.1.1 3.0.3 2.23.0 2.22.0 2.21.0 2.20.0 2.19.0 2.18.1 2.17.0 2.16.0 2.15.5 2.14.0 2.12.1 2.11.0 2.10.0 2.9.2 Reference documentation and code samples for the Cloud Pub/Sub API class Google::Cloud::PubSub::Publisher.

## Publisher

A [Publisher](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher "Google::Cloud::PubSub::Publisher (class)") 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

```ruby
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**

- ([AsyncPublisher](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-AsyncPublisher)) --- Returns publisher object if calls to [#publish_async](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_publish_async_instance_ "Google::Cloud::PubSub::Publisher#publish_async (method)") have been made, returns `nil` otherwise.
**Example**

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_async_publisher_instance_ "Google::Cloud::PubSub::Publisher#async_publisher (method)"). When enabled, messages published with the same
`ordering_key` will be delivered in the order they were published.


<br />

See [#message_ordering?](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_message_ordering__instance_ "Google::Cloud::PubSub::Publisher#message_ordering? (method)"). See [#publish_async](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_publish_async_instance_ "Google::Cloud::PubSub::Publisher#publish_async (method)"),
[Subscriber#listen](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Subscriber#Google__Cloud__PubSub__Subscriber_listen_instance_ "Google::Cloud::PubSub::Subscriber#listen (method)"), and [Message#ordering_key](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Message#Google__Cloud__PubSub__Message_ordering_key_instance_ "Google::Cloud::PubSub::Message#ordering_key (method)").

### #message_ordering?

    def message_ordering?() -> Boolean

Whether message ordering for messages with ordering keys has been
enabled on the [#async_publisher](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_async_publisher_instance_ "Google::Cloud::PubSub::Publisher#async_publisher (method)"). 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.


<br />

See [#enable_message_ordering!](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_enable_message_ordering__instance_ "Google::Cloud::PubSub::Publisher#enable_message_ordering! (method)"). See [#publish_async](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_publish_async_instance_ "Google::Cloud::PubSub::Publisher#publish_async (method)"),
[Subscriber#listen](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Subscriber#Google__Cloud__PubSub__Subscriber_listen_instance_ "Google::Cloud::PubSub::Subscriber#listen (method)"), and [Message#ordering_key](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Message#Google__Cloud__PubSub__Message_ordering_key_instance_ "Google::Cloud::PubSub::Message#ordering_key (method)").
**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.


<br />

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**

- **batch** ([BatchPublisher](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-BatchPublisher)) --- the topic batch publisher object
**Returns**

- ([Message](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Message), Array\<[Message](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Message)\>) --- Returns the published message when called without a block, or an array of messages when called with a block.
**Examples**

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_async_publisher_instance_ "Google::Cloud::PubSub::Publisher#async_publisher (method)").


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.

<br />

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](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-PublishResult)) --- the result of the asynchronous publish
**Raises**

- ([Google::Cloud::PubSub::AsyncPublisherStopped](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-AsyncPublisherStopped)) --- when the publisher is stopped. (See [AsyncPublisher#stop](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-AsyncPublisher#Google__Cloud__PubSub__AsyncPublisher_stop_instance_ "Google::Cloud::PubSub::AsyncPublisher#stop (method)") and [AsyncPublisher#stopped?](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-AsyncPublisher#Google__Cloud__PubSub__AsyncPublisher_stopped__instance_ "Google::Cloud::PubSub::AsyncPublisher#stopped? (method)").)
- ([Google::Cloud::PubSub::OrderedMessagesDisabled](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-OrderedMessagesDisabled)) --- when publishing a message with an `ordering_key` but ordered messages are not enabled. (See [#message_ordering?](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_message_ordering__instance_ "Google::Cloud::PubSub::Publisher#message_ordering? (method)") and [#enable_message_ordering!](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_enable_message_ordering__instance_ "Google::Cloud::PubSub::Publisher#enable_message_ordering! (method)").)
- ([Google::Cloud::PubSub::OrderingKeyError](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-OrderingKeyError)) --- when publishing a message with an `ordering_key` that has already failed when publishing. Use [#resume_publish](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher#Google__Cloud__PubSub__Publisher_resume_publish_instance_ "Google::Cloud::PubSub::Publisher#resume_publish (method)") to allow this `ordering_key` to be published again.
- ([Google::Cloud::PubSub::FlowControlLimitError](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-FlowControlLimitError)) --- when publish flow control limits are exceeded, and the `async` parameter key `flow_control.limit_exceeded_behavior` is set to `:error` or `:block`. If `flow_control.limit_exceeded_behavior` is set to `:block`, this error will be raised only when a limit would be exceeded by a single message.
**Examples**

```ruby
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:

```ruby
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:

```ruby
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:

```ruby
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!
```

### #reference?

    def reference?() -> Boolean

Determines whether the publisher object was created with a resource
representation from the Pub/Sub service.
**Returns**

- (Boolean) --- `true` when the publisher was created with a resource representation, `false` otherwise.

### #reload!

    def reload!() -> Google::Cloud::PubSub::Publisher

Reloads the publisher with current data from the Pub/Sub service.
**Returns**

- ([Google::Cloud::PubSub::Publisher](https://docs.cloud.google.com/ruby/docs/reference/google-cloud-pubsub/latest/Google-Cloud-PubSub-Publisher)) --- Returns the reloaded publisher
**Example**

```ruby
require "google/cloud/pubsub"

pubsub = Google::Cloud::PubSub.new

publisher = pubsub.publisher "my-topic", skip_lookup: true

publisher.reload!
```

### #resource?

    def resource?() -> Boolean

Determines whether the publisher object was created with a resource
representation from the Pub/Sub service.
**Returns**

- (Boolean) --- `true` when the publisher was created with a resource representation, `false` otherwise.

### #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.