# Compression
Device API V2 supports compression of messages. Compression per message is
controlled by the content-encoding property. The following messages support
compression:
- Device-To-Cloud (D2C) mesages (actions)
- Cloud-To-Device (C2D) messages:
- request-response notifications
- acknowledgements
Regarding the message structure, the following applies:
- Headers are not compressed;
- Body is compressed.
# Examples
# Message without compression
By default, messages are not compressed. Such behaviour is achieved with
content-encoding set to "utf8". Since this is the default setting, the
content-encoding property does not need to be provided in the message.
Message Properties:
|-------------------------------|----------------------------------------|
| Key | Value |
|-------------------------------|----------------------------------------|
| "iothub-connection-device-id" | "0d4e1778-ff46-4880-b540-0124141b32da" |
| "msgType" | "action" |
| "action" | "model.create" |
| "version" | 2 |
| "correlationId" | "5e9d709b-440d-4296-8902-b81bfae3dd3b" |
| "objectId" | "0d4e1778-ff46-4880-b540-0124141b32da" |
| "model" | "abb.ability.device.test@1" |
| "ack" | "all" |
|-------------------------------|----------------------------------------|
Message Body:
{
"objectId": "0d4e1778-ff46-4880-b540-0124141b32da",
"model": "abb.ability.device",
"type": "abb.ability.device.test@1",
"properties": {
"serialNumber": {
"value": "200615125813-000024"
}
}
}
# Message with compression
If you intend to send a compressed message, you need to set the
content-encoding property with one of the following values:
- gzip
- deflate
Here's an example of a message that uses gzip as its content-encoding:
Message Properties:
|-------------------------------|----------------------------------------|
| Key | Value |
|-------------------------------|----------------------------------------|
| "iothub-connection-device-id" | "0d4e1778-ff46-4880-b540-0124141b32da" |
| "msgType" | "action" |
| "action" | "model.create" |
| "version" | 2 |
| "correlationId" | "5e9d709b-440d-4296-8902-b81bfae3dd3b" |
| "objectId" | "0d4e1778-ff46-4880-b540-0124141b32da" |
| "model" | "abb.ability.device.test@1" |
| "ack" | "all" |
| "target" | "" |
| "content-encoding" | "gzip" |
|-------------------------------|----------------------------------------|
Message Body:
H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA==
TIP
You can verify that the message above contains the same data as in the example
without compression, by running the following command (assuming base64 and
gzip programs are available in your PATH):
echo "H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA==" | base64 -d | gzip -d
You should see an uncompressed JSON.
# Returned Messages
The Cloud-To-Device messages ('request-response' notifications and
acknowledgments) will be compressed using same method as the one specified in
the request. Header properties content-type and content-encoding will be
also added to each compressed C2D message (if present and non-default in the
request). It is the responsibility of the device implementation to decompress
these messages.
If decompression of the request message fails, unsuccessful acknowledgement will be sent back with an error code "decompression_error" and details "Request message cannot be decompressed by Ability Platform".
# Examples
# Example of Compressed 'request-response' Notification
Message Properties:
|-------------------------------|----------------------------------------|
| Key | Value |
|-------------------------------|----------------------------------------|
| "msgType" | "platformEvent" |
| "eventType" | "Abb.Ability.ObjectModel.Updated" |
| "version" | 2 |
| "correlationId" | "5e9d709b-440d-4296-8902-b81bfae3dd34" |
| "objectId" | "0d4e1778-ff46-4880-b540-0124141b32db" |
| "model" | "abb.ability.device.test@1" |
| "target" | "" |
| "content-encoding" | "gzip" |
|-------------------------------|----------------------------------------|
Message Body (compressed format):
H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA==
# Example of Compressed Acknowledgement
Message Properties:
|-------------------------------|----------------------------------------|
| Key | Value |
|-------------------------------|----------------------------------------|
| "msgType" | "ack" |
| "action" | "model.query" |
| "version" | 2 |
| "correlationId" | "5e9d709b-440d-4296-8902-b81bfae3dd37" |
| "target" | "" |
| "content-encoding" | "gzip" |
|-------------------------------|----------------------------------------|
Message Body (compressed format):
H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA==
# Summary
Compression is quite useful when your device is constrained regarding the Internet communication. Sending less bytes is certainly a good thing in such case. Additionally, using compression you wil be able to "pack" more actions into a batch, if you require to do so.