azure-docs-sdk-java/docs-ref-autogen/com.azure.messaging.eventhu...

161 строка
23 KiB
YAML

### YamlMime:JavaType
uid: "com.azure.messaging.eventhubs.EventHubProducerClient"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient"
name: "EventHubProducerClient"
nameWithType: "EventHubProducerClient"
summary: "A **synchronous** producer responsible for transmitting <xref uid=\"com.azure.messaging.eventhubs.EventData\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventData\"></xref> to a specific Event Hub, grouped together in batches."
inheritances:
- "<xref href=\"java.lang.Object?displayProperty=fullName\" data-throw-if-not-resolved=\"False\" />"
inheritedClassMethods:
- classRef: "java.lang.<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html\">Object</a>"
methodsRef:
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#clone--\">clone</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#equals-java.lang.Object-\">equals</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#finalize--\">finalize</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#getClass--\">getClass</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#hashCode--\">hashCode</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notify--\">notify</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#notifyAll--\">notifyAll</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#toString--\">toString</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait--\">wait</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-\">wait</a>"
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Object.html#wait-long-int-\">wait</a>"
syntax: "public class **EventHubProducerClient**</br> implements <a href=\"https://docs.oracle.com/javase/8/docs/api/java/io/Closeable.html\">Closeable</a>"
methods:
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.close()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.close()"
name: "close()"
nameWithType: "EventHubProducerClient.close()"
syntax: "public void close()"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.createBatch()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.createBatch()"
name: "createBatch()"
nameWithType: "EventHubProducerClient.createBatch()"
summary: "Creates an <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> that can fit as many events as the transport allows."
syntax: "public EventDataBatch createBatch()"
desc: "Creates an <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> that can fit as many events as the transport allows."
returns:
description: "A new <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> that can fit as many events as the transport allows."
type: "<xref href=\"com.azure.messaging.eventhubs.EventDataBatch?alt=com.azure.messaging.eventhubs.EventDataBatch&text=EventDataBatch\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.createBatch(com.azure.messaging.eventhubs.models.CreateBatchOptions)"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.createBatch(CreateBatchOptions options)"
name: "createBatch(CreateBatchOptions options)"
nameWithType: "EventHubProducerClient.createBatch(CreateBatchOptions options)"
summary: "Creates an <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> configured with the options specified."
parameters:
- description: "A set of options used to configure the <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref>."
name: "options"
type: "<xref href=\"com.azure.messaging.eventhubs.models.CreateBatchOptions?alt=com.azure.messaging.eventhubs.models.CreateBatchOptions&text=CreateBatchOptions\" data-throw-if-not-resolved=\"False\" />"
syntax: "public EventDataBatch createBatch(CreateBatchOptions options)"
desc: "Creates an <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> configured with the options specified."
returns:
description: "A new <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref> that can fit as many events as the transport allows."
type: "<xref href=\"com.azure.messaging.eventhubs.EventDataBatch?alt=com.azure.messaging.eventhubs.EventDataBatch&text=EventDataBatch\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getEventHubName()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getEventHubName()"
name: "getEventHubName()"
nameWithType: "EventHubProducerClient.getEventHubName()"
summary: "Gets the Event Hub name this client interacts with."
syntax: "public String getEventHubName()"
desc: "Gets the Event Hub name this client interacts with."
returns:
description: "The Event Hub name this client interacts with."
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getEventHubProperties()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getEventHubProperties()"
name: "getEventHubProperties()"
nameWithType: "EventHubProducerClient.getEventHubProperties()"
summary: "Retrieves information about an Event Hub, including the number of partitions present and their identifiers."
syntax: "public EventHubProperties getEventHubProperties()"
desc: "Retrieves information about an Event Hub, including the number of partitions present and their identifiers."
returns:
description: "The set of information for the Event Hub that this client is associated with."
type: "<xref href=\"com.azure.messaging.eventhubs.EventHubProperties?alt=com.azure.messaging.eventhubs.EventHubProperties&text=EventHubProperties\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getFullyQualifiedNamespace()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getFullyQualifiedNamespace()"
name: "getFullyQualifiedNamespace()"
nameWithType: "EventHubProducerClient.getFullyQualifiedNamespace()"
summary: "Gets the fully qualified Event Hubs namespace that the connection is associated with."
syntax: "public String getFullyQualifiedNamespace()"
desc: "Gets the fully qualified Event Hubs namespace that the connection is associated with. This is likely similar to `{yournamespace}.servicebus.windows.net`."
returns:
description: "The fully qualified Event Hubs namespace that the connection is associated with."
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getIdentifier()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getIdentifier()"
name: "getIdentifier()"
nameWithType: "EventHubProducerClient.getIdentifier()"
summary: "Gets the client identifier."
syntax: "public String getIdentifier()"
desc: "Gets the client identifier."
returns:
description: "The unique identifier string for current client."
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getPartitionIds()"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getPartitionIds()"
name: "getPartitionIds()"
nameWithType: "EventHubProducerClient.getPartitionIds()"
summary: "Retrieves the identifiers for the partitions of an Event Hub."
syntax: "public IterableStream<String> getPartitionIds()"
desc: "Retrieves the identifiers for the partitions of an Event Hub."
returns:
description: "A Flux of identifiers for the partitions of an Event Hub."
type: "<xref href=\"com.azure.core.util.IterableStream?alt=com.azure.core.util.IterableStream&text=IterableStream\" data-throw-if-not-resolved=\"False\" />&lt;<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>&gt;"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.getPartitionProperties(java.lang.String)"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.getPartitionProperties(String partitionId)"
name: "getPartitionProperties(String partitionId)"
nameWithType: "EventHubProducerClient.getPartitionProperties(String partitionId)"
summary: "Retrieves information about a specific partition for an Event Hub, including elements that describe the available events in the partition event stream."
parameters:
- description: "The unique identifier of a partition associated with the Event Hub."
name: "partitionId"
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
syntax: "public PartitionProperties getPartitionProperties(String partitionId)"
desc: "Retrieves information about a specific partition for an Event Hub, including elements that describe the available events in the partition event stream."
returns:
description: "The set of information for the requested partition under the Event Hub this client is associated with."
type: "<xref href=\"com.azure.messaging.eventhubs.PartitionProperties?alt=com.azure.messaging.eventhubs.PartitionProperties&text=PartitionProperties\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.send(com.azure.messaging.eventhubs.EventDataBatch)"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.send(EventDataBatch batch)"
name: "send(EventDataBatch batch)"
nameWithType: "EventHubProducerClient.send(EventDataBatch batch)"
summary: "Sends the batch to the associated Event Hub."
parameters:
- description: "The batch to send to the service."
name: "batch"
type: "<xref href=\"com.azure.messaging.eventhubs.EventDataBatch?alt=com.azure.messaging.eventhubs.EventDataBatch&text=EventDataBatch\" data-throw-if-not-resolved=\"False\" />"
syntax: "public void send(EventDataBatch batch)"
desc: "Sends the batch to the associated Event Hub."
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.send(java.lang.Iterable<com.azure.messaging.eventhubs.EventData>)"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.send(Iterable<EventData> events)"
name: "send(Iterable<EventData> events)"
nameWithType: "EventHubProducerClient.send(Iterable<EventData> events)"
summary: "Sends a set of events to the associated Event Hub using a batched approach."
parameters:
- description: "Events to send to the service."
name: "events"
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html\">Iterable</a>&lt;<xref href=\"com.azure.messaging.eventhubs.EventData?alt=com.azure.messaging.eventhubs.EventData&text=EventData\" data-throw-if-not-resolved=\"False\" />&gt;"
syntax: "public void send(Iterable<EventData> events)"
desc: "Sends a set of events to the associated Event Hub using a batched approach. If the size of events exceed the maximum size of a single batch, an exception will be triggered and the send will fail. By default, the message size is the max amount allowed on the link.\n\n```java\nList<EventData> events = Arrays.asList(new EventData(\"maple\"), new EventData(\"aspen\"),\n new EventData(\"oak\"));\n producer.send(events);\n```\n\nFor more information regarding the maximum event size allowed, see [Azure Event Hubs Quotas and Limits][].\n\n\n[Azure Event Hubs Quotas and Limits]: https://docs.microsoft.com/azure/event-hubs/event-hubs-quotas"
- uid: "com.azure.messaging.eventhubs.EventHubProducerClient.send(java.lang.Iterable<com.azure.messaging.eventhubs.EventData>,com.azure.messaging.eventhubs.models.SendOptions)"
fullName: "com.azure.messaging.eventhubs.EventHubProducerClient.send(Iterable<EventData> events, SendOptions options)"
name: "send(Iterable<EventData> events, SendOptions options)"
nameWithType: "EventHubProducerClient.send(Iterable<EventData> events, SendOptions options)"
summary: "Sends a set of events to the associated Event Hub using a batched approach."
parameters:
- description: "Events to send to the service."
name: "events"
type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html\">Iterable</a>&lt;<xref href=\"com.azure.messaging.eventhubs.EventData?alt=com.azure.messaging.eventhubs.EventData&text=EventData\" data-throw-if-not-resolved=\"False\" />&gt;"
- description: "The set of options to consider when sending this batch."
name: "options"
type: "<xref href=\"com.azure.messaging.eventhubs.models.SendOptions?alt=com.azure.messaging.eventhubs.models.SendOptions&text=SendOptions\" data-throw-if-not-resolved=\"False\" />"
syntax: "public void send(Iterable<EventData> events, SendOptions options)"
desc: "Sends a set of events to the associated Event Hub using a batched approach. If the size of events exceed the maximum size of a single batch, an exception will be triggered and the send will fail. By default, the message size is the max amount allowed on the link.\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> events = Arrays.asList(new EventData(\"Melbourne\"), new EventData(\"London\"),\n new EventData(\"New York\"));\n\n SendOptions sendOptions = new SendOptions().setPartitionKey(\"cities\");\n producer.send(events, sendOptions);\n```\n\nFor more information regarding the maximum event size allowed, see [Azure Event Hubs Quotas and Limits][].\n\n\n[Azure Event Hubs Quotas and Limits]: https://docs.microsoft.com/azure/event-hubs/event-hubs-quotas"
type: "class"
desc: "A **synchronous** producer responsible for transmitting <xref uid=\"com.azure.messaging.eventhubs.EventData\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventData\"></xref> to a specific Event Hub, grouped together in batches. Depending on the <xref uid=\"com.azure.messaging.eventhubs.models.CreateBatchOptions\" data-throw-if-not-resolved=\"false\" data-raw-source=\"options\"></xref> specified when creating an <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref>, the events may be automatically routed to an available partition or specific to a partition. More information and specific recommendations for strategies to use when publishing events is in: [ Distribute events to partitions][Distribute events to partitions]\n\nAllowing automatic routing of partitions is recommended when:\n\n * The sending of events needs to be highly available.\n * The event data should be evenly distributed among all available partitions.\n\nIf no partition id is specified, the following rules are used for automatically selecting one:\n\n1. Distribute the events equally amongst all available partitions using a round-robin approach.\n2. If a partition becomes unavailable, the Event Hubs service will automatically detect it and forward the message to another available partition.\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**Sample: Construct a <xref uid=\"com.azure.messaging.eventhubs.EventHubProducerClient\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventHubProducerClient\"></xref>**\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=\"EventHubProducerClient\"></xref>. The `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.\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 EventHubProducerClient producer = new EventHubClientBuilder()\n .credential(\"<<fully-qualified-namespace>>\", \"<<event-hub-name>>\",\n credential)\n .buildProducerClient();\n```\n\n**Sample: Create a producer and publish events to any partition**\n\nThe following code sample demonstrates publishing events and allowing the service to distribute the events round-robin between all partitions.\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: Publish events to partition \"0\"**\n\nThe following code sample demonstrates publishing events to a specific partition. In the scenario below, all events are sent to partition \"0\".\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 // Creating a batch with partitionId set will route all events in that batch to partition `0`.\n CreateBatchOptions options = new CreateBatchOptions().setPartitionId(\"0\");\n EventDataBatch batch = producer.createBatch(options);\n\n // Add events to batch and when you want to send the batch, send it using the producer.\n producer.send(batch);\n```\n\n**Sample: Publish events to the same partition, grouped together using partition key**\n\nThe sample code below uses <xref uid=\"com.azure.messaging.eventhubs.models.CreateBatchOptions.setPartitionKey(java.lang.String)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"CreateBatchOptions#setPartitionKey(String)\"></xref> when creating the <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref>. All events added to this batch will be published to the same partition. In general, events with the same `partitionKey` end up in the same partition.\n\n```java\nList<EventData> events = Arrays.asList(new EventData(\"sourdough\"), new EventData(\"rye\"),\n new EventData(\"wheat\"));\n\n // Creating a batch with partitionKey set will tell the service to hash the partitionKey and decide which\n // partition to send the events to. Events with the same partitionKey are always routed to the same partition.\n CreateBatchOptions options = new CreateBatchOptions().setPartitionKey(\"bread\");\n EventDataBatch batch = producer.createBatch(options);\n\n events.forEach(event -> batch.tryAdd(event));\n producer.send(batch);\n```\n\n**Sample: Publish events using a size-limited <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref>**\n\nThe sample code below uses <xref uid=\"com.azure.messaging.eventhubs.models.CreateBatchOptions.setMaximumSizeInBytes(int)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"CreateBatchOptions#setMaximumSizeInBytes(int)\"></xref> when creating the <xref uid=\"com.azure.messaging.eventhubs.EventDataBatch\" data-throw-if-not-resolved=\"false\" data-raw-source=\"EventDataBatch\"></xref>. In the example, it limits the size of the batch to 256 bytes. This is useful for scenarios where there are constraints like network throughput, memory, etc.\n\n```java\nList<EventData> telemetryEvents = Arrays.asList(firstEvent, secondEvent, thirdEvent);\n\n // Setting `setMaximumSizeInBytes` when creating a batch, limits the size of that batch.\n // In this case, all the batches created with these options are limited to 256 bytes.\n CreateBatchOptions options = new CreateBatchOptions().setMaximumSizeInBytes(256);\n\n EventDataBatch currentBatch = producer.createBatch(options);\n\n // For each telemetry event, we try to add it to the current batch.\n // When the batch is full, send it then create another batch to add more events to.\n for (EventData event : telemetryEvents) {\n if (!currentBatch.tryAdd(event)) {\n producer.send(currentBatch);\n currentBatch = producer.createBatch(options);\n\n // Add the event we couldn't before.\n if (!currentBatch.tryAdd(event)) {\n throw new IllegalArgumentException(\"Event is too large for an empty batch.\");\n }\n }\n }\n```\n\n\n[Distribute events to partitions]: https://learn.microsoft.com/azure/architecture/reference-architectures/event-hubs/partitioning-in-event-hubs-and-kafka#distribute-events-to-partitions\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"
implements:
- "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/io/Closeable.html\">Closeable</a>"
metadata: {}
package: "com.azure.messaging.eventhubs"
artifact: com.azure:azure-messaging-eventhubs:5.18.7