Skip to content

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:


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

pip install python-qpid-proton==0.40.0

Note: While version 0.40.0 was 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.

receiver = conn.create_receiver(
    "/queues/de-dwd.ops.heartbeat"
)

Note: The /queues/ prefix is required when talking to RabbitMQ. It cleanly separates names in different endpoints, e.g., from an exchange of 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.

msg = receiver.receive(timeout=70)

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:

{
    "technical_message_type": "heartbeat", 
    "timestamp": "YYYY-MM-DDTHH:MM:SS.ssssss"
}

Additionally, you can inspect the application properties to see metadata about the message. Qpid proton uses the properties attribute for this purpose.

print(msg.properties)

Which will generate output similar to:

{
    "properties.message-type": "technical",
    "properties.technical-message-type": "heartbeat"
}

Optional: Acknowledging the Message

To acknowledge that the message has been successfully processed and to remove it from the queue, use the following command:

receiver.accept()

Closing the Connection

After processing, close the connection to the broker:

conn.close()

Congratulations!

You have successfully received your first SWIM message!

Next Steps

For further assistance, contact swim.service@dwd.de.