Share via

@azure/event-hubs package

  • Reference

Classes

EventHubBufferedProducerClient

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 onSendEventsSuccessHandler and onSendEventsErrorHandler handlers.
  • 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 EventHubBufferedProducerClient may 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.
EventHubConsumerClient

The EventHubConsumerClient class is used to consume events from an Event Hub.

There are multiple ways to create an EventHubConsumerClient

  • Use the connection string from the SAS policy created for your Event Hub instance.
  • Use the connection string from the SAS policy created for your Event Hub namespace, and the name of the Event Hub instance
  • Use the full namespace like <yournamespace>.servicebus.windows.net, and a credentials object.

Optionally, you can also pass:

  • An options bag to configure the retry policy or proxy settings.
  • A checkpoint store that is used by the client to read checkpoints to determine the position from where it should resume receiving events when your application gets restarted. The checkpoint store is also used by the client to load balance multiple instances of your application.
EventHubProducerClient

The EventHubProducerClient class is used to send events to an Event Hub.

There are multiple ways to create an EventHubProducerClient

  • Use the connection string from the SAS policy created for your Event Hub instance.
  • Use the connection string from the SAS policy created for your Event Hub namespace, and the name of the Event Hub instance
  • Use the full namespace like <yournamespace>.servicebus.windows.net, and a credentials object.

Optionally, you can also pass an options bag to configure the retry policy or proxy settings.
MessagingError

Describes the base class for Messaging Error.

Interfaces

BufferedCloseOptions

Options to configure the close method on the EventHubBufferedProducerClient.
BufferedFlushOptions

Options to configure the flush method on the EventHubBufferedProducerClient.
Checkpoint

A checkpoint is meant to represent the last successfully processed event by the user from a particular partition of a consumer group in an Event Hub instance.

When the updateCheckpoint() method on the PartitionProcessor class is called by the user, a Checkpoint is created internally. It is then stored in the storage solution implemented by the CheckpointManager chosen by the user when creating an EventProcessor.

Users are never expected to interact with Checkpoint directly. This interface exists to support the internal workings of EventProcessor and CheckpointManager.
CheckpointStore

A checkpoint store stores and retrieves partition ownership information and checkpoint details for each partition in a given consumer group of an event hub instance.

Users are not meant to implement an CheckpointStore. Users are expected to choose existing implementations of this interface, instantiate it, and pass it to the EventHubConsumerClient class constructor when instantiating a client. Users are not expected to use any of the methods on a checkpoint store, these are used internally by the client.

Implementations of CheckpointStore can be found on npm by searching for packages with the prefix @azure/eventhub-checkpointstore-.
CreateBatchOptions

Options to configure the createBatch method on the EventHubProducerClient.

  • partitionKey : A value that is hashed to produce a partition assignment.
  • maxSizeInBytes: The upper limit for the size of batch.
  • abortSignal : A signal the request to cancel the send operation.

Example usage:

{
    partitionKey: 'foo',
    maxSizeInBytes: 1024 * 1024 // 1 MB
}
EnqueueEventOptions

Options to configure the enqueueEvents method on the EventHubBufferedProducerClient.
EventData

The interface that describes the data to be sent to Event Hub. Use this as a reference when creating the object to be sent when using the EventHubProducerClient. For example, { body: "your-data" } or

{
   body: "your-data",
   properties: {
      propertyName: "property value"
   }
}
EventDataAdapterParameters

Parameters to the createEventDataAdapter function that creates an event data adapter.
EventDataBatch

An interface representing a batch of events which can be used to send events to Event Hub.

To create the batch, use the createBatch() method on the EventHubProducerClient. To send the batch, use the sendBatch() method on the same client. To fill the batch, use the tryAdd() method on the batch itself.
EventHubBufferedProducerClientOptions

Describes the options that can be provided while creating the EventHubBufferedProducerClient.
EventHubClientOptions

Describes the options that can be provided while creating the EventHubClient.

  • userAgent : A string to append to the built in user agent string that is passed as a connection property to the service.
  • webSocketOptions : Options to configure the channelling of the AMQP connection over Web Sockets.
    • websocket : The WebSocket constructor used to create an AMQP connection if you choose to make the connection over a WebSocket.
    • webSocketConstructorOptions : Options to pass to the Websocket constructor when you choose to make the connection over a WebSocket.
  • retryOptions : The retry options for all the operations on the client/producer/consumer.
    • maxRetries : The number of times the operation can be retried in case of a retryable error.
    • maxRetryDelayInMs: The maximum delay between retries. Applicable only when performing exponential retries.
    • mode: Which retry mode to apply, specified by the RetryMode enum. Options are Exponential and Fixed. Defaults to Fixed.
    • retryDelayInMs: Amount of time to wait in milliseconds before making the next attempt. When mode is set to Exponential, this is used to compute the exponentially increasing delays between retries. Default: 30000 milliseconds.
    • timeoutInMs: Amount of time in milliseconds to wait before the operation times out. This will trigger a retry if there are any retry attempts remaining. Default value: 60000 milliseconds.

A simple usage can be { "maxRetries": 4 }.

Example usage:

{
    retryOptions: {
        maxRetries: 4
    }
}
EventHubConnectionStringProperties

The set of properties that comprise an Event Hub connection string.
EventHubConsumerClientOptions

Describes the options that can be provided while creating the EventHubConsumerClient.

  • loadBalancingOptions: Options to tune how the EventHubConsumerClient claims partitions.
  • userAgent : A string to append to the built in user agent string that is passed as a connection property to the service.
  • webSocketOptions : Options to configure the channelling of the AMQP connection over Web Sockets.
    • websocket : The WebSocket constructor used to create an AMQP connection if you choose to make the connection over a WebSocket.
    • webSocketConstructorOptions : Options to pass to the Websocket constructor when you choose to make the connection over a WebSocket.
  • retryOptions : The retry options for all the operations on the client/producer/consumer.
    • maxRetries : The number of times the operation can be retried in case of a retryable error.
    • maxRetryDelayInMs: The maximum delay between retries. Applicable only when performing exponential retries.
    • mode: Which retry mode to apply, specified by the RetryMode enum. Options are Exponential and Fixed. Defaults to Fixed.
    • retryDelayInMs: Amount of time to wait in milliseconds before making the next attempt. When mode is set to Exponential, this is used to compute the exponentially increasing delays between retries. Default: 30000 milliseconds.
    • timeoutInMs: Amount of time in milliseconds to wait before the operation times out. This will trigger a retry if there are any retry attempts remaining. Default value: 60000 milliseconds.

A simple usage can be { "maxRetries": 4 }.

Example usage:

{
    retryOptions: {
        maxRetries: 4
    }
}
EventHubProperties

Describes the runtime information of an Event Hub.
EventPosition

Represents the position of an event in an Event Hub partition, typically used when calling the subscribe() method on an EventHubConsumerClient to specify the position in the partition to begin receiving events from.

To get an EventPosition representing the start or end of the stream, use the constants earliestEventPosition and latestEventPosition respectively.
GetEventHubPropertiesOptions

The set of options to configure the behavior of getEventHubProperties.

  • abortSignal : An implementation of the AbortSignalLike interface to signal the request to cancel the operation.
  • parentSpan : The Span or SpanContext to use as the parent of the span created while calling this operation.
GetPartitionIdsOptions

The set of options to configure the behavior of getPartitionIds.

  • abortSignal : An implementation of the AbortSignalLike interface to signal the request to cancel the operation.
  • parentSpan : The Span or SpanContext to use as the parent of the span created while calling this operation.
GetPartitionPropertiesOptions

The set of options to configure the behavior of getPartitionProperties.

  • abortSignal : An implementation of the AbortSignalLike interface to signal the request to cancel the operation.
  • parentSpan : The Span or SpanContext to use as the parent of the span created while calling this operation.
LastEnqueuedEventProperties

A set of information about the last enqueued event of a partition, as observed by the consumer as events are received from the Event Hubs service
LoadBalancingOptions

An options bag to configure load balancing settings.
OnSendEventsErrorContext

Contains the events that were not successfully sent to the Event Hub, the partition they were assigned to, and the error that was encountered while sending.
OnSendEventsSuccessContext

Contains the events that were successfully sent to the Event Hub, and the partition they were assigned to.
OperationOptions

Options for configuring tracing and the abortSignal.
PartitionContext

Interface that describes the context passed to each of the functions that are a part of the SubscriptionEventHandlers. When implementing any of these functions, use the context object to get information about the partition as well as the ability to checkpoint.
PartitionOwnership

An interface representing the details on which instance of a EventProcessor owns processing of a given partition from a consumer group of an Event Hub instance.

Note: This is used internally by the EventProcessor and user never has to create it directly.
PartitionProperties

Describes the runtime information of an EventHub Partition.
ReceivedEventData

The interface that describes the structure of the event received from Event Hub. Use this as a reference when creating the processEvents function to process the events recieved from an Event Hub when using the EventHubConsumerClient.
RetryOptions

Retry policy options that determine the mode, number of retries, retry interval etc.
SendBatchOptions

Options to configure the sendBatch method on the EventHubProducerClient when sending an array of events. If partitionId is set, partitionKey must not be set and vice versa.

  • partitionId : The partition this batch will be sent to.
  • partitionKey : A value that is hashed to produce a partition assignment.
  • abortSignal : A signal used to cancel the send operation.
SubscribeOptions

Options to configure the subscribe method on the EventHubConsumerClient. For example, { maxBatchSize: 20, maxWaitTimeInSeconds: 120, startPosition: { sequenceNumber: 123 } }
Subscription

Interface that describes the object returned by the subscribe() method on the EventHubConsumerClient.
SubscriptionEventHandlers

Interface that describes the functions to be implemented by the user which are invoked by the EventHubConsumerClient when the subscribe() method is called to receive events from Event Hub.
TokenCredential

Represents a credential capable of providing an authentication token.
TryAddOptions

Options to configure the behavior of the tryAdd method on the EventDataBatch class.
WebSocketImpl

Describes the required shape of WebSocket constructors.
WebSocketOptions

Options to configure the channelling of the AMQP connection over Web Sockets.

Type Aliases

ProcessCloseHandler

Signature of the user provided function invoked by EventHubConsumerClient just after stopping to receive events from a partition.
ProcessErrorHandler

Signature of the user provided function invoked by EventHubConsumerClient for errors that occur when receiving events or when executing any of the user provided functions passed to the subscribe() method.
ProcessEventsHandler

Signature of the user provided function invoked by EventHubConsumerClient when a set of events is received.
ProcessInitializeHandler

Signature of the user provided function invoked by EventHubConsumerClient just before starting to receive events from a partition.

Enums

CloseReason

An enum representing the different reasons for an EventHubConsumerClient to stop processing events from a partition in a consumer group of an Event Hub.
RetryMode

Describes the Retry Mode type

Functions

createEventDataAdapter(EventDataAdapterParameters)

A function that constructs an event data adapter. That adapter can be used with @azure/schema-registry-avro to encode and decode body in event data.
parseEventHubConnectionString(string)

Parses given connection string into the different properties applicable to Azure Event Hubs. The properties are useful to then construct an EventHubProducerClient or an EventHubConsumerClient.

Function Details

createEventDataAdapter(EventDataAdapterParameters)

A function that constructs an event data adapter. That adapter can be used with @azure/schema-registry-avro to encode and decode body in event data.

function createEventDataAdapter(params?: EventDataAdapterParameters): MessageAdapter<EventData>

Parameters

params
EventDataAdapterParameters

parameters to create the event data

Returns

MessageAdapter<EventData>

An event data adapter that can produce and consume event data

parseEventHubConnectionString(string)

Parses given connection string into the different properties applicable to Azure Event Hubs. The properties are useful to then construct an EventHubProducerClient or an EventHubConsumerClient.

function parseEventHubConnectionString(connectionString: string): Readonly<EventHubConnectionStringProperties>

Parameters

connectionString

string

The connection string associated with the Shared Access Policy created for the Event Hubs namespace.

Returns

Readonly<EventHubConnectionStringProperties>