asyncapi: 2.6.0 info: title: Azure Event Hubs Messaging API version: 1.0.0 description: >- Azure Event Hubs is a big data streaming platform and event ingestion service that can receive and process millions of events per second. This AsyncAPI specification describes the event-driven messaging capabilities of Azure Event Hubs, including publishing events to event hubs and consuming events from partitions via consumer groups. Event Hubs supports AMQP 1.0, Kafka, and HTTPS protocols for both producing and consuming events. Events are organized into partitions for parallel processing, and consumer groups provide independent views of the event stream. contact: name: Microsoft Azure Support url: https://azure.microsoft.com/en-us/support/ license: name: Microsoft Azure Terms of Service url: https://azure.microsoft.com/en-us/support/legal/ x-logo: url: https://azure.microsoft.com/svghandler/event-hubs/ servers: amqp: url: '{namespaceName}.servicebus.windows.net' protocol: amqp protocolVersion: '1.0' description: >- Azure Event Hubs AMQP 1.0 endpoint. AMQP is the primary protocol for high-throughput event streaming. Connections use TLS on port 5671. variables: namespaceName: description: The Event Hubs namespace name. default: my-namespace security: - sasToken: [] - azureAd: [] kafka: url: '{namespaceName}.servicebus.windows.net:9093' protocol: kafka protocolVersion: '2.0' description: >- Azure Event Hubs Kafka endpoint. Event Hubs provides a Kafka-compatible endpoint that allows existing Kafka applications to connect without code changes. Requires SASL/PLAIN authentication over TLS. variables: namespaceName: description: The Event Hubs namespace name. default: my-namespace security: - kafkaSasl: [] https: url: '{namespaceName}.servicebus.windows.net' protocol: https description: >- Azure Event Hubs HTTPS endpoint for sending events via REST API. This endpoint supports sending single events, batch events, and partition-targeted events. variables: namespaceName: description: The Event Hubs namespace name. default: my-namespace security: - sasToken: [] - azureAd: [] defaultContentType: application/json channels: '{eventHubName}': description: >- An event hub channel for publishing and subscribing to events. Events sent to this channel are distributed across partitions based on the partition key or round-robin if no partition key is specified. Each event hub can have up to 32 partitions (configurable at creation time) and supports multiple consumer groups for independent consumption. parameters: eventHubName: description: >- The name of the event hub. Event hub names must be between 1 and 256 characters long. schema: type: string minLength: 1 maxLength: 256 publish: operationId: publishEvent summary: Publish event to event hub description: >- Publishes an event to the specified event hub. The event is distributed to a partition based on the partition key if provided, or using round-robin distribution. Events are appended to the event stream and assigned a sequence number and offset within the partition. tags: - name: Event Publishing bindings: amqp: is: queue exchange: type: topic vhost: / bindingVersion: 0.3.0 kafka: groupId: type: string bindingVersion: 0.5.0 http: type: request method: POST bindingVersion: 0.3.0 message: oneOf: - $ref: '#/components/messages/EventMessage' - $ref: '#/components/messages/BatchEventMessage' subscribe: operationId: consumeEvent summary: Consume events from event hub description: >- Consumes events from the specified event hub. Events are read from partitions via consumer groups. Each consumer group maintains its own offset position in each partition. The default consumer group $Default is created automatically. Consumers can read from a specific offset, from the beginning, or from the latest event. tags: - name: Event Consumption bindings: amqp: is: queue exchange: type: topic vhost: / bindingVersion: 0.3.0 kafka: groupId: type: string bindingVersion: 0.5.0 message: $ref: '#/components/messages/ReceivedEventMessage' '{eventHubName}/partitions/{partitionId}': description: >- A partition-specific channel for publishing events to a specific partition of an event hub. Using partition-targeted publishing gives you direct control over which partition receives the event but bypasses the load balancing that Event Hubs provides. parameters: eventHubName: description: The name of the event hub. schema: type: string minLength: 1 maxLength: 256 partitionId: description: >- The partition identifier. Partition IDs are zero-based integers (e.g., 0, 1, 2, ..., N-1 where N is the partition count). schema: type: string publish: operationId: publishPartitionEvent summary: Publish event to specific partition description: >- Publishes an event directly to a specific partition of the event hub. This is useful when you need deterministic partition placement but should be used carefully as it bypasses partition load balancing. tags: - name: Event Publishing message: $ref: '#/components/messages/EventMessage' subscribe: operationId: consumePartitionEvent summary: Consume events from specific partition description: >- Consumes events from a specific partition of the event hub. The consumer can specify the starting position using an offset, sequence number, or enqueued time. This is the lowest-level consumption model and is typically wrapped by higher-level abstractions like the Event Processor. tags: - name: Event Consumption message: $ref: '#/components/messages/ReceivedEventMessage' '{eventHubName}/publishers/{publisherId}': description: >- A publisher-specific channel for sending events with a publisher identity. Publisher policies enable you to track which publisher sent each event and to revoke publishing access for misbehaving publishers. parameters: eventHubName: description: The name of the event hub. schema: type: string minLength: 1 maxLength: 256 publisherId: description: >- The publisher identifier. This is a unique string that identifies the event source, often a device ID or application instance ID. schema: type: string publish: operationId: publishEventWithPublisherId summary: Publish event with publisher identity description: >- Publishes an event to the event hub with a specified publisher identity. This enables per-publisher access control and tracking through publisher policies. tags: - name: Event Publishing message: $ref: '#/components/messages/EventMessage' components: messages: EventMessage: name: EventMessage title: Event Hub Event summary: An event published to Azure Event Hubs. description: >- Represents an event that is sent to an Azure Event Hub. The event body can contain any data format (JSON, Avro, binary, text). Events can include custom user properties as metadata and broker properties such as partition key for routing. contentType: application/json headers: type: object properties: Authorization: type: string description: >- SAS token or Azure AD bearer token for authentication. Content-Type: type: string description: The content type of the event body. default: application/json x-ms-retrypolicy: type: string description: Set to NoRetry to disable automatic retry. enum: - NoRetry additionalProperties: type: string description: >- Custom user properties as additional headers. These are key-value pairs attached to the event as metadata. payload: $ref: '#/components/schemas/EventData' traits: - $ref: '#/components/messageTraits/CommonEventProperties' BatchEventMessage: name: BatchEventMessage title: Batch Event Hub Events summary: A batch of events published to Azure Event Hubs. description: >- Represents a batch of events sent to an Azure Event Hub in a single request. Batching reduces network overhead by combining multiple events into one transmission. Each event in the batch can have its own user properties. contentType: application/vnd.microsoft.servicebus.json payload: $ref: '#/components/schemas/BatchEventData' traits: - $ref: '#/components/messageTraits/CommonEventProperties' ReceivedEventMessage: name: ReceivedEventMessage title: Received Event Hub Event summary: An event received from Azure Event Hubs. description: >- Represents an event consumed from an Azure Event Hub partition. In addition to the event body and user properties, received events include system properties such as the sequence number, offset, and enqueued timestamp assigned by the Event Hubs service. contentType: application/json payload: $ref: '#/components/schemas/ReceivedEventData' traits: - $ref: '#/components/messageTraits/CommonEventProperties' schemas: EventData: type: object description: >- The event data payload sent to Azure Event Hubs. The body can contain any serialized data. properties: body: description: >- The body of the event. Can be any valid data format including JSON objects, strings, or binary data. oneOf: - type: object additionalProperties: true - type: string - type: array items: {} properties: type: object additionalProperties: type: string description: >- Application-defined properties associated with the event. These are custom key-value pairs that serve as metadata. systemProperties: type: object description: System-assigned properties for the event. properties: partitionKey: type: string description: >- The partition key used to route the event to a specific partition. Events with the same partition key are guaranteed to be sent to the same partition. messageId: type: string description: >- A unique identifier for the message set by the producer. correlationId: type: string description: >- A correlation identifier for relating events. contentType: type: string description: >- The content type of the event body, such as application/json. BatchEventData: type: array description: >- An array of event messages for batch transmission. Each item represents a single event within the batch. items: type: object required: - Body properties: Body: description: The body content of the event message. oneOf: - type: string - type: object additionalProperties: true UserProperties: type: object additionalProperties: type: string description: >- Custom user properties for this specific event in the batch. BrokerProperties: type: object properties: PartitionKey: type: string description: Partition key for routing. MessageId: type: string description: Message identifier. CorrelationId: type: string description: Correlation identifier. ReceivedEventData: type: object description: >- The event data received from an Azure Event Hub partition. Includes the original event body, user properties, and system-assigned properties. properties: body: description: The body of the received event. oneOf: - type: object additionalProperties: true - type: string - type: array items: {} properties: type: object additionalProperties: type: string description: Application-defined properties from the event producer. systemProperties: type: object description: >- System properties assigned by the Event Hubs service when the event was enqueued. properties: sequenceNumber: type: integer format: int64 description: >- The logical sequence number of the event within the partition stream. This is a monotonically increasing number assigned when the event is accepted. offset: type: string description: >- The offset of the event within the partition. This is a string representation of the byte offset in the partition log. It can be used to seek to a specific position. enqueuedTimeUtc: type: string format: date-time description: >- The UTC timestamp when the event was accepted and stored in the partition. partitionKey: type: string description: >- The partition key used by the producer when sending the event. x-opt-sequence-number: type: integer format: int64 description: >- AMQP annotation for the sequence number. x-opt-offset: type: string description: >- AMQP annotation for the offset. x-opt-enqueued-time: type: string format: date-time description: >- AMQP annotation for the enqueued time. messageTraits: CommonEventProperties: headers: type: object properties: x-opt-partition-key: type: string description: >- The partition key for the event. Events with the same partition key are sent to the same partition. x-opt-sequence-number: type: integer format: int64 description: The sequence number assigned by Event Hubs. x-opt-offset: type: string description: The offset of the event within the partition. x-opt-enqueued-time: type: string format: date-time description: The time the event was enqueued in the partition. securitySchemes: sasToken: type: httpApiKey name: Authorization in: header description: >- Shared Access Signature (SAS) token for authentication. Format: SharedAccessSignature sr={namespace}.servicebus.windows.net&sig={signature}&se={expiry}&skn={keyName} azureAd: type: http scheme: bearer bearerFormat: JWT description: >- Azure Active Directory (Azure AD) bearer token (JWT) for authentication. The token must be issued for the Event Hubs resource. kafkaSasl: type: plain description: >- Kafka SASL/PLAIN authentication using the Event Hubs connection string. The username is $ConnectionString and the password is the Event Hubs connection string. tags: - name: Event Publishing description: >- Operations for publishing events to Azure Event Hubs, including single events, batch events, and partition-targeted events. - name: Event Consumption description: >- Operations for consuming events from Azure Event Hubs partitions through consumer groups with configurable offset tracking.