メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Publishing to Sync Objects

Sync for IoT is currently in Developer Preview, which means access is by invite only. If you'd like to try what you see in these docs, sign up for the developer preview and the team at Twilio will get you onboarded.

Any device that can run an MQTT client can publish data to Sync. This happens by delivering simple MQTT messages to well-named topics, and assigning the appropriate QoS level. This works for all Sync object types and their sub-resources.

Documents

The topic mapping pattern is sync/docs/{DocumentId}, where DocumentId is a Sync document unique name or SID. Publishing to such topic name results in an update of the document state, overwriting its previous state.

The table below provides examples of publishing to MQTT topics projected to Sync Document objects.

MQTT Topic Sync URL 動作

sync/docs/myDoc

https://sync.twilio.com
/v1/Services/ISxx/Documents/myDoc

When an MQTT message is published, Sync updates (i.e. overwrites) the contents of the indicated document.

If no such document exists, Sync creates one with the given unique name.

sync/docs/ETxx

https://sync.twilio.com
/v1/Services/ISxx/Documents/ETxx

When an MQTT message is published, Sync updates (i.e. overwrites) the contents of the indicated document.

If no such document exists, publication will fail.

Lists

The topic mapping pattern is sync/lists/{ListId}, where ListId is a Sync list collection unique name or SID. Publishing to such topic name results in a new item pushed (appended) to the list collection.

In addition to list "push" semantics, there is also an option to publish updates to individual list items, with mapping pattern sync/lists/{ListId}/{ItemIndex}. Publishing to such topic name results in the update of an existing item in the collection with the given ItemIndex.

The table below provides examples of publishing to MQTT topics projected to Sync List collections.

MQTT Topic Sync URL 動作

sync/lists/myList

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList

When an MQTT message is published, Sync appends a new item to the indicated list.

If no such list exists, publishing creates one with the given unique name.

sync/lists/ESxx

https://sync.twilio.com
/v1/Services/ISxx/Lists/ESxx

When an MQTT message is published, Sync appends a new item to the indicated list.

If no such list exists, publication will fail.

sync/lists/myList/42

https://sync.twilio.com
/v1/Services/ISxx/Lists/myList
/Items/42

When an MQTT message is published, Sync updates (i.e. overwrites) the list item with index 42 within the indicated list.

If no such list exists, or if that list does not have such an item, publication will fail.

sync/lists/ESxx/42

https://sync.twilio.com
/v1/Services/ISxx/Lists/ESxx
/Items/42

When an MQTT message is published, Sync updates (i.e. overwrites) the list item with index 42 within the indicated list.

If no such list exists, or if that list has no such item, publication will fail.

Maps

The topic mapping pattern is sync/maps/{MapId}, where MapId is a unique name or SID of a Sync map collection. Publishing to such topic name results in a new item inserted into the map, with randomly generated key.

In addition to map "insert" semantics, there is also an option to publish and subscribe to individual map items, with mapping pattern being sync/maps/{MapId}/{ItemKey}. Publishing to such topic name results in the update of an existing item in the collection with the given ItemKey.

The table below provides examples of publishing to MQTT topics projected to Sync Map collections.

MQTT Topic Sync URL 動作

sync/maps/myMap

https://sync.twilio.com
/v1/Services/ISxx/Maps/myMap

When an MQTT message is published, Sync inserts a new item into the indicated map. The assigned key of the created item is a random UUID.

If no such map exists, one will be created with the given unique name.

sync/maps/MPxx

https://sync.twilio.com
/v1/Services/ISxx/Maps/MPxx

When an MQTT message is published, Sync appends a new item to the indicated map. The assigned key of the created item is a random UUID.

If no such map exists, publication will fail.

sync/maps/myMap/myKey

https://sync.twilio.com
/v1/Services/ISxx/Maps/myMap
/Items/myKey

When an MQTT message is published, Sync updates (i.e. overwrites) the keyed map item with the message content.

If no such map exists, or if that map has no item myKey, either the item or the map and item both will be created.

sync/maps/MPxx/myKey

https://sync.twilio.com
/v1/Services/ISxx/Maps/MPxx
/Items/myKey

When an MQTT message is published, Sync updates (i.e. overwrites) the keyed map item.

If no such map exists, or if that map has no item myKey, either or both will be created.

Message Streams

The topic mapping pattern is sync/streams/{StreamId}, where StreamId is a Sync Message Stream unique name or SID. Publishing to such topic name results in a new message sent to the stream and delivered to all its subscribers.

The table below provides examples of publishing to MQTT topics projected to Sync Message Stream objects.

MQTT Topic Sync URL 動作

sync/streams/myStream

https://sync.twilio.com
/v1/Services/ISxx/Streams/myStream

When an MQTT message is published, Sync delivers a new message to all subscribers of this stream.

If no such message stream exists, Sync creates one with the given unique name.

sync/streams/TOxx

https://sync.twilio.com
/v1/Services/ISxx/Streams/TOxx

When an MQTT message is published, Sync delivers a new message to all subscribers of this stream.

If no such message stream exists, publication will fail.

Supported Payloads

MQTT Gateway supports two payload types published by connected clients to Sync for all objects listed above.

  • JSON objects
  • Binary data

JSON objects are represented by strings included in MQTT PUBLISH message payload, containing correctly encoded JSON in UTF-8 format. In case MQTT Gateway is unable to parse the published payload as valid JSON, it interprets it as an opaque binary data blob.

As Sync uses JSON as its primary storage medium, binary data published by devices is wrapped into an envelope. The envelope is a JSON object that includes the following fields:

  • payload: Base64 encoded binary data published by the device
  • _iot_meta.payload_type: Specifies the payload type which is "application/octet-stream"
  • _iot_meta.payload_encoding: Specifies the payload encoding which is "base64"

For example, a device publishes 4 bytes of binary data [ AA BB CC DD ] to topic sync/docs/input. As a result, the document with unique name "input" shall contain the following JSON object:

{
"payload": "qrvM3Q==",
"_iot_meta": {
"payload_type": "application/octet-stream",
"payload_encoding": "base64"
}
}

Note: _iot_meta is a reserved system key at the root level of Sync JSON payload. Your application may not use it, as it will be filtered out by the MQTT Gateway.

Caveats

The MQTT specification specifies a QoS setting for each delivered message. Since this is a foreign concept to Sync, particularly on publishing, this has little effect on the outcome except for at a protocol level with the publisher. We have assigned the following semantics to each QoS level.

  • In case QoS 0 is specified by the publisher, MQTT gateway shall handle the message asynchronously with best effort. PUBACK is not delivered back to the publisher.
  • In case QoS 1 is specified by the publisher, MQTT gateway shall handle the message synchronously, and when the processing is completed successfully, a matching PUBACK confirmation message is going to be sent back to the publisher.
  • The case of QoS 2 is not supported, and the connection shall be closed immediately by MQTT gateway.

Retained message selection flag is not supported in Developer Preview phase. Instead, current behavior assumes that all document, list item and map item publications are retained. Therefore, subscribing to corresponding topics emits their latest known-good state back to subscribers. Please refer to the Subscribing to Sync Service section for more details.

Today, MQTT endpoints can publish to 4 destinations within Twilio Sync service: Documents, Message Streams, Lists and Maps objects and their sub-items.

Rate this page:

ヘルプが必要ですか?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.