@azure/event-hubs package

Classes

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.

Interfaces

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
}
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"
   }
}
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.

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

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.

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.

TryAddOptions

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

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.

Functions

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

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)

Parameters

connectionString

string

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

Returns