Connecting to AMQP Services¶
Welcome to this tutorial on using the SWIM service from DWD! In this guide, we will walk you through setting up a connection and consuming messages. By the end of this tutorial, you will be able to access the service and start receiving messages using Python and the Apache Qpid Proton library.
This tutorial tries to describe everything in the abstract concept of services and subscriptions, without going into the details of the implementation. However, as queues are actually created on a technical level you might want to refer to the Semantics of Subscriptions vs. Queues document for more details on their relationship.
Prerequisites¶
Before starting, ensure you meet the following requirements:
- A basic understanding of the AMQP 1.0 protocol.
- Registration for the SWIM service at DWD. If you are not registered, please contact vl.kundenservice@dwd.de.
Step 1: Requesting a Subscription¶
You don't need a specific subscription for the services offered by DWD. Simply connect to one of the addresses of the services listed in the List of Services. You will only receive messages published after you created your AMQP receiver. Hence, if you disconnect from the service and reconnect later, you will only receive messages published after your reconnection.
However, if you need a dedicated subscription keeping track of your specific messages there exists the option of creating a custom subscription. If you want to receive messages from before you created your receiver you can use offset tracking to retrieve past messages.
Step 2: Receiving Your First Message¶
We will guide you through consuming your first message using Python. Although this example is Python-specific, the concepts apply to other AMQP 1.0 compatible libraries.
Setting Up Your Environment¶
Please refer to the official docs to setup python. We recommend setting up a virtual environment for this example, too.
For this tutorial we only need the qpid-proton library, which we install with
Note: While version
0.40.0was used for this tutorial, newer versions will likely work as well. We just pin it here to ensure compatibility. Feel free to try out newer versions!
Connecting to the Broker¶
Replace the placeholders with your connection details:
from proton import ProtonException
from proton.utils import BlockingConnection
conn = BlockingConnection(
"amqps://swimt.dwd.de",
user="swim_user",
password="your_password"
)
Creating a Receiver and Fetching Messages¶
You will connect a receiver to the de-dwd.ops.heartbeat queue to receive heartbeat messages.
The systems sends a heartbeat every 60 seconds so we don't have to wait long for our first message.
Note: The
/queues/prefix is required when talking to RabbitMQ. It cleanly separates names in different endpoints, e.g., from anexchangeof the same name.
To actually receive a message we need to call the receive method on the receiver.
We use a timeout of 70 seconds to ensure we receive at least one heartbeat message.
The receive call will block until a message is received or the timeout is reached.
Displaying the Message Content¶
Now that we have received a message, let's display its content.
The body of the message contains the actual payload.
We do a type check to ensure we handle the body correctly.
Please be aware that the body can contain different types of data depending on the service and message type.
Here, we expect a binary encoded JSON payload.
Qpid proton represents this as a memoryview, so we need to convert it to bytes before decoding it.
import json
if isinstance(msg.body, memoryview):
print(json.loads(msg.body.tobytes().decode("utf-8")))
For the heartbeat message, you should see output similar to this template:
Additionally, you can inspect the application properties to see metadata about the message.
Qpid proton uses the properties attribute for this purpose.
Which will generate output similar to:
Optional: Acknowledging the Message¶
To acknowledge that the message has been successfully processed and to remove it from the queue, use the following command:
Closing the Connection¶
After processing, close the connection to the broker:
Congratulations!¶
You have successfully received your first SWIM message!
Next Steps¶
- Receive past messages using offset tracking.
- Refer to the consumer loop script for a starter script to continuously consume messages.
For further assistance, contact swim.service@dwd.de.