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
| Event |
The |
| Event |
The |
| Event |
The |
| Event |
The |
| Event |
The |
| Event |
The |
Properties
| default |
The name of the default consumer group in the Event Hubs service. |
| 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 EventHubConsumerClient. If not specified or empty, a random unique one will be generated. |
Methods
| close() | Closes the AMQP connection to the Event Hub instance, returning a promise that will be resolved when disconnection is completed. |
| 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. |
| subscribe(string, Subscription |
Subscribe to events from a single partition. Call close() on the returned object to stop receiving events. Example usage: |
| subscribe(Subscription |
Subscribe to events from all partitions. If checkpoint store is provided to the Call close() on the returned object to stop receiving events. Example usage: |
Constructor Details
EventHubConsumerClient(string, string, CheckpointStore, EventHubConsumerClientOptions)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
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)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
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)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
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 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.
- 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)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
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 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.
- 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 | NamedKeyCredential | SASCredential, CheckpointStore, EventHubConsumerClientOptions)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
new EventHubConsumerClient(consumerGroup: string, fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential | NamedKeyCredential | SASCredential, 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
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.
- 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 | NamedKeyCredential | SASCredential, EventHubConsumerClientOptions)
The EventHubConsumerClient class is used to consume events from an Event Hub.
Use the options parmeter to configure retry policy or proxy settings.
new EventHubConsumerClient(consumerGroup: string, fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential | NamedKeyCredential | SASCredential, 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
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.
- 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: stringProperty Value
string
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 EventHubConsumerClient. If not specified or empty, a random unique one will be generated.
identifier: stringProperty 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(): Promise<void>Returns
Promise<void>
Promise
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 .
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): SubscriptionParameters
- 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): SubscriptionParameters
- 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 } }