EventHubBufferedProducerClient class
The EventHubBufferedProducerClientis used to publish events to a specific Event Hub.
The EventHubBufferedProducerClient does not publish events immediately.
Instead, events are buffered so they can be efficiently batched and published
when the batch is full or the maxWaitTimeInMs has elapsed with no new events
enqueued.
Depending on the options specified when events are enqueued, they may be automatically assigned to a partition, grouped according to the specified partition key, or assigned a specifically requested partition.
This model is intended to shift the burden of batch management from callers, at the cost of non-deterministic timing, for when events will be published. There are additional trade-offs to consider, as well:
- If the application crashes, events in the buffer will not have been published. To prevent
data loss, callers are encouraged to track publishing progress using the
onSendEventsSuccessHandlerandonSendEventsErrorHandlerhandlers. - Events specifying a partition key may be assigned a different partition than those using the same key with other producers.
- In the unlikely event that a partition becomes temporarily unavailable, the
EventHubBufferedProducerClientmay take longer to recover than other producers.
In scenarios where it is important to have events published immediately with a deterministic
outcome, ensure that partition keys are assigned to a partition consistent with other
publishers, or where maximizing availability is a requirement, using the
EventHubProducerClient is recommended.
Constructors
| Event |
The |
| Event |
The |
| Event |
The |
Properties
| event |
The name of the Event Hub instance for which this client is created. |
| fully |
The fully qualified namespace of the Event Hub instance for which this client is created. This is likely to be similar to .servicebus.windows.net. |
| identifier | The name used to identify this EventHubBufferedProducerClient. If not specified or empty, a random unique one will be generated. |
Methods
| close(Buffered |
Closes the AMQP connection to the Event Hub instance, returning a promise that will be resolved when disconnection is completed. This will wait for enqueued events to be flushed to the service before closing
the connection.
To close without flushing, set the |
| enqueue |
Enqueues an event into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the event has been enqueued. When this call returns, the event has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed. |
| enqueue |
Enqueues events into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the events have been enqueued. When this call returns, the events have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed. |
| flush(Buffered |
Attempts to publish all events in the buffer immediately.
This may result in multiple batches being published,
the outcome of each of which will be individually reported by
the |
| get |
Provides the Event Hub runtime information. |
| get |
Provides the id for each partition associated with the Event Hub. |
| get |
Provides information about the state of the specified partition. |
Constructor Details
EventHubBufferedProducerClient(string, EventHubBufferedProducerClientOptions)
The EventHubBufferedProducerClient class is used to send events to an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
new EventHubBufferedProducerClient(connectionString: string, options: EventHubBufferedProducerClientOptions)Parameters
- connectionString
-
string
The connection string to use for connecting to the Event Hub instance. It is expected that the shared key properties and the Event Hub path are contained in this connection string. e.g. 'Endpoint=sb://my-servicebus-namespace.servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;EntityPath=my-event-hub-name'.
A set of options to apply when configuring the client.
retryOptions: Configures the retry policy for all the operations on the client. For example,{ "maxRetries": 4 }or{ "maxRetries": 4, "retryDelayInMs": 30000 }.webSocketOptions: Configures the channelling of the AMQP connection over Web Sockets.userAgent: A string to append to the built in user agent string that is passed to the service.
EventHubBufferedProducerClient(string, string, EventHubBufferedProducerClientOptions)
The EventHubBufferedProducerClient class is used to send events to an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
new EventHubBufferedProducerClient(connectionString: string, eventHubName: string, options: EventHubBufferedProducerClientOptions)Parameters
- connectionString
-
string
The connection string to use for connecting to the Event Hubs namespace. It is expected that the shared key properties are contained in this connection string, but not the Event Hub path, e.g. 'Endpoint=sb://my-servicebus-namespace.servicebus.windows.net/;SharedAccessKeyName=my-SA-name;SharedAccessKey=my-SA-key;'.
- eventHubName
-
string
The name of the specific Event Hub to connect the client to.
A set of options to apply when configuring the client.
retryOptions: Configures the retry policy for all the operations on the client. For example,{ "maxRetries": 4 }or{ "maxRetries": 4, "retryDelayInMs": 30000 }.webSocketOptions: Configures the channelling of the AMQP connection over Web Sockets.userAgent: A string to append to the built in user agent string that is passed to the service.
EventHubBufferedProducerClient(string, string, TokenCredential | NamedKeyCredential | SASCredential, EventHubBufferedProducerClientOptions)
The EventHubBufferedProducerClient class is used to send events to an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
new EventHubBufferedProducerClient(fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential | NamedKeyCredential | SASCredential, options: EventHubBufferedProducerClientOptions)Parameters
- fullyQualifiedNamespace
-
string
The full namespace which is likely to be similar to .servicebus.windows.net
- eventHubName
-
string
The name of the specific Event Hub to connect the client to.
- credential
An credential object used by the client to get the token to authenticate the connection
with the Azure Event Hubs service.
See @azure/identity for creating credentials that support AAD auth.
Use the AzureNamedKeyCredential from @azure/core-auth if you want to pass in a SharedAccessKeyName
and SharedAccessKey without using a connection string. These fields map to the name and key field respectively
in AzureNamedKeyCredential.
Use the AzureSASCredential from @azure/core-auth if you want to pass in a SharedAccessSignature
without using a connection string. This field maps to signature in AzureSASCredential.
A set of options to apply when configuring the client.
retryOptions: Configures the retry policy for all the operations on the client. For example,{ "maxRetries": 4 }or{ "maxRetries": 4, "retryDelayInMs": 30000 }.webSocketOptions: Configures the channelling of the AMQP connection over Web Sockets.userAgent: A string to append to the built in user agent string that is passed to the service.
Property Details
eventHubName
The name of the Event Hub instance for which this client is created.
string eventHubNameProperty Value
string
fullyQualifiedNamespace
The fully qualified namespace of the Event Hub instance for which this client is created. This is likely to be similar to .servicebus.windows.net.
string fullyQualifiedNamespaceProperty Value
string
identifier
The name used to identify this EventHubBufferedProducerClient. If not specified or empty, a random unique one will be generated.
identifier: stringProperty Value
string
Method Details
close(BufferedCloseOptions)
Closes the AMQP connection to the Event Hub instance, returning a promise that will be resolved when disconnection is completed.
This will wait for enqueued events to be flushed to the service before closing
the connection.
To close without flushing, set the flush option to false.
function close(options?: BufferedCloseOptions): Promise<void>Parameters
- options
- BufferedCloseOptions
The set of options to apply to the operation call.
Returns
Promise<void>
Promise
enqueueEvent(EventData | AmqpAnnotatedMessage, EnqueueEventOptions)
Enqueues an event into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the event has been enqueued.
When this call returns, the event has been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
function enqueueEvent(event: EventData | AmqpAnnotatedMessage, options?: EnqueueEventOptions): Promise<number>Parameters
- event
- options
- EnqueueEventOptions
A set of options that can be specified to influence the way in which the event is sent to the associated Event Hub.
abortSignal: A signal used to cancel the enqueueEvent operation.partitionId: The partition this set of events will be sent to. If set,partitionKeycan not be set.partitionKey: A value that is hashed to produce a partition assignment. If set,partitionIdcan not be set.
Returns
Promise<number>
The total number of events that are currently buffered and waiting to be published, across all partitions.
enqueueEvents(EventData[] | AmqpAnnotatedMessage[], EnqueueEventOptions)
Enqueues events into the buffer to be published to the Event Hub. If there is no capacity in the buffer when this method is invoked, it will wait for space to become available and ensure that the events have been enqueued.
When this call returns, the events have been accepted into the buffer, but it may not have been published yet. Publishing will take place at a nondeterministic point in the future as the buffer is processed.
function enqueueEvents(events: EventData[] | AmqpAnnotatedMessage[], options?: EnqueueEventOptions): Promise<number>Parameters
- events
An array of EventData or AmqpAnnotatedMessage.
- options
- EnqueueEventOptions
A set of options that can be specified to influence the way in which events are sent to the associated Event Hub.
abortSignal: A signal used to cancel the enqueueEvents operation.partitionId: The partition this set of events will be sent to. If set,partitionKeycan not be set.partitionKey: A value that is hashed to produce a partition assignment. If set,partitionIdcan not be set.
Returns
Promise<number>
The total number of events that are currently buffered and waiting to be published, across all partitions.
flush(BufferedFlushOptions)
Attempts to publish all events in the buffer immediately.
This may result in multiple batches being published,
the outcome of each of which will be individually reported by
the onSendEventsSuccessHandler and onSendEventsErrorHandler handlers.
function flush(options?: BufferedFlushOptions): Promise<void>Parameters
- options
- BufferedFlushOptions
The set of options to apply to the operation call.
Returns
Promise<void>
getEventHubProperties(GetEventHubPropertiesOptions)
Provides the Event Hub runtime information.
function getEventHubProperties(options?: GetEventHubPropertiesOptions): Promise<EventHubProperties>Parameters
- options
- GetEventHubPropertiesOptions
The set of options to apply to the operation call.
Returns
Promise<EventHubProperties>
A promise that resolves with information about the Event Hub instance.
getPartitionIds(GetPartitionIdsOptions)
Provides the id for each partition associated with the Event Hub.
function getPartitionIds(options?: GetPartitionIdsOptions): Promise<string[]>Parameters
- options
- GetPartitionIdsOptions
The set of options to apply to the operation call.
Returns
Promise<string[]>
A promise that resolves with an Array of strings representing the id for each partition associated with the Event Hub.
getPartitionProperties(string, GetPartitionPropertiesOptions)
Provides information about the state of the specified partition.
function getPartitionProperties(partitionId: string, options?: GetPartitionPropertiesOptions): Promise<PartitionProperties>Parameters
- partitionId
-
string
The id of the partition for which information is required.
- options
- GetPartitionPropertiesOptions
The set of options to apply to the operation call.
Returns
Promise<PartitionProperties>
A promise that resolves with information about the state of the partition .