PublishStream RPC Method
The 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.
The 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 CreatedDate and 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.
The event 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 id, the 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 PublishResult.correlationKey with 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.
If an error occurs, the long-lived connection is stopped. Retry the PublishStream RPC method call to create a new long-lived connection. For more information, see Handle Errors.
See Also