Date formats
平台允许 some flexibility in the use of date/time fields in the HTTP and MQTT APIs. Fields are always of type string, but the content can be specified 使用 formats described 此处. 本节 also describes characteristics related to UTC handling, time zone conversion, and other details.
Separators
Date separator
The characters "/" and "-" are accepted interchangeably as date separators.
Time separator
The time separator must always be ":".
Date and time separator
Optionally, a "T" character can be used to separate the date and time. The following two dates, for example, are equivalent:
2020-02-25 14:35:18
2020-02-25T14:35:18Formats
Date formats (without time)
The platform supports the following formats for specifying a date.
| Format | 说明 |
|---|---|
| yyyy/M/d | Specifies the 4-digit year, followed by month and day, without using zeros to pad month and day. The date separator can be any of the supported ones. |
| yyyy/MM/dd | Specifies the 4-digit year, followed by month and day, using zeros to pad month and day. The date separator can be any of the supported ones. |
Time formats
The platform supports the following formats for time.
| Format | 说明 |
|---|---|
| H:m | Time is specified in 24-hour format, providing hours and minutes, without zero-padding, 使用 time separator. |
| H:m:s | Time is specified in 24-hour format, providing hours, minutes, and seconds, without zero-padding, 使用 time separator. |
| HH:mm | Time is specified in 24-hour format, providing hours and minutes, with zero-padding, 使用 time separator. |
| HH:mm:ss | Time is specified in 24-hour format, providing hours, minutes, and seconds, with zero-padding, 使用 time separator. |
Epoch format
It is possible to specify a date and time in epoch format, that is, as the number of seconds since midnight on January 1, 1970, UTC. The epoch format is always ex按下ed in UTC, and t此处fore does not allow time zone indication.
| Format | 说明 |
|---|---|
| nnnnnnnnnn | Epoch format. In this format, the date and time are reported as a number of seconds from midnight on January 1, 1970, UTC. For example, the date "2010/10/23 02:47:25" corresponds to the value 1287802045. |
Time zone indication (optional)
All APIs require the use of UTC dates and times. However, local times are allowed as long as they contain the time zone offset indication.
- For all dates and times that do not contain a time zone offset (or that contain the "Z" suffix), they will be assumed to be ex按下ed in UTC.
- If a time zone offset is provided, it must consist of a "+" or "-" sign, followed by hours and minutes 使用 time separator between them.
- Time zone offsets are not compatible with epoch format. Epoch format must always be reported in UTC.
Below are some examples.
| 示例 | UTC value used | 说明 |
|---|---|---|
| 2020-02-21 03:37:14 | 2020-02-21 03:37:14 (same) | No time indication, so UTC is assumed. Corresponds to 03:37:14 on February 21, 2020, UTC time. |
| 2020-02-21 03:37:14Z | 2020-02-21 03:37:14 (same) | The Z suffix indicates the time is ex按下ed in UTC, so this example is equivalent to the previous one. |
| 2020-02-21 20:30:25 -05:00 | 2020/02/22 01:30:25 | Indicates a 5-hour offset to the west. Note that in UTC time, the date advances 5 hours and moves to the next day. |
| 2020-02-21 20:30:25 +05:00 | 2020-02-21 15:30:25 | Indicates a 5-hour offset to the east. |