IoT Time Series Service - 示例
只要您的设备已连接到 MindSphere 并发送了时间序列数据，您就可以通过执行分析和可视化深入了解相关信息。时间序列数据始终基于 asset 的 aspect 进行存储。
先决条件
- 创建一个 aspect，并已定义要收集的数据类型。
- 将 aspect 分配给 asset，以便存储时间序列数据。
写入时间序列数据
本节示例基于符合限制的PUT端点。
注意
如果为已存在的时间戳写入数据，该时间戳包含所有 varialbes 的所有现有记录将被覆写。如果新请求中只提供部分数据，未提供数据的现有 varialbes 将被覆写为 NULL。
创建单条时间序列记录
不带任何参数调用以下端点来为 aspect 创建单条时间序列记录：
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}
该端点期望堪载荷中包含一个 _time 时间戳字段和指定 aspect 的 varialbes 字段。时间戳必须符合ISO 8601。
以下 aspect 示例载荷包含两个数值 varialbes temperature 和 pressure，以及一个字符串 variable notes:
[
{
"_time": "2017-11-02T00:00:00.001Z",
"temperature": 10,
"pressure": 2,
"notes": "normal operation"
}
]
创建多条时间序列记录
您可以在单个请求中使用上述同样的端点来创建具有不同时间戳的多条记录：
有效载荷示例：
[
{
"_time": "2017-11-02T00:00:00.001Z",
"temperature": 10,
"pressure": 2,
"notes": "normal operation"
},
{
"_time": "2017-11-02T00:01:00.001Z",
"temperature": 17,
"pressure": 2,
"notes": "normal operation"
}
]
为多个Aspect创建时间序列记录
使用如下端点来为相同或不同 asssets 的多个 aspects 创建时间序列数据：
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries;
信息
所有 aspects 必须属于同一个租户。
有效载荷示例：
{
"timeseries": [
{
"entityId": "{assetId_1}",
"propertysetName": "{aspectName_1}",
"data": [
{
"enginetemperature_1": 100,
"speed_1": 100,
"_time": "2019-03-25T01:00:00Z"
},
{
"enginetemperature_2": 200,
"speed_2": 200,
"_time": "2019-03-25T02:00:00Z"
}
]
},
{
"entityId": "{assetId_2}",
"propertysetName": "{aspectName_2}",
"data": [
{
"rpm_1": 10,
"pressure_1": 200,
"_time": "2019-03-25T01:00:00Z"
}
]
}
]
}
发送到端点的所有数据都异步写入底层数据存储。因此，从服务读回数据时可能存在延迟。有效载荷的审核是同步完成的，因此客户端可以立即收到反馈。
读取时间序列数据
本节示例基于符合限制的GET端点。
该端点响应包含最多2000条记录。如果还有更多记录需要读取，该响应包含一个获取剩余记录 URI 的 Link 头，例如：
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}; rel="next"
获取指定 Variable 数据
通过 URL 参数 select 指定某个 apscpect 的 某个 variable：
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?select=temperature
select 参数对大小写敏感。它接受逗号分隔的变量名称列表和质量代码变量名称。变量名称带有 -qc 后缀。
select 参数可以与以下部分描述的 URL 参数组合使用。
Info
select 查询从响应中排除其他变量，但不检查指定的变量是否可用。响应可能包含只由时间戳字段组成的时间序列记录。
响应示例：
[
{
"temperature": 17,
"_time": "2017-11-01T01:00:00.001Z"
}
]
获取最新记录
当 Aspect 数据频繁更改时，首选此端点。在没有额外 URL 参数的情况下调用以下端点来读取 aspect 的最新记录:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}
最新记录 vs. 最新值
注意，最新的记录可能只包含一个时间戳。要读取最新值，请使用对应 URL 参数。
示例响应：
[
{
"temperature": 12,
"pressure": 4,
"notes": "normal operation",
"_time": "2017-11-02T00:00:00.001Z"
}
]
获取最新值
当方面数据不经常更改时，首选此端点。使用 URL 参数 latestValue 请求最新值:
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?latestValue=true;
最新记录 vs. 最新值
注意，此请求返回每个变量的最新接收值和关联的时间戳。要读取最新接收到的记录，请使用对应请求。
响应示例：
[
{
"enginetemperature": 11234570,
"speed": 3,
"_time": "2019-05-15T04:30:00Z"
},
{
"rpm": 13.12,
"_time": "2019-05-16T04:30:00Z"
},
{
"pressure": 4,
"_time": "2019-05-16T05:30:00Z"
}
]
获取某个指定时间范围内的数据
使用URL参数 from 和 to 指定所需的时间范围：
https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&to=2018-01-01T00:00:00Z
要设置时间范围的时区，必须在 URL 中将 + 字符编码为 %2B。例如，应发送 017-09-21T14:08:00%2B02:00，而非 2017-09-21T14:08:00+02:00。
示例响应：
[
{
"temperature":10,
"pressure":2,
"notes": "normal operation",
"_time":"2017-11-01T00:00:00.001Z"
},
{
"temperature":17,
"pressure":2,
"notes": "normal operation",
"_time":"2017-11-01T01:00:00.001Z"
}
]
响应中的时间戳采用 UTC 时区，以 ISO 8601 格式显示。服务将返回时间戳晚于 from 时间且早于或等于 to 时间的时间序列记录。默认情况下，响应中的相关记录按升序排序。可以使用可选的 sort 参数更改排序（目前仅在 Europe 1 可用）。sort 参数的可选值为 desc 或 asc。
错误请求
如果端点以 HTTP 400 错误请求响应，有可能因为以下原因：
- 指定的时间范围大于90天。
from字段大于to字段。
获取指定开始时间之后自定义数量的记录
使用 URL 参数 from 和 limit 指定所需记录的数量和开始时间：
GET https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&limit=4
响应示例：
[
{
"temperature": 10,
"pressure": 2,
"notes": "normal operation",
"_time": "2017-11-01T00:00:00.001Z"
},
{
"temperature": 17,
"pressure": 2,
"notes": "normal operation",
"_time": "2017-11-01T01:00:00.001Z"
}
]
如果可用结果少于定义的 limit ，则响应只包含可用记录。
删除时间序列数据
本节示例基于应用限制的DELETE 端点。
合法删除请求示例
使用 URL 参数 from和 to 指定所需的每小时对齐时间范围:
DELETE https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&to=2017-11-01T01:00:00Z
指定的时间范围不能超过7天：
DELETE https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&to=2017-11-08T00:00:00Z
非法删除请求示例
指定的时间范围必须每小时对齐一次。如果 from 和 to 未与UTC小时对齐则以下请求将失败:
DELETE https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:15:00Z&to=2017-11-01T02:15:00Z
指定的时间范围不能超过7天。如果 from 和 to 时间大于7天则以下请求将失败：
DELETE https://gateway.{region}-{environment}.{mindsphere-domain}/api/iottimeseries/v3/timeseries/{assetId}/{aspectName}?from=2017-11-01T00:00:00Z&to=2017-12-01T00:00:00Z
还有问题?
除非另行声明，该网站内容遵循MindSphere开发许可协议.