Share via

EventHubProducerClient class

  • Reference
Package:
@azure/event-hubs

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.

Constructors

EventHubProducerClient(string, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.
EventHubProducerClient(string, string, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.
EventHubProducerClient(string, string, TokenCredential | NamedKeyCredential | SASCredential, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.

Properties

eventHubName

The name of the Event Hub instance for which this client is created.
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.
identifier

The name used to identify this EventHubProducerClient. 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.
createBatch(CreateBatchOptions)

Creates an instance of EventDataBatch to which one can add events until the maximum supported size is reached. The batch can be passed to the sendBatch method of the EventHubProducerClient to be sent to Azure Event Hubs.

Events with different values for partitionKey or partitionId will need to be put into different batches. To simplify such batch management across partitions or to have the client automatically batch events and send them in specific intervals, use EventHubBufferedProducerClient instead.

The below example assumes you have an array of events at hand to be batched safely. If you have events coming in one by one, EventHubBufferedProducerClient is recommended instead for effecient management of batches.

Example usage:

const client = new EventHubProducerClient(connectionString);
let batch = await client.createBatch();
for (let i = 0; i < messages.length; i++) {
 if (!batch.tryAdd(messages[i])) {
   await client.sendBatch(batch);
   batch = await client.createBatch();
   if (!batch.tryAdd(messages[i])) {
     throw new Error("Message too big to fit")
   }
   if (i === messages.length - 1) {
     await client.sendBatch(batch);
   }
  }
}
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.
sendBatch(EventDataBatch, OperationOptions)

Sends a batch of events created using EventHubProducerClient.createBatch() to the associated Event Hub.

Events with different values for partitionKey or partitionId will need to be put into different batches. To simplify such batch management across partitions or to have the client automatically batch events and send them in specific intervals, use EventHubBufferedProducerClient instead.

The below example assumes you have an array of events at hand to be batched safely. If you have events coming in one by one, EventHubBufferedProducerClient is recommended instead for effecient management of batches.

Example usage:

const client = new EventHubProducerClient(connectionString);
let batch = await client.createBatch();
for (let i = 0; i < messages.length; i++) {
 if (!batch.tryAdd(messages[i])) {
   await client.sendBatch(batch);
   batch = await client.createBatch();
   if (!batch.tryAdd(messages[i])) {
     throw new Error("Message too big to fit")
   }
   if (i === messages.length - 1) {
     await client.sendBatch(batch);
   }
  }
}
sendBatch(EventData[] | AmqpAnnotatedMessage[], SendBatchOptions)

Sends an array of events as a batch to the associated Event Hub.

Azure Event Hubs has a limit on the size of the batch that can be sent which if exceeded will result in an error with code MessageTooLargeError. To safely send within batch size limits, use EventHubProducerClient.createBatch() or EventHubBufferedProducerClient instead.

Example usage:

const client = new EventHubProducerClient(connectionString);
await client.sendBatch(messages);

Constructor Details

EventHubProducerClient(string, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.

new EventHubProducerClient(connectionString: string, options?: EventHubClientOptions)

Parameters

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
EventHubClientOptions

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.

EventHubProducerClient(string, string, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.

new EventHubProducerClient(connectionString: string, eventHubName: string, options?: EventHubClientOptions)

Parameters

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
EventHubClientOptions

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.

EventHubProducerClient(string, string, TokenCredential | NamedKeyCredential | SASCredential, EventHubClientOptions)

The EventHubProducerClient class is used to send events to an Event Hub. Use the options parmeter to configure retry policy or proxy settings.

new EventHubProducerClient(fullyQualifiedNamespace: string, eventHubName: string, credential: TokenCredential | NamedKeyCredential | SASCredential, options?: EventHubClientOptions)

Parameters

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 | NamedKeyCredential | SASCredential

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
EventHubClientOptions

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

eventHubName

The name of the Event Hub instance for which this client is created.

string eventHubName

Property 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 fullyQualifiedNamespace

Property Value

string

identifier

The name used to identify this EventHubProducerClient. If not specified or empty, a random unique one will be generated.

identifier: string

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(): Promise<void>

Returns

Promise<void>

Promise

createBatch(CreateBatchOptions)

Creates an instance of EventDataBatch to which one can add events until the maximum supported size is reached. The batch can be passed to the sendBatch method of the EventHubProducerClient to be sent to Azure Event Hubs.

Events with different values for partitionKey or partitionId will need to be put into different batches. To simplify such batch management across partitions or to have the client automatically batch events and send them in specific intervals, use EventHubBufferedProducerClient instead.

The below example assumes you have an array of events at hand to be batched safely. If you have events coming in one by one, EventHubBufferedProducerClient is recommended instead for effecient management of batches.

Example usage:

const client = new EventHubProducerClient(connectionString);
let batch = await client.createBatch();
for (let i = 0; i < messages.length; i++) {
 if (!batch.tryAdd(messages[i])) {
   await client.sendBatch(batch);
   batch = await client.createBatch();
   if (!batch.tryAdd(messages[i])) {
     throw new Error("Message too big to fit")
   }
   if (i === messages.length - 1) {
     await client.sendBatch(batch);
   }
  }
}

function createBatch(options?: CreateBatchOptions): Promise<EventDataBatch>

Parameters

options
CreateBatchOptions

Configures the behavior of the batch.

  • partitionKey : A value that is hashed and used by the Azure Event Hubs service to determine the partition to which the events need to be sent.
  • partitionId : Id of the partition to which the batch of events need to be sent.
  • maxSizeInBytes: The upper limit for the size of batch. The tryAdd function will return false after this limit is reached.
  • abortSignal : A signal the request to cancel the operation.

Returns

Promise<EventDataBatch>

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 .

sendBatch(EventDataBatch, OperationOptions)

Sends a batch of events created using EventHubProducerClient.createBatch() to the associated Event Hub.

Events with different values for partitionKey or partitionId will need to be put into different batches. To simplify such batch management across partitions or to have the client automatically batch events and send them in specific intervals, use EventHubBufferedProducerClient instead.

The below example assumes you have an array of events at hand to be batched safely. If you have events coming in one by one, EventHubBufferedProducerClient is recommended instead for effecient management of batches.

Example usage:

const client = new EventHubProducerClient(connectionString);
let batch = await client.createBatch();
for (let i = 0; i < messages.length; i++) {
 if (!batch.tryAdd(messages[i])) {
   await client.sendBatch(batch);
   batch = await client.createBatch();
   if (!batch.tryAdd(messages[i])) {
     throw new Error("Message too big to fit")
   }
   if (i === messages.length - 1) {
     await client.sendBatch(batch);
   }
  }
}

function sendBatch(batch: EventDataBatch, options?: OperationOptions): Promise<void>

Parameters

batch
EventDataBatch

A batch of events that you can create using the createBatch method.

options
OperationOptions

A set of options that can be specified to influence the way in which events are sent to the associated Event Hub.

  • abortSignal : A signal the request to cancel the send operation.

Returns

Promise<void>

Promise

sendBatch(EventData[] | AmqpAnnotatedMessage[], SendBatchOptions)

Sends an array of events as a batch to the associated Event Hub.

Azure Event Hubs has a limit on the size of the batch that can be sent which if exceeded will result in an error with code MessageTooLargeError. To safely send within batch size limits, use EventHubProducerClient.createBatch() or EventHubBufferedProducerClient instead.

Example usage:

const client = new EventHubProducerClient(connectionString);
await client.sendBatch(messages);

function sendBatch(batch: EventData[] | AmqpAnnotatedMessage[], options?: SendBatchOptions): Promise<void>

Parameters

batch

EventData[] | AmqpAnnotatedMessage[]

An array of EventData or AmqpAnnotatedMessage.

options
SendBatchOptions

A set of options that can be specified to influence the way in which events are sent to the associated Event Hub.

  • abortSignal : A signal the request to cancel the send operation.
  • partitionId : The partition this batch will be sent to. If set, partitionKey can not be set.
  • partitionKey : A value that is hashed to produce a partition assignment. If set, partitionId can not be set.

Returns

Promise<void>

Promise