说明

欢迎使用SensorThings API文档!本文档讲解了Open Geospatial Consortium (OGC) SensorThings国际标准的的相关内容。OGC SensorThings API为物联网(Internet of Things,IoT)中的所有设备提供了开放且统一的连接方式,也给这些设备的观测(Observations)提供了可供运用与分析的接口。

SensorThings API的基础是对系统中的实体(entities)在现实世界中的相互关系进行模型化。这些实体之间的自然关系使得任何垂直产业中的物联网传感器设备都可被模型化。比如,一个物联网设备(device)或者一个物联网系统(system)可模型化为一个物体(Thing),一个物体(Thing)既含有位置(Location),也含有一个或多个数据流(Datastreams)。每个数据流(Datastream)都是通过一个传感器(Sensor)观测一个观测属性(ObservedProperty)而获得的,且这个传感器(Sensor)可能存在多个观测(Observations)。传感器(Sensor)观测(Observation)的是一个特定的被观测物(FeatureOfInterest)。综合以上,这些相互关系就可灵活且标准化地描述和模拟各种传感系统,SensorThings借助这些相互关系从而实现了为任何组织的异构设备提供了单数据交换的功能。

这份文档可指导开发人员如何增删改查(Create-Read-Update-Delete ,CRUD),以及如何通过复杂查询从系统中取回数据。文档中一部分示例提供了向SensorThings服务器发送请求的模版。

OGC SensorThings API standard

UML数据模型

下图为OGC SensorThings API的UML数据模型,其中定义了不同的实体以及他们的属性,同时展示了不同实体之间的关系。

Sensor ObservedProperty Datastream Observation Thing Location HistoricalLocation FeatureOfInterest

SensorThings资源基路径

想取得资源首先需要获得资源基路径。

返回所有可用的SensorThings资源的JSON数组。

[formpanel type=GET] [formtitle] /v1.0/ [/formtitle] [formbody]

[/formbody] [/formpanel]

Things

Thing可能是一个实体世界的物件(实体的物体),也可能是信息世界(虚拟的物体),可被识别和整合进入通讯网路[ITU-T Y.2060]。

Thing是创建SensorThings模型结构的起点,一个Thing有Location(位置)和一个或多个Datastreams(数据流)来Observation(观测)。一个最精简的Thing可在不指定Location和Datastreams的情况下创建。同时,Thing也可以通过嵌套Location和Datastreams来创建。

POST

Property Required Type
name mandatory String
description mandatory String
properties optional JSON Object

创建一个Thing时所需的实体:

Entity Required
Locations optional
HistoricalLocations optional
Datastreams optional

示例 1: POST

创建一个Thing。 [tabpanel] [tabpage header=HTTP id=thingspost-example1-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example1-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);  
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example1-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用新的Location来POST

在创建Thing时,可同时创建跟他相关的Location(位置),这个Location在系统中将以一个新的Location进行存储。

[tabpanel] [tabpage header=HTTP id=thingspost-example2-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example2-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example2-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }]
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 链接已存在的Location来POST

创建一个Thing,并将其绑定一个已存在的Location id。

[tabpanel] [tabpage header=HTTP id=thingspost-example3-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example3-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example3-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}' 'https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things'

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 嵌入Location和Datastream来POST

创建一个Thing,并嵌入Location和Datastream。在请求正文中嵌入完整的JSON实体的对象表示,便可与相关实体进行连接。

[tabpanel] [tabpage header=HTTP id=thingspost-example4-1]

{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=thingspost-example4-2]

var json = JSON.stringify({
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=thingspost-example4-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "Temperature Monitoring System",
  "description": "Sensor system monitoring area temperature",
  "properties": {
    "Deployment Condition": "Deployed in a third floor balcony",
    "Case Used": "Radiation shield"
  },
  "Locations": [{
    "name": "UofC CCIT",
    "description": "University of Calgary, CCIT building",
    "encodingType": "application/vnd.geo+json",
    "location": {
      "type": "Point",
      "coordinates": [-114.133, 51.08]
    }
  }],
  "Datastreams": [{
    "name": "Air Temperature DS",
    "description": "Datastream for recording temperature",
    "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "unitOfMeasurement": {
      "name": "Degree Celsius",
      "symbol": "degC",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
    },
    "ObservedProperty": {
      "name": "Area Temperature",
      "description": "The degree or intensity of heat present in the area",
      "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
    },
    "Sensor": {
      "name": "DHT22",
      "description": "DHT22 temperature sensor",
      "encodingType": "application/pdf",
      "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
    }
  }]
}' 'https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things'

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有的Thing。

[tabpanel] [tabpage header=HTTP id=Things-get-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things

[/tabpage] [tabpage header=JavaScript/jQuery id=Things-get-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Things-get-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来GET

取回一个指定的Thing。

[formpanel type=GET] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用expand来GET

使用$expand查询选项,取回一个Thing和其所包含的实体,可取回多实体集合或单一实体。

$expand相关实体 描述
Locations 展示Thing实体内Location
Datastreams 展示Thing实体内Datastreams详细内容
HistoricalLocations 展示Thing实体内HistoricalLocation详细内容

[formpanel type=GET] [formtitle] /v1.0/Things(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用select来GET

取回一个指定的Thing的特定属性。

$select查询属性 Description
name Thing的实体名称
description Thing的实体描述
properties Thing的物体属性
Locations 从Thing到Location的链接
Datastreams 从Thing到Datastream的链接
HistoricalLocations 从Thing到HistoricalLocations的链接

[formpanel type=GET] [formtitle] /v1.0/Things(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个指定Thing的属性。

[tabpanel] [tabpage header=HTTP id=things-patch-1]

{
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}

[/tabpage] [tabpage header=JavaScript/jQuery id=things-patch-2]

var patchJson = JSON.stringify({
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
});

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(2)",
  type: "PATCH",
  data: patchJson,
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);

  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=things-patch-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "description": "WiFi Water Temperature System",
  "properties": {
    "detail": "3 ft water sealed, external temperature probe.",
    "WiFi-range": "Up to 250 ft.* (Typical to standard WiFi devices)"
  },
  "Locations": [
    {"@iot.id":1}
  ]
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(2)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

删除一个Thing。 [tabpanel] [tabpage header=HTTP id=Things-delete-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Things-delete-2]

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)",
  type: "DELETE",
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);
  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Things-delete-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Things(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Locations

Location(位置)实体记录Thing(s)关联的位置。一个Thing的Location实体被定义为Thing最后已知的位置(物理位置)。 当一个location(物理位置)存在多种encodingType(编码类型)时,此时的Thing可关联多个Locations。

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
location mandatory Any (Depends on encodingType)

创建一个Location所需的实体:

Entity Required
Things optional
HistoricalLocations optional

示例 1: POST

创建一个Location。

[tabpanel] [tabpage header=HTTP id=Locaitons-post-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-post-2]

var location = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations",
    type: "POST",
    data: location,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Locaitons-post-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 链接已存在的Thing来POST

创建一个Location,并将其绑定一个已存在的Thing。

[tabpanel] [tabpage header=HTTP id=Locaitons-post2-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-post2-2]

var location = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(705831)/Locations",
    type: "POST",
    data: location,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Locaitons-post2-3]

curl -XPOST -H "Content-type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "location": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Things(705831)/Locations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things(id)/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有的Location。

[tabpanel] [tabpage header=HTTP id=Locaitons-get-tab1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Locations

[/tabpage] [tabpage header=JavaScript/jQuery id=Locaitons-get-tab1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Locations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Locaitons-get-tab1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Locations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来GET

取回一個指定的Location。

[formpanel type=GET] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用Thing id来GET

取回一个指定Thing的Locations。

[formpanel type=GET] [formtitle] /v1.0/Things(id)/Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用expand来GET

使用$expand查询选项,取回一个指定的Location和其所包含的实体。

$expand相关实体 描述
Things 显示Location內部的Thing详细内容
HistoricalLocations 现实Location内部的HistoricalLocation详细内容

[formpanel type=GET] [formtitle] /v1.0/Locations(id)?$expand=Things [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 5: 使用filter来GET(空间查询)

取回指定的多边形中的所有Locations,并扩展到Thing实体来取回所有元数据。

[formpanel type=GET] [formtitle] /v1.0/Locations?$expand=Things&$filter=st_within(location, geography’POLYGON ((-79.39 43.651,-79.371 43.651,-79.371 43.641,-79.39 43.641,-79.39 43.651))’) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 6: 使用select来GET

从指定Location中取回特定的属性。

$select查询属性 描述
name Location名称
description Location描述
encodingType Location的编码类型
location 编码类型定义的location
Thing 从Location到Thing的链接
HistoricalLocations 从Location到HistoricalLocations的链接

[formpanel type=GET] [formtitle] /v1.0/Locations(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新Location的属性值。

[tabpanel] [tabpage header=HTTP id=Location-patch-1]

{
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Location-patch-2]

var patchJson = JSON.stringify({
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
});

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Location(1)",
  type: "PATCH",
  data: patchJson,
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);

  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Location-patch-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "name": "Edworthy Park Area",
  "location": {
    "type": "Point",
    "coordinates": [-114.154,51.064]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Location(2)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個Location。

[tabpanel] [tabpage header=HTTP id=Locations-delete-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Locations-delete-2]

$.ajax({
  url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)",
  type: "DELETE",
  contentType: "application/json; charset=utf-8",
  success: function(data){
    console.log(data);
  },
  error: function(response, status){
    console.log(response);
    console.log(status);
  }
});

[/tabpage] [tabpage header=cURL id=Locations-delete-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Locations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Locations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

HistoricalLocations

Thing的HistoricalLocation(历史位置)实体提供了Thing的当前(最后已知)和之前所有locations的时间。

GET

Exmaple 1: GET

取回所有的HistoricalLocations。

[tabpanel] [tabpage header=HTTP id=HistoricalLocations-get-tab-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocations-get-tab-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=HistoricalLocations-get-tab-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/HistoricalLocations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来GET

取回指定的HistoricalLocations。

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用expand来GET

使用$expand查询选项取回指定的HistoricalLocations以及其包含的相关实体信息。

$expand相关实体 描述
Locations 显示HistoricalLocations內部的Location详细内容
Thing 显示HistoricalLocations內部的Thing详细内容

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id)?$expand=Locations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用select来GET

从指定的HistoricalLocation取回特定的属性数据。

$select查询属性 描述
time HistoricalLocation的时间
Locations 从HistoricalLocation到Locations链接
Thing 从HistoricalLocation到Thing的链接

[formpanel type=GET] [formtitle] /v1.0/HistoricalLocations(id)?$select=time [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新HistoricalLocation的属性值。

[tabpanel] [tabpage header=HTTP id=HistoricalLocation-patch-tab-1]

{
  "time": "2015-02-07T19:22:11.297Z"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocation-patch-tab-2]

var patchJson = JSON.stringify({
  "time": "2015-02-07T19:22:11.297Z"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=HistoricalLocation-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "time": "2015-02-07T19:22:11.297Z"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個HistoricalLocation。

[tabpanel] [tabpage header=HTTP id=HistoricalLocation-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocation(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=HistoricalLocation-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=HistoricalLocation-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/HistoricalLocations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/HistoricalLocations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Datastreams

同一个Sensor(传感器)测量同一个ObservedProperty(观测属性)Observations(观测)的集合,称之为Datastream(数据流)。

POST

Property Required Type
name mandatory String
description mandatory String
unitOfMeasurement mandatory JSON Object
observationType mandatory ValueCode
observedArea optional GeoJSON Polygon Object
phenomenonTime optional Time Interval (ISO 8601)
resultTime optional Time Interval (ISO 8601)

创建一个Datastream所需的实体:

Entity Required
Thing mandatory
ObservedProperty mandatory
Sensor mandatory
Observations optional

示例 1: POST

创建一个Datastream。

[tabpanel] [tabpage header=HTTP id=datastream-post-tab-1]

{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-post-tab-2]

var json = JSON.stringify({
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "Thing":{"@iot.id":2},
  "ObservedProperty":{"@iot.id":7},
  "Sensor":{"@iot.id":6}
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 链接已存在的Thing来POST

创建一个Datastream,并将其绑定一个已存在的Thing。

[tabpanel] [tabpage header=HTTP id=datastream-post-2-tab-1]

{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-post-2-tab-2]

var json = JSON.stringify({
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-post-2-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Air Temperature DS",
  "description": "Datastream for recording temperature",
  "observationType": "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
  "unitOfMeasurement": {
    "name": "Degree Celsius",
    "symbol": "degC",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeCelsius"
  },
  "ObservedProperty": {
    "name": "Area Temperature",
    "description": "The degree or intensity of heat present in the area",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
  },
  "Sensor": {
    "name": "DHT22",
    "description": "DHT22 temperature sensor",
    "encodingType": "application/pdf",
    "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Things(id)/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有的Datastreams。

[tabpanel] [tabpage header=HTTP id=Datastreams-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams

[/tabpage] [tabpage header=JavaScript/jQuery id=Datastreams-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Datastreams-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来GET

取回指定的Datastream。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用Thing id来GET

取回指定Thing的Datastream。

[formpanel type=GET] [formtitle] /v1.0/Things(id)/Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用expand来GET

使用$expand查询选项,取回一个指定的Datastream和其所包含的实体。

$expand相关实体 描述
Thing 显示Datastreams内部的Thing详细内容
Sensor 显示Datastreams内部的Sensor详细内容
ObservedProperty 时线Datastreams内部的ObservedProperty详细内容
Observations 显示Datastreams內部的Observations详细内容

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations,ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 5: 使用select来GET

從一个指定的Datastream取回特定的屬性數據。

$select查询属性 描述
name Datastream名称
description Datastream描述
unitOfMeasurement 传感器测量单位(Unit Of Measurement)的JSON对象
observationType 观测类型
observedArea Datastream相关的Observations在空间范围
phenomenonTime Datastream所有Observations的出现时间范围
resultTime Datastream所有Observations的结果时间范围
Thing 从Datastream到Thing的链接
Sensor 从Datastream到Sensor的链接
ObservedProperty 从Datastream到ObservedProperty的链接
Observations 从Datastream到Datastream的链接

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$select=description,unitOfMeasurement [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个Datastream属性值。 [tabpanel] [tabpage header=HTTP id=datastream-patch-tab-1]

{
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-patch-tab-2]

var patchJson = JSON.stringify({
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "unitOfMeasurement": {
    "name": "Degrees Fahrenheit",
    "symbol": "degF",
    "definition": "http://www.qudt.org/qudt/owl/1.0.0/unit/Instances.html#DegreeFahrenheit"
  },
  "description": "Water Temperature of Bow river"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個Datastream。 [tabpanel] [tabpage header=HTTP id=datastream-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastream(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=datastream-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=datastream-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Datastreams(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Datastreams(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Sensors

传感器(Sensor)在SensorThing API是测量仪器,負責观测一个属性或一种现象,并记录其得到的观测值。

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
metadata mandatory Any (depending on the value of the encodingType)

示例 1: POST

创建一個Sensor。

[tabpanel] [tabpage header=HTTP id=sensor-post-tab-1]

{
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=sensor-post-tab-2]

var json = JSON.stringify({
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        //To access a data field
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=sensor-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "DHT22",
  "description": "DHT22 temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "https://cdn-shop.adafruit.com/datasheets/DHT22.pdf"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Sensors [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有Sensor。

[tabpanel] [tabpage header=HTTP id=Sensors-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Sensors-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Sensors"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Sensors [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来Get

取回一個指定Sensor。

[formpanel type=GET] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用expand来GET

使用$expand查询选项,取回一个Sensor和其所包含的实体,可取回多实体集合或单一实体。

$expand相关实体 Description
Datastreams 显示Datastreams内部的详细内容

[formpanel type=GET] [formtitle] /v1.0/Sensors(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用select来GET

从一个指定的Sensor中取回特定的属性数据。

$select查询属性 Description
name Sensor实体名称
description Sensor实体描述
encodingType 元数据属性的编码类型
metadata Sensor或系统的详细描述,元数据类型由encodingType定义
Datastreams 从Sensor到Datastreams的链接

[formpanel type=GET] [formtitle] /v1.0/Sensors(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个Sensor属性值。 [tabpanel] [tabpage header=HTTP id=Sensors-patch-tab-1]

{
  "description": "DHT22 Temperature and Humidity sensor"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-patch-tab-2]

var patchJson = JSON.stringify({
  "description": "DHT22 Temperature and Humidity sensor"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Sensors-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "description": "DHT22 Temperature and Humidity sensor"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個Sensor。 [tabpanel] [tabpage header=HTTP id=Sensors-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Sensors-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Sensors-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Sensors(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Sensors(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

ObservedProperties

一个ObservedProperty特指一个观测值(Observation)的现象。

POST

Property Required Type
name mandatory String
definition mandatory URI
description mandatory String

示例 1: POST

创建一個ObservedProperty。

[tabpanel] [tabpage header=HTTP id=ObservedProperties-post-tab-1]

{
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-post-tab-2]

var json = JSON.stringify({
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "Area Temperature",
  "description": "The degree or intensity of heat present in the area",
  "definition": "http://www.qudt.org/qudt/owl/1.0.0/quantity/Instances.html#AreaTemperature"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/ObservedProperties [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有的ObservedProperty。

[tabpanel] [tabpage header=HTTP id=ObservedProperties-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/ObservedProperties"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用id来GET

取回一个指定的ObservedProperty。

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用Datastream id来GET

取回一个指定的Datastream的ObservedProperty。

[formpanel type=GET] [formtitle] /v1.0/Datastream(id)/ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用expand来GET

使用$expand查询选项,取回一个指定的ObservedProperty和其所包含的实体。

$expand相关实体 描述
Datastreams 显示这个ObservedProperties的Datastreams的详细内容

[formpanel type=GET] [formtitle] /v1.0/ObservedProperties(id)?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 5: 使用select来GET

从特定的ObservedProperty取回特定的属性数据。

$expand相关实体 描述
name ObservedProperty实体名称
definition ObservedProperty定义的URI
description ObservedPropert实体描述
Datastreams 从ObservedProperty到Datastreams的链接

[formpanel type=GET] [formtitle] /ObservedProperties(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个ObservedProperty属性值。

[tabpanel] [tabpage header=HTTP id=ObservedProperties-patch-tab-1]

{
  "name": "Water Temperature"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-patch-tab-2]

var patchJson = JSON.stringify({
  "name": "Water Temperature"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "name": "Water Temperature"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個ObservedProperty。

[tabpanel] [tabpage header=HTTP id=ObservedProperties-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=ObservedProperties-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=ObservedProperties-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/ObservedProperties(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/ObservedProperties(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

Observations

一个Observation(观测)是一种测量或者是测算一个属性值的行为,SensorThings中的一个Observation代表一个ObservedPropert中单个Sensor的读取值。一个物理设备(Sensor)发送Observations给一个指定的Datastream。同时,一个Observation需要一个FeatureOfInterest(被观测物)实体。如果请求中什么都没有提供FeatureOfInterest,那么这个Datastream所关联的Thing的Location,将被作为FeatureOfInterest指定为新的Observation。

POST

Property Required Type
phenomenonTime mandatory Time(Interval) String (ISO 8601)
result mandatory Any (depends on the observationType defined in the associated Datastream)
resultTime mandatory Time(Interval) String (ISO 8601)
resultQuality optional DQ_Element
validTime optional Time Interval String (ISO 8601)
parameters optional JSON Object

创建一个Observation时所需的实体:

Entity Required
Datastream mandatory
FeatureOfInterest mandatory (如果没有题佛难过FeatureOfInterest,系统会自动关联Location作为FeatureOfInterest)

示例 1: POST

创建一个觀測。 [tabpanel] [tabpage header=HTTP id=Observations-post-tab-1]

{
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-post-tab-2]

var json = JSON.stringify({
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "phenomenonTime": "2017-02-07T18:02:00.000Z",
  "resultTime" : "2017-02-07T18:02:05.000Z",
  "result" : 21.6,
  "Datastream":{"@iot.id":8}
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用FeatureOfInterest来POST

建立一個Observation,并嵌入新的FeatureOfInterest。

[formpanel type=POST] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 链接已存在Datastream来POST

创建一個Observation,并连接已存在的Datastream。

[formpanel type=POST] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 链接已存在的Datastream和FeatureOfInterest来POST

创建一个Observation,并连接到已存在的Datastream和FeatureOfInterest。

[formpanel type=POST] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有的Observations。

[tabpanel] [tabpage header=HTTP id=Observations-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=Observations-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 使用Observation id来GET

取回一个指定的Observation。

[formpanel type=GET] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用Datastream id来GET

从一个指定的Datastream中取回Observations。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用expand来GET

使用$expand查询选项,取回一个指定的Observation和其所包含的实体。

$expand相关实体 描述
Datastream 显示这个Observations中Datastream的详细内容
FeatureOfInterest 显示这个Observations中FeatureOfInterest的详细内容

[formpanel type=GET] [formtitle] /v1.0/Observations(id)?$expand=Datastream [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 5: 使用select来GET

从一个指定的Observation中取回特定的属性数据。

$select查询选项 描述
phenomenonTime 观测发生时间
result Sensor中ObservedProperty的数值
resultTime 得到观测结果的时间T
resultQuality 观测结果的质量
validTime 可能使用此结果的时间周期
parameters 在测量期间描述环境情况的键-值对
Datastream 从Observation到Datastream的链接
FeatureOfInterest 从Observation到FeatureOfInterest的链接

[formpanel type=GET] [formtitle] /v1.0/Observations(id)?$select=phenomenonTime,result [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个Observation属性值。 [tabpanel] [tabpage header=HTTP id=Observations-patch-tab-1]

{
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
}

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-patch-tab-2]

var patchJson = JSON.stringify({
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "phenomenonTime": "2017-02-09T18:02:00.000Z",
  "resultTime" : "2017-02-09T18:02:05.000Z"
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個Observation。 [tabpanel] [tabpage header=HTTP id=Observations-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=Observations-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=Observations-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/Observations(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

FeaturesOfInterest

一个Observation(观测)的动作实际是将一个数据被指定给了一种现象,这种现象可理解为一个特征属性,也就是Observation[OGC and ISO 19156:2011]的FeatureOfInterest(被观测物)。在物联网的环境中,许多Observations的FeatureOfInterest就是这个Thing的Location。举例来说,一个WiFi连接恒温器的FeatureOfInterest可以是这个恒温器的Location(比如放置这个恒温器的客厅)。但在遥感中,FeatureOfInterest就是这个恒温器被感测到的地理范围。

POST

Property Required Type
name mandatory String
description mandatory String
encodingType mandatory ValueCode
feature mandatory Any (depending on the value of the encodingType)

示例 1: POST

创建一个FeatureOfInterest。

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-post-tab-1]

{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-post-tab-2]

var json = JSON.stringify({
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest",
    type: "POST",
    data: json,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-post-tab-3]

curl -X POST -H "Content-Type: application/json" -d '{
  "name": "UofC CCIT",
  "description": "University of Calgary, CCIT building",
  "encodingType": "application/vnd.geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [-114.133, 51.08]
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest"

[/tabpage] [/tabpanel]

[formpanel type=POST] [formtitle] /v1.0/FeaturesOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

GET

示例 1: GET

取回所有FeatureOfInterest。

[tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-get-tab-1-1]

https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-get-tab-1-2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-get-tab-1-3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/FeaturesOfInterest"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

Exmaple 2: GET by id

取回一个指定的FeatureOfInterest。

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 使用expand来GET

使用$expand查询选项,取回一个指定的FeatureOfInteres和其所包含的实体。

$expand相关实体 描述
Observations 显示Observations中FeaturesOfInterest的详细内容

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id)?$expand=Observations [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 使用select来GET

取回一个指定的FeatureOfInterest特定属性。

$select查询选项 描述
name FeatureOfInterest实体名称
description FeatureOfInterest实体描述
encodingType 特征属性的编码类型
feature 被观测物特征的详细描述,数据类型可在encodingType中定义
Observations 从FeatureOfInterest到Observations的链接

[formpanel type=GET] [formtitle] /v1.0/FeaturesOfInterest(id)?$select=description [/formtitle] [formbody]

[/formbody] [/formpanel]

PATCH

更新一个FeatureOfInterest属性值。 [tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-patch-tab-1]

{
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
}

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-patch-tab-2]

var patchJson = JSON.stringify({
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
});

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)",
    type: "PATCH",
    data: patchJson,
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);

    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-patch-tab-3]

curl -X PATCH -H "Content-Type: application/json" -d '{
  "feature": {
    "coordinates": [
      -114.154,
      51.064
    ],
    "type": "Point"
  }
}' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/Observations(id)"

[/tabpage] [/tabpanel]

[formpanel type=PATCH] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

DELETE

刪除一個FeatureOfInterest。 [tabpanel] [tabpage header=HTTP id=FeaturesOfInterest-delete-tab-1]

https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)

[/tabpage] [tabpage header=JavaScript/jQuery id=FeaturesOfInterest-delete-tab-2]

$.ajax({
    url: "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)",
    type: "DELETE",
    contentType: "application/json; charset=utf-8",
    success: function(data){
        console.log(data);
    },
    error: function(response, status){
        console.log(response);
        console.log(status);
    }
});

[/tabpage] [tabpage header=cURL id=FeaturesOfInterest-delete-tab-3]

curl -X DELETE -H "Content-Type: application/json" -H -d '' "https://scratchpad.sensorup.com/OGCSensorThings/v1.0/FeaturesOfInterest(id)"

[/tabpage] [/tabpanel]

[formpanel type=DELETE] [formtitle] /v1.0/FeaturesOfInterest(id) [/formtitle] [formbody]

[/formbody] [/formpanel]

查询选项

使用查询选项可以简化在SensorThings中获得所需信息的请求。以下列出的所有查询选项都可以使用在SensorThings的各个实体中,可能选项具体使用会有些微差别。 SensorThings查询选项可以分为两种类型,一类主要用于指定请求的返回属性,$expand和$select属于这类。另一类主要用于对返回的结果设限、过滤或者重新排序,$orderby、$top、$skip、$count和$filter属于这类。

expand

使用$expand查询选项来请求相关实体的信息集合。

查询 选项 描述
$expand 使用逗号或前斜线间隔各子实体名称 取回指定的相关实体和基实体的内部内容

示例 1: 返回Things的集合,并返回这些Thing相关的Datastreams。

[tabpanel] [tabpage header=HTTP id=expand1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$expand=Datastreams

[/tabpage] [tabpage header=JavaScript/jQuery id=expand2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$expand=Datastreams",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=expand3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24expand=Datastreams"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$expand=Datastreams [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 返回Things的集合,并返回这些Thing相关的Datastreams,以及这些Datastream相关的ObservedProperty。

[formpanel type=GET] [formtitle] /v1.0/Thing?$expand=Datastreams/ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 返回指定id的Datastream,并返回内部相关的Observations和ObservedProperty。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations,ObservedProperty [/formtitle] [formbody]

[/formbody] [/formpanel]

select

$select查询选项从SensorThings服务中请求一个实体的特定属性。这个查询选项可用来简化从服务器传回的数据。

查询 选项 描述
$select 用逗号间隔各属性名称(包括链接的属性名称) 如设置,结果将包含SensorThing实体的特定属性

示例 1: 只返回Observation的result和phenomenonTime属性。

[tabpanel] [tabpage header=HTTP id=select1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$select=result,phenomenonTime

[/tabpage] [tabpage header=JavaScript/jQuery id=select2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$select=result,phenomenonTime",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=select3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24select=result%2CphenomenonTime"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$select=result,phenomenonTime [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 返回Datastream的name属性和Observations属性,以及Observations相关的FeatureOfInterest属性。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$select=name,Observations&$expand=Observations/FeatureOfInterest [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 返回一个指定的Datastream,并同时返回这个Datastream相关的Observations,返回的这些Observations中只挑选result和phenomenonTime这两种属性。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations($select=result,phenomenonTime) [/formtitle] [formbody]

[/formbody] [/formpanel]

orderby

使用$orderby查询选项对指定属性返回的结果进行升序(asc)或降序排列(desc)。

查询 选项 描述
$orderby 逗号间隔属性名称,后缀asc为升序,后缀desc为降序 用来指定需要按顺序排列的属性

示例: 返回按照phenomenonTime属性进行降序排列的所有Observations

[tabpanel] [tabpage header=HTTP id=orderby1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$orderby=phenomenonTime

[/tabpage] [tabpage header=JavaScript/jQuery id=orderby2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$orderby=phenomenonTime",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=orderby3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24orderby=phenomenonTime"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$orderby=phenomenonTime desc [/formtitle] [formbody]

[/formbody] [/formpanel]

top

使用$top查询选项来限制请求的实体数量

查询 选项 描述
$top 非负整型 指定一个非负整形来限制返回实体的数量。服务器将返回最多,但不超多这个指定值的实体

示例 1: 返回Observations中最新5个实体

[tabpanel] [tabpage header=HTTP id=top1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$top=5

[/tabpage] [tabpage header=JavaScript/jQuery id=top2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?$top=5",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=top3]

curl -X GET -H "Content-Type: application/json"  "https://toronto-bike-snapshot.sensorup.com/v1.0/Observations?%24top=5"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Observations?$top=5 [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 返回Observation中最新3个实体,并按照phenomenonTime属性进行降序排列。

[formpanel type=GET] [formtitle] /v1.0/Observations?$top=3&$orderby=phenomenonTime desc [/formtitle] [formbody]

[/formbody] [/formpanel]

skip

使用$skip来指定返回实体时应该跳过(忽略)的实体数量。

查询 选项 描述
$skip 非负整型 指定将被跳过的实体数量

示例 1: 按照服务器中实体顺序,跳过最近的6个Thing实体,返回从第7个开始的所有Thing。

[tabpanel] [tabpage header=HTTP id=skip1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$skip=5

[/tabpage] [tabpage header=JavaScript/jQuery id=skip2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$skip=5",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=skip3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24skip=5"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$skip=5 [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 从Observation集合中返回第3个和第4个实体,并在结果中按照phenomenonTime属性进行升序排列,

[formpanel type=GET] [formtitle] /v1.0/Observations?$skip=2&$top=2&$orderby=phenomenonTime [/formtitle] [formbody]

[/formbody] [/formpanel]

count

使用$count查询选项获得请求的实体总数。

查询 选项 描述
$count true 或 false 用于是否返回实体总数的统计结果

示例: 返回Things集合中所有数据及统计总数 [tabpanel] [tabpage header=HTTP id=count1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$count=true

[/tabpage] [tabpage header=JavaScript/jQuery id=count2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Things?$count=true",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=count3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Things?%24count=true"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Things?$count=true [/formtitle] [formbody]

[/formbody] [/formpanel]

filter

使用$filter查询选项可以进行对返回的属性值按条件进行筛选过滤。

  • 默认下,$filter视所有result为string(字符串型)
  • 例外情况,如返回Observations是作为Datastream的子结果返回,比如Datastreams(id)/Observations, 此时Datastream有一个observationType有一个observationType,此时$filter将视result为数字。
查询 选项 描述
$filter '属性/函数 操作符' 或者 函数 指定对结果进行过滤的方法

示例 1: 返回一个指定的Datastream中Observations,仅返回Observations的result比10小的所有数据。

[tabpanel] [tabpage header=JSON class=active id=filter1]

https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?$filter=result lt 10

[/tabpage] [tabpage header=JavaScript/jQuery id=filter2]

$.get("https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?$filter=result lt 10",function(response, status){
    console.log(response);
});

[/tabpage] [tabpage header=cURL id=filter3]

curl -X GET -H "Content-Type: application/json" "https://toronto-bike-snapshot.sensorup.com/v1.0/Datastreams(206051)/Observations?%24filter=result%20lt%2010"

[/tabpage] [/tabpanel]

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations?$filter=result lt 10 [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 2: 返回在一个指定时间之前的所有Observations。

[formpanel type=GET] [formtitle] /v1.0/Observations?$filter=phenomenonTime lt ‘2016-11-24T14:37:01.000Z’ [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 3: 返回所有location为Central Tech [-79.407,43.661]的所有Locations。

[formpanel type=GET] [formtitle] /v1.0/Locations?$filter=st_equals(location,geography’POINT(-79.407 43.661)’) [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 4: 返回Things的FeatureOfInterest,仅返回指定name以及指定时间为2017年1月至3月的数据。

[formpanel type=GET] [formtitle] /Things?$expand=Datastreams/Observations/FeatureOfInterest&$filter=Datastreams/Observations/FeatureOfInterest/name eq ‘7000:Ft. York / Capreol Crt.’ and Datastreams/Observations/phenomenonTime ge 2017-01-01T00:00:00.000Z and Datastreams/Observations/phenomenonTime le 2017-03-01T00:00:00.000Z [/formtitle] [formbody]

[/formbody] [/formpanel]

示例 5: 返回一个指定的,其内部Observations的result为2的Datastream。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)?$expand=Observations($filter=result eq 2) [/formtitle] [formbody]

[/formbody] [/formpanel]

Built-in Filter Operators

操作符 描述 示例
比较运算符    
eq 等于 /ObservedProperties?$filter=name eq 'Area Temperature'
ne 不等于 /ObservedProperties?$filter=name ne 'Area Temperature'
gt 大于 /Datastreams(id)/Observations?$filter=result gt 20.0
ge 大于或等于 /Datastreams(id)/Observations?$filter=result ge 20.0
lt 小于 /Datastreams(id)/Observations?$filter=result lt 100
le 小于或等于 /Datastreams(id)/Observations?$filter=result le 100
逻辑运算符    
and 逻辑与 /Datastreams(id)/Observations?$filter=result le 3.5 and FeatureOfInterest/id eq '1'
or 逻辑或 /Datastreams(id)/Observations?$filter=result gt 20 or result le 3.5
not 逻辑非 /Things?$filter=not startswith(description,'test')
分组运算符    
( ) 优先分组 /Datastreams(id)/Observations?$filter=(result sub 5) gt 10

Built-in Query Functions

函数 Example
字符串函数  
bool substringof(string searchString,string baseString) substringof('Sensor Things',description)
bool endswith(string baseString, string suffix) endswith(description,'Things')
bool startswith(string baseString, string prefix) startswith(description,'Sensor')
int length(string p0) length(description) eq 13
string tolower(string p0) tolower(description) eq 'sensor things'
string toupper(string p0) toupper(description) eq 'SENSOR THINGS'
日期函数  
int year year(resultTime) eq 2015
int month month(resultTime) eq 12
int day day(resultTime) eq 8
int hour hour(resultTime) eq 1
int minute minute(resultTime) eq 0
int second second(resultTime) eq 0
数学函数  
round round(result) eq 32
floor floor(result) eq 32
ceiling ceiling(result) eq 33
地理空间函数  
double geo.distance(Point p0, Point p1) geo.distance(location, geography'POINT (30 10)')
double geo.length(LineString p0) geo.length(geography'LINESTRING (30 10, 10 30, 40 40)')
bool geo.intersects(Point p0, Polygon p1) geo.intersects(location,geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
空间关系函数  
bool st_equals st_equals(location, geography'POINT (30 10)')
bool st_disjoint st_disjoint(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_touches st_touches(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_within st_within(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_overlaps st_overlaps(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')
bool st_crosses st_crosses(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_intersects st_intersects(location, geography'LINESTRING (30 10, 10 30, 40 40)')
bool st_contains st_contains(location, geography'POINT (30 10)')
bool st_relate st_relate(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))', 'T****')

resultFormat

使用$resultFormat查询选项以数组形式返回Observations。

Property Options Description
$resultFormat dataArray Enables returning Observations in data arrays.

示例 1: Returns all Observations of a specific Datastream in a data array to minimize metadata being returned from the server.

按照数组形式返回一个指定的Datastream的所有Observations,以最小化从服务器返回的元数据。

[formpanel type=GET] [formtitle] /v1.0/Datastreams(id)/Observations?$resultFormat=dataArray [/formtitle] [formbody]

[/formbody] [/formpanel]

Errors

SensorThings API 使用下列错误代码:

错误代码 含义
400 Bad Request – 您的请求不正确,可能是不正确的JSON内容,或者可能与服务器接受格式不符
401 Unauthorized – 未授权的,错误的API key
404 Not Found – 正在查找的资源不存在
405 Method not allowed – 请求了一种尚未在服务器上实现的方法
406 Not Acceptable – 请求的格式不是JSON
409 Conflict – 资源检查约束发生了冲突
410 Gone – 请求的资源已被删除
429 Too Many Requests – 目前负载太多,请稍后再试
500 Internal Server Error – 服务器有些问题,请稍后再试
503 Service Unavailable – 暂时离线进行维护,请稍后再试