Quickstart: Send and Receive Events with Azure Event Hubs

This quickstart guide will walk you through the process of sending and receiving events using Azure Event Hubs. Azure Event Hubs is a highly scalable data streaming platform and event ingestion service, capable of receiving and processing millions of events per second.

Prerequisites

Before you begin, ensure you have the following:

An Azure subscription. If you don't have one, create a free account.
An Azure Event Hubs namespace and an Event Hub within that namespace. You can create these using the Azure portal, Azure CLI, or Azure PowerShell.
The connection string for your Event Hub. You can find this in the Azure portal under your Event Hub's "Shared access policies".
A development environment set up for your chosen language (e.g., Python, C#, Java, Node.js).

Step 1: Set up your Project

For this example, we'll use Python. Ensure you have Python installed. Then, install the necessary Azure Event Hubs client library:

pip install azure-eventhubs

Step 2: Create an Event Sender

Create a Python script (e.g., send_events.py) to send events to your Event Hub. Replace the placeholder values with your actual connection string and hub name.

import os
import asyncio
from azure.eventhub.aio import EventHubProducerClient

EVENT_HUB_CONNECTION_STR = "YOUR_EVENT_HUB_CONNECTION_STRING" # Replace with your connection string
EVENT_HUB_NAME = "YOUR_EVENT_HUB_NAME" # Replace with your Event Hub name

async def run():
    # If the EH_CONNECTION_STR environment variable is not set,
    # use the default EH_CONNECTION_STR value.
    conn_str = os.environ.get('EVENT_HUB_CONNECTION_STR', EVENT_HUB_CONNECTION_STR)
    eh_name = os.environ.get('EVENT_HUB_NAME', EVENT_HUB_NAME)

    # Create a producer client to send events to the Event Hub.
    producer = EventHubProducerClient.from_connection_string(conn_str, event_hub_name=eh_name)

    async with producer:
        # Prepare events.
        events_batch = await producer.create_batch()
        for i in range(10):
            events_batch.add_event(f"Event {i}")

        # Send the events.
        await producer.send_batch(events_batch)
        print("Sent 10 events.")

if __name__ == "__main__":
    asyncio.run(run())

Tip: It's recommended to store sensitive information like connection strings in environment variables rather than hardcoding them directly into your scripts.

Step 3: Create an Event Receiver

Create another Python script (e.g., receive_events.py) to receive events from your Event Hub. This script will continuously listen for new events.

import os
import asyncio
from azure.eventhub.aio import EventHubConsumerClient

EVENT_HUB_CONNECTION_STR = "YOUR_EVENT_HUB_CONNECTION_STRING" # Replace with your connection string
EVENT_HUB_NAME = "YOUR_EVENT_HUB_NAME" # Replace with your Event Hub name
CONSUMER_GROUP_NAME = "$Default" # Or your custom consumer group

async def run():
    conn_str = os.environ.get('EVENT_HUB_CONNECTION_STR', EVENT_HUB_CONNECTION_STR)
    eh_name = os.environ.get('EVENT_HUB_NAME', EVENT_HUB_NAME)

    # Create a consumer client to receive events from the Event Hub.
    # Specify the consumer group you want to use.
    consumer = EventHubConsumerClient.from_connection_string(
        conn_str,
        consumer_group=CONSUMER_GROUP_NAME,
        event_hub_name=eh_name
    )

    async def on_event(partition_context, event):
        print(f"Received event: {event.body_as_str()}")
        # Acknowledge the event by completing the partition context.
        await partition_context.update_checkpoint(event)

    async with consumer:
        await consumer.receive(on_event=on_event, starting_position="-1") # Start receiving from the earliest event

if __name__ == "__main__":
    asyncio.run(run())

Note: The starting_position="-1" tells the consumer to start reading from the beginning of the event stream if no checkpoint is found. For production scenarios, managing checkpoints properly is crucial to ensure no events are missed or processed multiple times.

Step 4: Run the Scripts

Open two terminal windows or command prompts. In the first, run the sender script:

python send_events.py

In the second terminal, run the receiver script:

python receive_events.py

You should see the "Sent 10 events." message in the sender's terminal, and the receiver's terminal will print each received event.

Step 5: Clean Up

Once you're done, remember to clean up your Azure resources to avoid incurring unnecessary costs. This typically involves deleting the Event Hubs namespace and any associated resources.

Warning: Deleting an Event Hubs namespace is irreversible and will delete all its associated Event Hubs and data.

Next Steps

Congratulations! You've successfully sent and received events using Azure Event Hubs. Here are some resources for further exploration: