30 строки
19 KiB
YAML
30 строки
19 KiB
YAML
### YamlMime:JavaPackage
|
|
uid: "com.azure.messaging.eventhubs"
|
|
fullName: "com.azure.messaging.eventhubs"
|
|
name: "com.azure.messaging.eventhubs"
|
|
summary: "[Azure Event Hubs][] is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers.\n\n\n[Azure Event Hubs]: https://learn.microsoft.com/azure/event-hubs/event-hubs-about"
|
|
classes:
|
|
- "com.azure.messaging.eventhubs.EventData"
|
|
- "com.azure.messaging.eventhubs.EventDataBatch"
|
|
- "com.azure.messaging.eventhubs.EventHubBufferedProducerAsyncClient"
|
|
- "com.azure.messaging.eventhubs.EventHubBufferedProducerClient"
|
|
- "com.azure.messaging.eventhubs.EventHubBufferedProducerClientBuilder"
|
|
- "com.azure.messaging.eventhubs.EventHubClientBuilder"
|
|
- "com.azure.messaging.eventhubs.EventHubConsumerAsyncClient"
|
|
- "com.azure.messaging.eventhubs.EventHubConsumerClient"
|
|
- "com.azure.messaging.eventhubs.EventHubProducerAsyncClient"
|
|
- "com.azure.messaging.eventhubs.EventHubProducerClient"
|
|
- "com.azure.messaging.eventhubs.EventHubProperties"
|
|
- "com.azure.messaging.eventhubs.EventProcessorClient"
|
|
- "com.azure.messaging.eventhubs.EventProcessorClientBuilder"
|
|
- "com.azure.messaging.eventhubs.PartitionProperties"
|
|
enums:
|
|
- "com.azure.messaging.eventhubs.LoadBalancingStrategy"
|
|
- "com.azure.messaging.eventhubs.Messages"
|
|
interfaces:
|
|
- "com.azure.messaging.eventhubs.CheckpointStore"
|
|
desc: "[Azure Event Hubs][] is a highly scalable publish-subscribe service that can ingest millions of events per second and stream them to multiple consumers. This lets you process and analyze the massive amounts of data produced by your connected devices and applications. Once Event Hubs has collected the data, you can retrieve, transform, and store it by using any real-time analytics provider or with batching/storage adapters.\n\nThe Azure Event Hubs client library allows Java developers to interact with Azure Event Hubs. It provides a set of clients that enable Java developers to publish events to and consume events from an Event Hub.\n\n## Key Concepts ##\n\n * **Event Hub producer:** A source of telemetry data, diagnostics information, usage logs, or other data, as part of an embedded device solution, a mobile device application, a game title running on a console or other device, some client or server based business solution, or a website\n * **Event Hub consumer:** Fetches events published to an Event Hub and processes it. Processing may involve aggregation, complex computation, and filtering. Processing may also involve distribution or storage of the information in a raw or transformed fashion. Event Hub consumers are often robust and high-scale platform infrastructure parts with built-in analytics capabilities, like Azure Stream Analytics, Apache Spark, or Apache Storm.\n * **Partition:** An ordered sequence of events that is held in an Event Hub. Azure Event Hubs provides message streaming through a partitioned consumer pattern in which each consumer only reads a specific subset, or partition, of the message stream. As newer events arrive, they are added to the end of this sequence. The number of partitions is specified at the time an Event Hub is created and cannot be changed.\n * **Consumer group:** A view of an entire Event Hub. Consumer groups enable multiple consuming applications to each have a separate view of the event stream, and to read the stream independently at their own pace and from their own position. There can be at most 5 concurrent readers on a partition per consumer group; however it is recommended that there is only one active consumer for a given partition and consumer group pairing. Each active reader receives the events from its partition; if there are multiple readers on the same partition, then they will receive duplicate events.\n * **Stream offset:** The position of an event within an Event Hub partition. It is a client-side cursor that specifies the point in the stream where the event is located. The offset of an event can change as events expire from the stream.\n * **Stream sequence number:** A number assigned to the event when it was enqueued in the associated Event Hub partition. This is unique for every message received in the Event Hub partition.\n * **Checkpointing:** A process by which readers mark or commit their position within a partition event sequence. Checkpointing is the responsibility of the consumer and occurs on a per-partition basis within a consumer group. This responsibility means that for each consumer group, each partition reader must keep track of its current position in the event stream, and can inform the service when it considers the data stream complete.\n\n## Getting Started ##\n\nService clients are the point of interaction for developers to use Azure Event Hubs. <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubProducerClient\"></xref> and <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubProducerAsyncClient\"></xref> are the sync and async clients for publishing events to an Event Hub. Similarly, <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerClient\"></xref> and <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\"></xref> are the sync and async clients for consuming events from an Event Hub. In production scenarios, we recommend users leverage <xref uid=\"com.azure.messaging.eventhubs.EventProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventProcessorClient\"></xref> because consumes events from all Event Hub partition, load balances work between multiple instances of <xref uid=\"com.azure.messaging.eventhubs.EventProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventProcessorClient\"></xref> and can perform checkpointing.\n\nThe examples shown in this document use a credential object named DefaultAzureCredential for authentication, which is appropriate for most scenarios, including local development and production environments. Additionally, we recommend using [managed identity][] for authentication in production environments. You can find more information on different ways of authenticating and their corresponding credential types in the [Azure Identity documentation\"][Azure Identity documentation].\n\n### Publishing events ###\n\nThis library provides several ways to publish events to Azure Event Hubs. There is a producer client, that sends events immediately to Azure Event Hubs and a buffered producer, that batches events together in the background and publishes them later. These two clients have synchronous and asynchronous versions. The samples below demonstrate simple scenarios, more snippets can be found in the class documentation for <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubProducerClient\"></xref>, <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubProducerAsyncClient\"></xref>, <xref uid=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\"></xref>, and <xref uid=\"com.azure.messaging.eventhubs.EventHubBufferedProducerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubBufferedProducerAsyncClient\"></xref>.\n\nIn the following snippets, `fullyQualifiedNamespace` is the Event Hubs Namespace's host name. It is listed under the \"Essentials\" panel after navigating to the Event Hubs Namespace via Azure Portal. The credential used is `DefaultAzureCredential` because it combines commonly used credentials in deployment and development and chooses the credential to used based on its running environment.\n\n**Sample: Construct a synchronous producer and publish events**\n\nThe following code sample demonstrates the creation of the synchronous client <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubProducerClient\"></xref>.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n EventHubProducerClient producer = new EventHubClientBuilder()\n .credential(\"<<fully-qualified-namespace>>\", \"<<event-hub-name>>\",\n credential)\n .buildProducerClient();\n\n List<EventData> allEvents = Arrays.asList(new EventData(\"Foo\"), new EventData(\"Bar\"));\n EventDataBatch eventDataBatch = producer.createBatch();\n\n for (EventData eventData : allEvents) {\n if (!eventDataBatch.tryAdd(eventData)) {\n producer.send(eventDataBatch);\n eventDataBatch = producer.createBatch();\n\n // Try to add that event that couldn't fit before.\n if (!eventDataBatch.tryAdd(eventData)) {\n throw new IllegalArgumentException(\"Event is too large for an empty batch. Max size: \"\n + eventDataBatch.getMaxSizeInBytes());\n }\n }\n }\n\n // send the last batch of remaining events\n if (eventDataBatch.getCount() > 0) {\n producer.send(eventDataBatch);\n }\n\n // Clients are expected to be long-lived objects.\n // Dispose of the producer to close any underlying resources when we are finished with it.\n producer.close();\n```\n\n**Sample: Creating an <xref uid=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\"></xref> and enqueuing events**\n\nThe following code sample demonstrates the creation of the synchronous client <xref uid=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubBufferedProducerClient\"></xref> as well as enqueueing events. The producer is set to publish events every 60 seconds with a buffer size of 1500 events for each partition.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // \"<<fully-qualified-namespace>>\" will look similar to \"{your-namespace}.servicebus.windows.net\"\n // \"<<event-hub-name>>\" will be the name of the Event Hub instance you created inside the Event Hubs namespace.\n EventHubBufferedProducerClient client = new EventHubBufferedProducerClientBuilder()\n .credential(\"fully-qualified-namespace\", \"event-hub-name\", credential)\n .onSendBatchSucceeded(succeededContext -> {\n System.out.println(\"Successfully published events to: \" + succeededContext.getPartitionId());\n })\n .onSendBatchFailed(failedContext -> {\n System.out.printf(\"Failed to published events to %s. Error: %s%n\",\n failedContext.getPartitionId(), failedContext.getThrowable());\n })\n .buildClient();\n\n List<EventData> events = Arrays.asList(new EventData(\"maple\"), new EventData(\"aspen\"),\n new EventData(\"oak\"));\n\n // Enqueues the events to be published.\n client.enqueueEvents(events);\n\n // Seconds later, enqueue another event.\n client.enqueueEvent(new EventData(\"bonsai\"));\n\n // Causes any buffered events to be flushed before closing underlying connection.\n client.close();\n```\n\n### Consuming events ###\n\nThis library provides several ways to consume events from Azure Event Hubs. There are consumer clients, <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerClient\"></xref> and <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\"></xref>, which fetches events from either a single partition or all partitions in an Event Hub. For production, we recommend <xref uid=\"com.azure.messaging.eventhubs.EventProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventProcessorClient\"></xref> whose checkpoints are backed by a durable storage such as Azure Blob Storage. The samples below demonstrate simple scenarios, more snippets can be found in the class documentation for <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerClient\"></xref>, <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerAsyncClient\"></xref>, and <xref uid=\"com.azure.messaging.eventhubs.EventProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventProcessorClient\"></xref>.\n\nIn the following snippets, `fullyQualifiedNamespace` is the Event Hubs Namespace's host name. It is listed under the \"Essentials\" panel after navigating to the Event Hubs Namespace via Azure Portal. The credential used is `DefaultAzureCredential` because it combines commonly used credentials in deployment and development and chooses the credential to used based on its running environment. The `consumerGroup` is found by navigating to the Event Hub instance, and selecting \"Consumer groups\" under the \"Entities\" panel. The `consumerGroup` is required for creating consumer clients.\n\nThe credential used is `DefaultAzureCredential` because it combines commonly used credentials in deployment and development and chooses the credential to used based on its running environment.\n\n**Sample: Construct a synchronous consumer and receive events**\n\nThe following code sample demonstrates the creation of the synchronous client <xref uid=\"com.azure.messaging.eventhubs.EventHubConsumerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventHubConsumerClient\"></xref>. In addition, it receives the first 100 events that were enqueued 12 hours ago. If there are less than 100 events, the ones fetched within `maxWaitTime` of 30 seconds are returned.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // \"<<fully-qualified-namespace>>\" will look similar to \"{your-namespace}.servicebus.windows.net\"\n // \"<<event-hub-name>>\" will be the name of the Event Hub instance you created inside the Event Hubs namespace.\n EventHubConsumerClient consumer = new EventHubClientBuilder()\n .credential(\"<<fully-qualified-namespace>>\", \"<<event-hub-name>>\",\n credential)\n .consumerGroup(EventHubClientBuilder.DEFAULT_CONSUMER_GROUP_NAME)\n .buildConsumerClient();\n\n Instant twelveHoursAgo = Instant.now().minus(Duration.ofHours(12));\n EventPosition startingPosition = EventPosition.fromEnqueuedTime(twelveHoursAgo);\n String partitionId = \"0\";\n\n // Reads events from partition '0' and returns the first 100 received or until the 30 seconds has elapsed.\n IterableStream<PartitionEvent> events = consumer.receiveFromPartition(partitionId, 100,\n startingPosition, Duration.ofSeconds(30));\n\n Long lastSequenceNumber = -1L;\n for (PartitionEvent partitionEvent : events) {\n // For each event, perform some sort of processing.\n System.out.print(\"Event received: \" + partitionEvent.getData().getSequenceNumber());\n lastSequenceNumber = partitionEvent.getData().getSequenceNumber();\n }\n\n // Figure out what the next EventPosition to receive from is based on last event we processed in the stream.\n // If lastSequenceNumber is -1L, then we didn't see any events the first time we fetched events from the\n // partition.\n if (lastSequenceNumber != -1L) {\n EventPosition nextPosition = EventPosition.fromSequenceNumber(lastSequenceNumber, false);\n\n // Gets the next set of events from partition '0' to consume and process.\n IterableStream<PartitionEvent> nextEvents = consumer.receiveFromPartition(partitionId, 100,\n nextPosition, Duration.ofSeconds(30));\n }\n```\n\n**Sample: Construct an <xref uid=\"com.azure.messaging.eventhubs.EventProcessorClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.EventProcessorClient\"></xref>**\n\nThe following code sample demonstrates the creation of the processor client. The processor client is recommended for production scenarios because it can load balance between multiple running instances, can perform checkpointing, and reconnects on transient failures such as network outages. The sample below uses an in-memory <xref uid=\"com.azure.messaging.eventhubs.CheckpointStore\" data-throw-if-not-resolved=\"false\" data-raw-source=\"com.azure.messaging.eventhubs.CheckpointStore\"></xref> but [ azure-messaging-eventhubs-checkpointstore-blob][azure-messaging-eventhubs-checkpointstore-blob] provides a checkpoint store backed by Azure Blob Storage.\n\n```java\nTokenCredential credential = new DefaultAzureCredentialBuilder().build();\n\n // \"<<fully-qualified-namespace>>\" will look similar to \"{your-namespace}.servicebus.windows.net\"\n // \"<<event-hub-name>>\" will be the name of the Event Hub instance you created inside the Event Hubs namespace.\n EventProcessorClient eventProcessorClient = new EventProcessorClientBuilder()\n .consumerGroup(EventHubClientBuilder.DEFAULT_CONSUMER_GROUP_NAME)\n .credential(\"<<fully-qualified-namespace>>\", \"<<event-hub-name>>\",\n credential)\n .processEvent(eventContext -> {\n System.out.printf(\"Partition id = %s and sequence number of event = %s%n\",\n eventContext.getPartitionContext().getPartitionId(),\n eventContext.getEventData().getSequenceNumber());\n })\n .processError(errorContext -> {\n System.out.printf(\"Error occurred in partition processor for partition %s, %s%n\",\n errorContext.getPartitionContext().getPartitionId(),\n errorContext.getThrowable());\n })\n .checkpointStore(new SampleCheckpointStore())\n .buildEventProcessorClient();\n\n eventProcessorClient.start();\n\n // Continue to perform other tasks while the processor is running in the background.\n //\n // Finally, stop the processor client when application is finished.\n eventProcessorClient.stop();\n```\n\n\n[Azure Event Hubs]: https://learn.microsoft.com/azure/event-hubs/event-hubs-about\n[managed identity]: https://learn.microsoft.com/azure/active-directory/managed-identities-azure-resources/\n[Azure Identity documentation]: https://learn.microsoft.com/java/api/overview/azure/identity-readme\n[azure-messaging-eventhubs-checkpointstore-blob]: https://central.sonatype.com/artifact/com.azure/azure-messaging-eventhubs-checkpointstore-blob"
|
|
metadata: {}
|
|
package: "com.azure.messaging.eventhubs"
|
|
artifact: com.azure:azure-messaging-eventhubs:5.18.7
|