Options
All
  • Public
  • Public/Protected
  • All
Menu

Class EventHubConsumer

Package version

A consumer is responsible for reading EventData from a specific Event Hub partition in the context of a specific consumer group. To create a consumer use the createConsumer() method on your EventHubClient.

You can pass the below in the options when creating a consumer.

  • ownerLevel : A number indicating that the consumer intends to be an exclusive consumer of events resulting in other consumers to fail if their ownerLevel is lower or doesn't exist.
  • retryOptions: The retry options used to govern retry attempts when an issue is encountered while receiving events.

Multiple consumers are allowed on the same partition in a consumer group. If there is a need to have an exclusive consumer for a partition in a consumer group, then specify the ownerLevel in the options. Exclusive consumers were previously referred to as "Epoch Receivers".

The consumer can be used to receive messages in a batch using receiveBatch() or by registering handlers by using receive() or via an async iterable got by using getEventIterator()

class

Hierarchy

  • EventHubConsumer

Index

Accessors

Methods

Accessors

consumerGroup

  • get consumerGroup(): string
  • property

    The name of the consumer group that this consumer is associated with. Events will be read only in the context of this group.

    readonly

    Returns string

isClosed

  • get isClosed(): boolean
  • property

    Returns true if the consumer is closed. This can happen either because the consumer itself has been closed or the client that created it has been closed.

    readonly

    Returns boolean

isReceivingMessages

  • get isReceivingMessages(): boolean

  • Indicates whether the consumer is currently receiving messages or not. When this returns true, new receive() or receiveBatch() calls cannot be made.

    Returns boolean

lastEnqueuedEventInfo

  • property

    The last enqueued event information. This property will only be enabled when trackLastEnqueuedEventInfo option is set to true in the client.createConsumer() method.

    readonly

    Returns LastEnqueuedEventInfo

ownerLevel

  • get ownerLevel(): number | undefined
  • property

    The owner level associated with an exclusive consumer; for a non-exclusive consumer, this value will be null or undefined.

    When provided, the owner level indicates that a consumer is intended to be the exclusive receiver of events for the requested partition and the associated consumer group. When multiple consumers exist for the same partition/consumer group pair, then the ones with lower or no ownerLevel will get a ReceiverDisconnectedError during the next attempted receive operation.

    readonly

    Returns number | undefined

partitionId

  • get partitionId(): string
  • property

    The identifier of the Event Hub partition that this consumer is associated with. Events will be read only from this partition.

    readonly

    Returns string

Methods

close

  • close(): Promise<void>

  • Closes the underlying AMQP receiver link. Once closed, the consumer cannot be used for any further operations. Use the createConsumer function on the EventHubClient to instantiate a new EventHubConsumer.

    throws

    {Error} Thrown if the underlying connection encounters an error while closing.

    Returns Promise<void>

getEventIterator

  • Returns an async iterable that retrieves events.

    The async iterable cannot indicate that it is done. When using for await (let event of consumer.getEventIterator()) {} to iterate over the events returned by the async iterable, take care to exit the for loop after receiving the desired number of messages, or provide an AbortSignal to control when to exit the loop.

    Parameters

    Returns AsyncIterableIterator<ReceivedEventData>

receive

  • Starts receiving events from the service and calls the user provided message handler for each event. Returns an object that can be used to query the state of the receiver and to stop receiving events as well.

    throws

    {AbortError} Thrown if the operation is cancelled via the abortSignal.

    throws

    {TypeError} Thrown if a required parameter is missing.

    throws

    {Error} Thrown if the underlying connection or receiver has been closed. Create a new EventHubConsumer using the EventHubClient createConsumer method.

    throws

    {Error} Thrown if the receiver is already receiving messages.

    Parameters

    • onMessage: OnMessage

      The message handler to receive event data objects.

    • onError: OnError

      The error handler for errora that can occur when receiving events.

    • Optional abortSignal: AbortSignalLike

      An implementation of the AbortSignalLike interface to signal the request to cancel the operation. For example, use the @azure/abort-controller to create an AbortSignal.

    Returns ReceiveHandler

    ReceiveHandler - An object that provides a mechanism to stop receiving more messages.

receiveBatch

  • receiveBatch(maxMessageCount: number, maxWaitTimeInSeconds?: number, abortSignal?: AbortSignalLike): Promise<ReceivedEventData[]>

  • Returns a promise that resolves to an array of events received from the service.

    throws

    {AbortError} Thrown if the operation is cancelled via the abortSignal.

    throws

    {MessagingError} Thrown if an error is encountered while receiving a message.

    throws

    {Error} Thrown if the underlying connection or receiver has been closed. Create a new EventHubConsumer using the EventHubClient createConsumer method.

    throws

    {Error} Thrown if the receiver is already receiving messages.

    Parameters

    • maxMessageCount: number

      The maximum number of messages to receive.

    • Default value maxWaitTimeInSeconds: number = 60

      The maximum amount of time to wait to build up the requested message count; If not provided, it defaults to 60 seconds.

    • Optional abortSignal: AbortSignalLike

      An implementation of the AbortSignalLike interface to signal the request to cancel the operation. For example, use the @azure/abort-controller to create an AbortSignal.

    Returns Promise<ReceivedEventData[]>

    Promise<ReceivedEventData[]>.

Generated using TypeDoc