EventHubConsumerClient class

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.

Constructors

EventHubConsumerClient(string, string, CheckpointStore, EventHubConsumerClientOptions)
EventHubConsumerClient(string, string, EventHubConsumerClientOptions)
EventHubConsumerClient(string, string, string, CheckpointStore, EventHubConsumerClientOptions)
EventHubConsumerClient(string, string, string, EventHubConsumerClientOptions)
EventHubConsumerClient(string, string, string, TokenCredential, CheckpointStore, EventHubConsumerClientOptions)
EventHubConsumerClient(string, string, string, TokenCredential, EventHubConsumerClientOptions)

Properties

defaultConsumerGroupName

The name of the default consumer group in the Event Hubs service.

eventHubName
fullyQualifiedNamespace

Methods

close()

Closes the AMQP connection to the Event Hub instance, returning a promise that will be resolved when disconnection is completed.

getEventHubProperties(GetEventHubPropertiesOptions)

Provides the Event Hub runtime information.

getPartitionIds(GetPartitionIdsOptions)

Provides the id for each partition associated with the Event Hub.

getPartitionProperties(string, GetPartitionPropertiesOptions)

Provides information about the state of the specified partition.

subscribe(string, SubscriptionEventHandlers, SubscribeOptions)

Subscribe to events from a single partition. Call close() on the returned object to stop receiving events. Example usage:

const client = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName);
const subscription = client.subscribe(
 partitionId,
 {
   processEvents: (events, context) => { console.log("Received event count: ", events.length) },
   processError: (err, context) => { console.log("Error: ", err) }
 },
 { startPosition: earliestEventPosition }
);
subscribe(SubscriptionEventHandlers, SubscribeOptions)

Subscribe to events from all partitions. If checkpoint store is provided to the EventHubConsumerClient and there are multiple instances of your application, then each instance will subscribe to a subset of the partitions such that the load is balanced amongst them.

Call close() on the returned object to stop receiving events.

Example usage:

const client = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName);
const subscription = client.subscribe(
 {
   processEvents: (events, context) => { console.log("Received event count: ", events.length) },
   processError: (err, context) => { console.log("Error: ", err) }
 },
 { startPosition: earliestEventPosition }
);

Constructor Details

EventHubConsumerClient(string, string, CheckpointStore, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, connectionString: string, checkpointStore: CheckpointStore, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

checkpointStore
CheckpointStore

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. It is also used by the client to load balance multiple instances of your application.

options
EventHubConsumerClientOptions

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.

EventHubConsumerClient(string, string, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, connectionString: string, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

options
EventHubConsumerClientOptions

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.

EventHubConsumerClient(string, string, string, CheckpointStore, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, connectionString: string, eventHubName: string, checkpointStore: CheckpointStore, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

eventHubName

string

The name of the specific Event Hub to connect the client to.

checkpointStore
CheckpointStore

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. It is also used by the client to load balance multiple instances of your application.

options
EventHubConsumerClientOptions

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.

EventHubConsumerClient(string, string, string, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, connectionString: string, eventHubName: string, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

eventHubName

string

The name of the specific Event Hub to connect the client to.

options
EventHubConsumerClientOptions

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.

EventHubConsumerClient(string, string, string, TokenCredential, CheckpointStore, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential, checkpointStore: CheckpointStore, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

TokenCredential

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 the credentials.

checkpointStore
CheckpointStore

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. It is also used by the client to load balance multiple instances of your application.

options
EventHubConsumerClientOptions

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.

EventHubConsumerClient(string, string, string, TokenCredential, EventHubConsumerClientOptions)

new EventHubConsumerClient(consumerGroup: string, fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential, options?: EventHubConsumerClientOptions)

Parameters

consumerGroup

string

The name of the consumer group from which you want to process events.

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

TokenCredential

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 the credentials.

options
EventHubConsumerClientOptions

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

defaultConsumerGroupName

The name of the default consumer group in the Event Hubs service.

static defaultConsumerGroupName: string

Property Value

string

eventHubName

string eventHubName

Property Value

string

fullyQualifiedNamespace

string fullyQualifiedNamespace

Property Value

string

Method Details

close()

Closes the AMQP connection to the Event Hub instance, returning a promise that will be resolved when disconnection is completed.

function close()

Returns

Promise<void>

Promise

getEventHubProperties(GetEventHubPropertiesOptions)

Provides the Event Hub runtime information.

function getEventHubProperties(options?: GetEventHubPropertiesOptions)

Parameters

options
GetEventHubPropertiesOptions

The set of options to apply to the operation call.

Returns

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)

Parameters

options
GetPartitionIdsOptions

The set of options to apply to the operation call.

Returns

Promise<Array<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)

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

A promise that resolves with information about the state of the partition .

subscribe(string, SubscriptionEventHandlers, SubscribeOptions)

Subscribe to events from a single partition. Call close() on the returned object to stop receiving events. Example usage:

const client = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName);
const subscription = client.subscribe(
 partitionId,
 {
   processEvents: (events, context) => { console.log("Received event count: ", events.length) },
   processError: (err, context) => { console.log("Error: ", err) }
 },
 { startPosition: earliestEventPosition }
);
function subscribe(partitionId: string, handlers: SubscriptionEventHandlers, options?: SubscribeOptions)

Parameters

partitionId

string

The id of the partition to subscribe to.

handlers
SubscriptionEventHandlers

Handlers for the lifecycle of the subscription - subscription initialization of the partition, receiving events, handling errors and the closing of a subscription to the partition.

options
SubscribeOptions

Configures the way events are received. Most common are maxBatchSize and maxWaitTimeInSeconds that control the flow of events to the handler provided to receive events as well as the start position. For example, `{ maxBatchSize: 20, maxWaitTimeInSeconds: 120, startPosition: { sequenceNumber: 123 } }

Returns

subscribe(SubscriptionEventHandlers, SubscribeOptions)

Subscribe to events from all partitions. If checkpoint store is provided to the EventHubConsumerClient and there are multiple instances of your application, then each instance will subscribe to a subset of the partitions such that the load is balanced amongst them.

Call close() on the returned object to stop receiving events.

Example usage:

const client = new EventHubConsumerClient(consumerGroup, connectionString, eventHubName);
const subscription = client.subscribe(
 {
   processEvents: (events, context) => { console.log("Received event count: ", events.length) },
   processError: (err, context) => { console.log("Error: ", err) }
 },
 { startPosition: earliestEventPosition }
);
function subscribe(handlers: SubscriptionEventHandlers, options?: SubscribeOptions)

Parameters

handlers
SubscriptionEventHandlers

Handlers for the lifecycle of the subscription - subscription initialization per partition, receiving events, handling errors and the closing of a subscription per partition.

options
SubscribeOptions

Configures the way events are received. Most common are maxBatchSize and maxWaitTimeInSeconds that control the flow of events to the handler provided to receive events as well as the start position. For example, `{ maxBatchSize: 20, maxWaitTimeInSeconds: 120, startPosition: { sequenceNumber: 123 } }

Returns