Connecting Business Central to Azure Service Bus with REST API Part 2

This blog post is a continuation to my previous post "Connecting Business Central to Azure Service Bus with REST API". I recommend reading the first post first.

Reading messages from the Service Bus queue.

There are two ways to read a message from a queue, a destructive read and a non-destructive read. A destructive read is effectively a read+delete and non-destructive read is a read, where the message gets locked for a period of time but will be available for a read after the locking period has expired. The length of the locking period can be found in the queue properties in the Azure Portal. The simplest case is reading the first available message from the queue. The location of the first available message is "/messages/head"

The http verb is POST, but the resource Uri ending with messages/head will give you the first available message. The message payload is returned in the content of the response and the other information of the message is in the response header. 

If you wish to also delete the message (destructive read), just change verb POST to a DELETE an you effectively pop the first message from the queue. 

Response header

When you read a message from the message queue the API returns a collection of properties, called Broker Properties. These properties include the MessageID and Lock Token of the message, which can be used to identify the message in the queue. It also tells you when the lock, which you just created by reading the message, will expire. This is all very useful information.

Broker Properties are in a JSON array. You can read individual values by creating an array of text and reading the header value "BrokerProperties" into the array.

Then it is pretty easy to initialize JSON object from the array using Codeunit 5459 JSON Management and get the values by property name as in the example above.

Where would you use broker Properties? Imagine you're designing an integration, where you need to either know the message content before you know what to do with it, or, say you need to get the messages in certain order, then it is extremely handy if you can read a message and then either process it or move forward to another message.

Unlocking a read message

The message read from the queue will be locked for a period of time after it was read from the queue. If you wish to re-read it while its still locked, the message needs to be unlocked. The Broker Properties returns the expiry date and time of the message in a LockedUntilUtc variable. There's no need to know what the Lock Duration of the queue is as you can easily check if the lock is still on. The value of LockedUntilUtc is in this example in RFC2616 UTC format. To convert to Business Central datetime, there is an external  function in codeunit 10 Type Helper that does exactly that.

If you need to access the message while its locked, you need to unlock the message before you can read it again. To unlock the message, you need to call a PUT with a messageID and a LockToken.

Unlocking a message makes it available to read immediately.

Controlled delete

A message can be deleted from the queue without unlocking it first as long as you know the MessageID and the Lock Token of the message. 

Binary Payload

Sending or receiving a binary payload differs from earlier examples only by how the payload is inserted or retrieved from the message body. I use a temporary table called tempBlob to handle the blob value.

To send a BLOB content:

To receive a BLOB content:

So the only trick needed is to convert the BLOB to/from Base64String, which implemented in the tempblob table itself, and that's it.

Thank You for reading.

Tero