开发者中心

测量值

测量值接口由三部分组成:

  • 测量值API资源将URI和URI模板返回到测量值集合, 使得可以根据各种过滤器准则来查询测量值。
  • 测量值集合资源检索测量并且能够创建新的测量值。
  • 测量值资源表示可以查询和删除的单个测量值。

注意: 所有的PUT/POST请求必须设置accept头, 否则会返回空的应答正文。

测量值API

测量值API [application/vnd.com.nsn.cumulocity.measurementApi+json
名称 类型 次数 描述
self URL 1 资源链接。
measurements Measurement Collection 1 所有测量值集合。
measurementsForSource MeasurementCollection URI template 1 来自特定源对象的所有测量值的只读集合 (占位符 {source})。
measurementsForDate MeasurementCollection URI template 1 特定时间段的所有测量值的只读集合 (占位符 {dateFrom} 和 {dateTo})。
measurementsForFragmentType MeasurementCollection URI template 1 包含特定片段类型的所有测量值的只读集合 (占位符 {fragmentType})。
measurementsForType MeasurementCollection URI template 1 包含特定类型的所有测量值的只读集合 (占位符 {type})。
measurements ForSourceAndDate MeasurementCollection URI template 1 特定时间段和特定源对象的所有测量值的只读集合 (占位符 {dateFrom}, {dateTo} 和 {source})。
measurements ForSourceAndFragmentType MeasurementCollection URI template 1 包含特定片段类型并来自特定源对象的所有测量值的只读集合 (占位符 {fragmentType} 和 {source})。
measurements ForSourceAndType MeasurementCollection URI template 1 包含特定类型并来自特定源对象的所有测量值的只读集合 (占位符 {type} 和 {source})。
measurements ForDateAndFragmentType MeasurementCollection URI template 1 包含特定片段类型并且来自特定时间段的所有测量值的只读集合 (占位符 {fragmentType}, {dateFrom} 和 {dateTo})。
measurements ForDateAndType MeasurementCollection URI template 1 包含特定类型和来自特定时间段的所有测量值的只读集合 (占位符 {type}, {dateFrom} 和 {dateTo})。
measurements ForFragmentTypeAndType MeasurementCollection URI template 1 包含特定类型和特定片段类型的所有测量值的只读集合 (占位符 {type} 和 {fragmentType})。
measurements ForSourceAndDateAndFragmentType MeasurementCollection URI template 1 包含特定片段类型并来自特定时间段和源对象的所有测量值的只读集合 (占位符 {fragmentType}, {dateFrom}, {dateTo} 和 {source})。
measurements ForSourceAndDateAndType MeasurementCollection URI template 1 包含特定类型并来自特定时间段不和源对象的所有测量值的只读集合 (占位符 {type}, {dateFrom}, {dateTo} 和 {source})。
measurements ForSourceAndFragmentTypeAndType MeasurementCollection URI template 1 包含特定片段类型和特定类型和源对象的所有测量值的只读集合 (占位符 {fragmentType}, {type} 和 {source})。
measurements ForDateAndFragmentTypeAndType MeasurementCollection URI template 1 包含特定片段类型并来自特定时间段和类型对象的所有测量值的只读集合 (占位符 {fragmentType}, {dateFrom}, {dateTo} 和 {type})。
measurementsForSource AndDateAndFragmentTypeAndType MeasurementCollection URI template 1 包含特定片段类型和类型对象且来自特定时间段和源对象的所有测量值的只读集合 (占位符 {fragmentType}, {dateFrom}, {dateTo}, {type} 和 {source})。
GET - 查询测量值API资源

应答正文: application/vnd.com.nsn.cumulocity.measurementApi+json 所需角色: ROLE_MEASUREMENT_READ

请求示例:

GET /measurement
                      Host: ...
                      Authorization: Basic ...
                    

应答示例:

HTTP/1.1 200 OK
                      Content-Type: application/vnd.com.nsn.cumulocity.measurementApi+json;ver=...
                      Content-Length: ...
                      {
                      "self" : "<<Measurement API URL>>",
                      "measurements" : { "self" : "<<MeasurementCollection URL>>" },
                      "measurementsForSource" : "<<MeasurementCollection URL>>?source={source}",
                      "measurementsForDate" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
                      "measurementsForFragmentType" : "<<MeasurementCollection URL>>?fragmentType={fragmentType}",
                      "measurementsForType" : "<<MeasurementCollection URL>>?type={type}",
                      "measurementsForSourceAndDate" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
                      "measurementsForSourceAndFragmentType" : "<<MeasurementCollection URL>>?source={source}&fragmentType={fragmentType}",
                      "measurementsForSourceAndType" : "<<MeasurementCollection URL>>?source={source}&type={type}",
                      "measurementsForDateAndFragmentType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
                      "measurementsForDateAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
                      "measurementsForFragmentTypeAndType" : "<<MeasurementCollection URL>>?fragmentType={fragmentType}&type={type}",
                      "measurementsForSourceAndDateAndFragmentType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}",
                      "measurementsForSourceAndDateAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&type={type}",
                      "measurementsForSourceAndFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&fragmentType={fragmentType}&type={type}",
                      "measurementsForDateAndFragmentTypeAndType" : "<<MeasurementCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}",
                      "measurementsForSourceAndDateAndFragmentTypeAndType" : "<<MeasurementCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}&fragmentType={fragmentType}&type={type}"
                    }
                  

测量值集合

测量值集合 [application/vnd.com.nsn.cumulocity.measurementCollection+json]
名称 类型 次数 描述
self URL 1 资源链接。
measurements Measurement 0..n 测量值列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询测量值集合

应答正文: 测量值集合

所需角色: ROLE_MEASUREMENT_READ

请求示例: 查询能耗读数。

 GET /measurement/measurements
                   Host: ...
                   Authorization: Basic ...
                   Accept: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
                 

应答示例:

HTTP/1.1 200 OK
                  Content-Type: application/vnd.com.nsn.cumulocity.measurementCollection+json;ver=...
                  Content-Length: ...

                  {
                  "self":"...",
                  "measurements":[
                  {
                  "id" : "42",
                  "self" : "...",
                  "time" : "2011-09-06T12:03:27.845Z",
                  "type" : "KamstrupA220Reading",
                  "source" : { "id": "12345", "self": "..." },
                  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
                  "A+:1": { "value": 123, "unit": "kWh" },
                  "A-:1": { "value": 2, "unit": "kWh" }
                },
                "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
                "A+:1": { "value": 123, "unit": "kWh" },
                "A+:2": { "value": 123, "unit": "kWh" },
                "A+:3": { "value": 123, "unit": "kWh" }
              }
            },
            {
            "id" : "43",
            "self" : "...",
            "time" : "2011-09-19T12:03:27.845Z",
            "type" : "KamstrupA220Reading",
            "source" : { "id": "12345", "self": "..." },
            "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
            "A+:1": { "value": 1234, "unit": "kWh" },
            "A-:1": { "value": 2, "unit": "kWh" }
          },
          "com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
          "A+:1": { "value": 1234, "unit": "kWh" },
          "A+:2": { "value": 1234, "unit": "kWh" },
          "A+:3": { "value": 1234, "unit": "kWh" }
        }
      }
      ],
      "statistics" : {
      "totalPages" : 2,
      "pageSize" : 5,
      "currentPage : 1
    }
  }

在对测量值API执行范围查询的情况下, 例如通过dateFrom和dateTo查询, 按照从最后到最新的顺序返回测量值。 可以通过向请求URL添加查询参数"revert=true"来更改顺序。 在许多使用情况下,需要获取从设备发送的最新测量值。 这可以通过将"revert"参数与"dateFrom"和"dateTo"参数一起传递来按日期排序结果来完成。

GET - 查询测量值序列

此端点返回以简化形式在测量值中找到的所有系列(包含值的任何片段都是序列)。 强制性参数是: dateFrom, dateTo和source。 此处不使用分页。 可以通过传递附加的参数: aggregationType (DAILY, HOURLY, MINUTELY)来获取聚合结果。 如果未指定聚合参数, 则结果不超过5000个值。 重要信息: 为了正确完成聚合, 要求设备在发送日期时始终使用相同的时区。

所需角色: ROLE_MEASUREMENT_READ

请求示例: 查询所有序列。

 GET /measurement/measurements/series...
   Authorization: Basic ...
   Accept: application/json
 

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/json
  Content-Length: ...

  {
  values: {
  2014-12-04T17:33:01.538+01:00: [
  {
  min: 13.37,
  max: 13.37
},
{
  min: 11.37,
  max: 11.37
}],
2014-12-04T17:34:01.774+01:00: [
{
  min: 10.2,
  max: 10.2
},
{
  min: 11.37,
  max: 11.37
}]
},
series: [
{
  unit: "m/s2",
  name: "acceleration",
  type: "c8y_AccelerationMeasurement"
},
{
  unit: "m/s",
  name: "velocity",
  type: "c8y_SpeedMeasurement"
}],
truncated: false
}

数值对象中的每个值都是从测量值获得的日期, 在该日期内有一个最小和最大对的列表。 每个对对应于序列对象中的单个序列定义。 如果没有使用聚合, 则在每对中min = max。

"Truncated"标志指示是否有超过5000个值, 并且最终结果是否被截断。

POST - 创建新测量值

请求正文: 测量值

应答正文: 测量值

所需角色: ROLE_MEASUREMENT_ADMIN 或源对象所有者

请求示例:

POST /measurement/measurements
  Host: ...
  Authorization: Basic ...
  Content-Length: ...
  Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...

  {
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345" },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
  "A+:1": { "value": 1234, "unit": "kWh" },
  "A-:1": { "value": 2, "unit": "kWh" }
},
"com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
"A+:1": { "value": 1234, "unit": "kWh" },
"A+:2": { "value": 1234, "unit": "kWh" },
"A+:3": { "value": 1234, "unit": "kWh" }
}
}

应答示例:

HTTP/1.1 201 Created
  Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
  Content-Length: ...

  {
  "id" : "43",
  "self" : "<<URL of new measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
  "A+:1": { "value": 1234, "unit": "kWh" },
  "A-:1": { "value": 2, "unit": "kWh" }
},
"com_cumulocity_model_energy_measurement_ThreePhaseElectricityMeasurement": {
"A+:1": { "value": 1234, "unit": "kWh" },
"A+:2": { "value": 1234, "unit": "kWh" },
"A+:3": { "value": 1234, "unit": "kWh" }
}
}

对于POST请求, source参数必须只有一个id。

新测量的"id"由服务器生成, 并在对POST操作的应答中返回。

请注意, 为了在UI图上正确显示测量序列, 用于片段和序列名称的属性名称不应包含空格和特殊字符, 如[],*。

DELETE - 删除测量值集合

DELETE方法允许删除测量集合。 适用的查询参数等同于GET方法。

请求正文: N/A

应答正文: N/A

所需角色: ROLE_MEASUREMENT_ADMIN

请求示例:

 DELETE: /measurement/measurements....
 Host: ...
 Authorization: Basic ...

应答示例:

HTTP/1.1  204 NO CONTENT

测量值

测量值 [application/vnd.com.nsn.cumulocity.measurement+json]
名称 类型 次数 描述 PUT/POST
id String 1 唯一标识测量值。
self URI 1 资源链接。
time String 1 测量值得时间。 必选
type String 1 整个测量的具体类型。 必选
source ManagedObject 1 此测量值的源的托管对象, 包含属性"id"和"self"。 必选
* * 0..n 测量值片段列表。 可选

每个测量值片段是包含作为属性的实际测量值的对象。 属性名称表示测量值的名称, 属性值的结构如下:

名称 类型 次数 描述 PUT/POST
value Number 1 单独测量值的值。 必选
unit String 1 测量值单位, 如 "Wh" 或 "C"。 可选
GET - 查询测量值表示

应答正文: 测量值

所需角色: ROLE_MEASUREMENT_READ

请求示例:

GET /measurement/measurements/<<measurementId>>
  Host: ...
  Authorization: Basic ...

应答示例:

Content-Type: application/vnd.com.nsn.cumulocity.measurement+json;ver=...
  Content-Length: ...
  {
  "id" : "43",
  "self" : "<<URL of the measurement>>",
  "time" : "2011-09-19T12:03:27.845Z",
  "type" : "KamstrupA220Reading",
  "source" : { "id": "12345", "self": "..." },
  "com_cumulocity_model_energy_measurement_SinglePhaseElectricityMeasurement": {
  "A+:1": { "value": 1234, "unit": "kWh" },
  "A-:1": { "value": 2, "unit": "kWh" }
},
"com_cumulocity_msrmts_ThreePhaseReading": {
"A+:1": { "value": 1234, "unit": "kWh" },
"A+:2": { "value": 1234, "unit": "kWh" },
"A+:3": { "value": 1234, "unit": "kWh" }
}
}
DELETE - 删除测量值

请求正文: N/A.

应答正文: N/A.

所需角色: ROLE_MEASUREMENT_ADMIN 或源对象所有者

请求示例: 删除测量值

DELETE /measurement/measurements/<<measurementID>>
 Host: [hostname]
 Authorization: Basic xxxxxxxxxxxxxxxxxxx

应答示例:

HTTP/1.1  204 NO CONTENT

数据流

测量值集合API允许以数据流的形式获取数据。 响应格式保持不变,但数据由服务器直接从数据库逐个元素传输,因此可以以相同的方式接收。 使用流式json解析,如java jsonjavascript json解析器,我们能够在单个请求中传输更大数据量。 要激活流,你需要设置Accept头applicatnion/json-stream

示例:

 GET /measurement/measurements
   Host: [hostname]
   Authorization: Basic xxxxxxxxxxxxxxxxxxx
   Accept application/json-stream
 

通知

测量值通知API允许接收针对特定设备的所有测量值的更新。 接收通知的基本协议参见 "实时通知"。 URL是

/cep/realtime
  

订阅频道需要包含设备的管理对象ID或"*"作为占位符, 以接收所有设备测量的通知

/measurements/<<deviceId>>
  

应答将附加到测量值对象包含"realtimeAction"以标识哪个动作导致给定对象(CREATE, UPDATE 或 DELETE)。 在删除的情况下,数据将仅包含已删除测量值的id。

应答示例:

HTTP/1.1 200 OK 
    Content-Type: application/json
    [
    {
    "channel": "/measurement/12345", 
    "successful": true, 
    "error": "", 
    "data": [{
    "realtimeAction": "CREATE",
    "data": {
    "id": "1",
    "self": "...",
    "source": { 
    "12345"
  },
  "creationTime": "2011-09-06T12:03:27.927+02:00",
  "c8y_TemperatureMeasurement": {
  "T": { 
  "value": 25,
  "unit": "C" 
}
},
"time":"2011-09-06T12:03:17.927+02:00", 
"type": "TemperatureMeasurement"
}
}], 
"clientId": "Un1q31d3nt1f13r" 
}
]

所需角色: ROLE_MEASUREMENT_READ