Skip to content

IoTHub

formatting...

Communicate with an Azure IoT hub as an IoT device.

Warning

Due to how Azure IoT hub devices works, you can only run one instance of this user if you rely on cloud-to-device (C2D) messages. Carefully chose to handle task errors so you do not end up with a scenario that will cause the whole feature to fail since the IotHubUser stopped.

Request methods

Supports the following request methods:

  • send
  • put
  • get
  • receive

Metadata

The following properties is added to the metadata part of a message.

Name Type
custom_properties dict
message_id str
expiry_time_utc str
correlation_id str
user_id str
content_type str
output_name str
input_name str
ack bool
iothub_interface_id str
size int

Sending

This user has support for sending IoT messages and uploading files. For device-to-cloud (D2C) messages, endpoint in the request must be device-to-cloud, otherwise it will try to upload the request as a file. See device-to-cloud communication guidance for the difference.

Receiving

Receiving cloud-to-device (C2D) messages is a little bit special, the endpoint in the in the request must be cloud-to-device.

There are 3 other context variables that will control wether a message will be pushed to the internal queue or not:

  • expression.unique (str), this is a JSON-path expression will extract a value from the message payload, push the whole message to the internal queue and save the value in a "volatile list", if a message with the same value is received within 20 seconds, it will not be handled. This is to avoid handling duplicates of messages, which can occur for different reasons ("at least once" design pattern). E.g. $.body.event.id.

  • expression.metadata (bool), this a JSON-path expression that should validate to a boolean expression, messages for which this expression does not validate to True will be dropped and not pushed to the internal queue. E.g. $.size>=1024.

  • expression.payload (bool), same as expression.metadata except it will validate against the actual message payload. E.g. $.body.timestamp>='2024-09-23 20:39:00, which will drop all messages having a timestamp before the specified date.

Pipe arguments

See Request task endpoint format for standard pipe arguments, in additional to those the following are also supported:

  • wait (int), number of seconds to wait for a available message before failing request. If not specified it will wait indefinitely.

Format

Format of host is the following:

HostName=<hostname>;DeviceId=<device key>;SharedAccessKey=<access key>

The metadata values content_type and content_encoding can be set to gzip compress the payload before upload (see example below).

Examples

Example of how to use it in a scenario:

Given a user of type "IotHub" load testing "HostName=my_iot_host_name;DeviceId=my_device;SharedAccessKey=xxxyyyyzzz=="
Then send request "test/blob.file" to endpoint "uploaded_blob_filename"

The same example with gzip compression enabled:

Given a user of type "IotHub" load testing "HostName=my_iot_host_name;DeviceId=my_device;SharedAccessKey=xxxyyyyzzz=="
And metadata "content_encoding" is "gzip"
Then send request "test/blob.file" to endpoint "uploaded_blob_filename | content_type=octet_stream_utf8"

Example of how to receive unique messages from a thermometer of type temperature (considered that the application sets a custom property message_type) 

Given a user of type "IotHub" load testing "HostName=my_iot_host_name;DeviceId=my_device;SharedAccessKey=xxxyyyyzzz=="
And set context variable "expression.unique" to "$.device.name=='thermometer01'"
And set context variable "expression.metadata" to "$.custom_properties.message_type=='temperature'"
And value for variable "temperature" is "none"

Then receive request with name "iot-get-temperature" from endpoint "cloud-to-device | content_type=json, wait=180"
Then save response payload "$.device.temperature" in variable "temperature"