PublishStream RPC Method
PublishStream method uses bidirectional streaming. It can send a stream of publish requests while receiving a stream of publish responses from the server. Use PublishStream to achieve a higher publish rate than with Publish.
The first PublishRequest of the stream identifies the topic to publish on. If a subsequent PublishRequest provides topic_name, it must match what was provided in the first PublishRequest. Otherwise, the RPC sends an error with an INVALID_ARGUMENT status.
The server returns a PublishResponse for each PublishRequest when publishing is complete for the batch. It isn’t necessary for a client to wait for a PublishResponse before sending a new PublishRequest. Multiple publish batches can be queued up. This behavior allows for a higher publish rate because a client can asynchronously publish more events while publish operations are still in flight on the server side.
The PublishResponse holds a PublishResult for each event published that indicates success or failure of the publish call. A successful status means that the event was published and is in the event bus. A failed status means that the event failed to publish.
For more information about the fields in PublishRequest and PublishResponse, see the Pub/Sub API proto file.
Publish method doesn’t enforce the presence of required custom event fields in the event payload. If you publish an event without including a required custom field, the publish call succeeds and the received event contains the field with a null value. For system fields, the
CreatedById fields are required in the event payload. If you publish an event without these system fields, the call fails.
For each batch of events in PublishRequest, the order of results corresponds to the order of events in the publish request. You can correlate each successful or failed result with the corresponding event in the publish request.
PublishStream doesn’t guarantee the order of batches of events (PublishRequests) published to match the order of batches received in the event bus. But the order of events published within each batch (PublishRequest) is preserved and matches the order of events received in the event bus.
id field in a PublishRequest,
ProducerEvent.id, identifies an event published. It can be either system-generated or user-provided. If you don’t specify an
id value in the PublishRequest and the publish call succeeds,
PublishResult.correlationKey is populated with a system-generated UUID. If the publish call fails,
PublishResult.correlationKey is empty. When publishing an event, you can specify a custom
id value in
ProducerEvent.id. If you set a custom
PublishResult.correlationKey field in the returned PublishResponse is the custom
id value for successful and failed publish calls. The custom
id value can be any string up to 36 characters. We recommend specifying a unique
id value, such as a UUID.
If the publishing fails due to a malformed event payload or a missing
schema_id field, fix your request and try publishing again. If the cause of the publishing failure is due to a temporary server issue, retry publishing. To be able to retry publishing events, set the ProducerEvent
id value in PublishRequest in the PublishStream call to a custom
id value. When the
PublishStream call fails, the returned PublishResult in PublishResponse contains the
correlationKey field set to the
id value that you provided. To identify the event published, match
ProducerEvent.id (the event ID). You can then republish the event. It’s advisable to limit the number of retries so that your publish calls don’t execute too many times in case the publishing keeps failing.
To hold onto the stream, a client must send a valid publish request with one or more events every 70 seconds. Otherwise, the server closes the stream and notifies the client. When the client is notified of the stream closure, it must make a new
PublishStream call to resume publishing.