歡迎使用SensorThings API教學服務,以下說明介紹幫助您了解API各項介面功能,如果有任何疑問,歡迎您留言給我們,我們會儘速回答相關問題。
URI介面
OGC SensorThings API 服務將相同類型的實體分組為實體集合。每個實體都有唯一的標識符和一對多屬性。此外,如果實體與其他實體集合中的實體保持關係,則這種類型的關係用導航屬性(即navigationLink和associationLink)表示。
因此,為了對資源執行查詢,第一步是通過URI尋址目標資源。這裡有使用三個主要組成部分的URI,即:(1)網路服務之URI,(2)資源的路徑,以及(3)查詢選項。另外,服務之URI由兩部分組成:(1)SensorThings服務的位置和(2)版本號。版本號的格式如下所示:
“v” majorversionnumber + “.” + minorversionnumber
通過在服務URI之後附加資源路徑,客戶端可以處理不同類型的資源,例如實體集合,實體,屬性或導航屬性。最後,客戶端可以在資源路徑之後應用查詢選項來進一步處理已處理的資源,例如按屬性進行排序或按條件進行篩選。
資源路徑
資源路徑位於服務URI後面,可用於指定不同的資源。以下列出資源路徑的用法。
URL模式:SERVICE_ROOT_URL
回應:一個名為value的屬性的JSON物件,其中包含SensorThings服務的每個實體集合的一個元素。
每個元素應該是一個帶有至少兩個名稱/值對的JSON物件,其中一個名稱包含實體集合的名稱(例如:Things, Locations, Datastreams, Observations, ObservedProperties和Sensors),以及另一個名稱包含URL實體集合,可能是絕對或相對的URL。
範例:一個沒有資源路徑的SensorThings的請求
請求範例:
http://example.org/v1.0/
回應範例:
{
"value": [
{
"name": "Things",
"url": "http://example.org/v1.0/Things"
},
{
"name": "Locations",
"url": " http://example.org/v1.0/Locations"
},
{
"name": "Datastreams",
"url": " http://example.org/v1.0/Datastreams"
},
{
"name": "Sensors",
"url": " http://example.org/v1.0/Sensors"
},
{
"name": "Observations",
"url": " http://example.org/v1.0/Observations"
},
{
"name": "ObservedProperties",
"url": " http://example.org/v1.0/ObservedProperties"
},
{
"name": "FeaturesOfInterest",
"url": " http://example.org/v1.0/FeaturesOfInterest"
}
]
}
為了指定一個實體集合,用戶可以將實體集合名稱放在服務URI之後。該服務返回具有value屬性的JSON物件,內含指定實體集合中實體的列表。
URL模式:SERVICE_ROOT_URI / ENTITY_SET_NAME
回應:強制執行沒有服務驅動分頁時,指定實體中的所有實體(包含所有屬性)的列表。該響應內含該實體集合之實體內容。一個空集合表示該集合未含任何實體。
計數屬性(@iot.count)代表集合中的實體數量。
當強制執行服務驅動分頁時,nextLink註釋將包含在結果的回應中。
範例:指定位置給一組實體
請求範例:
http://example.org/v1.0/ObservedProperties
回應範例:
{
"@iot.count":84
"value": [
{
"@iot.id": 1,
"@iot.selfLink":"http://example.org/v1.0/ObservedProperties(1)",
"Datastreams@iot.navigationLink":"ObservedProperties(1)/Datastreams",
"description": "The dew point is the temperature at which the water vapor in air at constant barometric pressure condenses into liquid water at the same rate at which it evaporates.",
"name": "DewPoint Temperature",
"definition":"http://dbpedia.org/page/Dew_point"
},
{
"@iot.id ": 2,
"@iot.selfLink":"http://example.org/v1.0/ObservedProperties(2)",
"Datastreams@iot.navigationLink": "ObservedProperties(2)/Datastreams",
"description": "Relative humidity is the ratio of the partial pressure of water vapor in an air-water mixture to the saturated vapor pressure of water at a prescribed temperature.",
"name": "Relative Humidity",
"definition":"http://dbpedia.org/page/Relative_humidity"
},
{…},
{…},
{…}
] "@iot.nextLink":"http://example.org/v1.0/ObservedProperties?$top=5&$skip=5"
}
用戶可以通過將實體的唯一標識符放置在大括號”()”之後並放在實體集合名稱後面,來指定實體集中的特定實體。該服務然後返回具有其所有屬性的實體。
URL模式:SERVICE_ROOT_URI/ENTITY_SET_NAME(ID_OF_THE_ENTITY)
回應:實體的JSON物件(及其所有屬性),用於在實體集中保存指定的ID。
範例:取得Thing id為1之實體的範例請求
請求範例:
http://example.org/v1.0/ObservedPropertieshttp://example.org/v1.0/Things(1)
用戶可以通過在實體的URI之後加入屬性名稱來指定實體的屬性。該服務然後返回指定屬性的值。如果該屬性具有複雜的類型值,那麼可以通過進一步的屬性名稱組合來指定該值的屬性。
如果該屬性是單值且具有空值,則服務應以204無內容作出回應。如果該屬性不可用(例如由於權限),則該服務應以404 Not Found回應。
URL模式:SERVICE_ROOT_URI / RESOURCE_PATH_TO_AN_ENTITY / PROPERTY_NAME
回應:在實體集中保存ID的實體的指定屬性。
範例:指定實體屬性的範例請求
請求範例:
http://example.org/v1.0/Observations(1)/resultTime
回應範例:
{
"resultTime": "2010-12-23T10:20:00-07:00"
}
為了指定原始屬性的原始值,客戶端將包含字符串$value的路徑段附加到屬性URL。
其中,TM_Object類型的默認格式是使用ISO8601格式的text / plain格式,例如TM_Period的2014-03-01T13:00:00Z / 2015-05-11T15:30:00Z和TM_Instant的2014-03-01T13:00:00Z。
URL模式:SERVICE_ROOT_URI/ENTITY_SET_NAME(ID_OF_THE_ENTITY)/PROPERTY_NAME/$value
回應:在實體集合中具特定id的實體之指定屬性的原始值。
範例:指定實體屬性的範例請求
請求範例:
http://example.org/v1.0/Observations(1)/resultTime
回應範例:
2015-01-12T23:00:13-07:00
由於不同實體集合中的實體可能存在一些關係,因此用戶可以通過實體的導航屬性來請求鏈接的實體。該服務將返回與指定實體保持特定關係的一個或多個實體。
URL模式:SERVICE_ROOT_URI / ENTITY_SET_NAME(ID_OF_THE_ENTITY)/ LINK_NAME
回應:與指定實體保持一定關係的一個實體或多個實體。
範例:針對導航屬性之位置的請求範例
請求範例:
http://example.org/v1.0/Datastreams(1)/Observations
回應範例:返回包含id為1的Datastream中的所有Observations。
由於不同實體集合中的實體可能存在一些關係,因此用戶可以通過指定實體的關聯鏈接來請求鏈接實體的自鏈接。associationLink可用於檢索對與當前實體相關的實體或實體集合的引用。解析相關鏈接時,僅返回相關實體的自鏈接。
URL模式:SERVICE_ROOT_URI/ENTITY_SET_NAME(KEY_OF_THE_ENTITY)/LINK_NAME/$ref
回應:具有值屬性的JSON物件。value屬性的值是一個JSON數組,每個associationLink包含一個元素。每個元素都是一個帶有名稱/值對的JSON物件。名稱是url,值是相關實體的selfLinks。
範例:指定關聯鏈接到associationLink的範例
請求範例:
http://example.org/v1.0/Datastreams(1)/Observations/$ref
回應範例:
{
"value": [
{
"@iot.selfLinks": "http://example.org/v1.0/Observations(1)"
},
{
"@iot.selfLinks": "http://example.org/v1.0/Observations(2)"
}
]
}
由於用戶可以使用導航屬性從一個實體集鏈接到另一個實體集,因此用戶可以使用唯一標識符,屬性或鏈接(即用法3、4和6)進一步擴展資源路徑。
範例:嵌套資源路徑的例子
範例請求1:
http://example.org/v1.0/Datastreams(1)/Observations(1)
在Datastream中回傳一個特定的Observation實體。
範例請求2:
http://example.org/v1.0/Datastreams(1)/Observations(1)/resultTime
在Datastream中轉換指定Observation的resultTime屬性。
範例請求3:
http://example.org/v1.0/Datastreams(1)/Observations(1)/FeatureOfInterest
返回Datastream中指定Observation的FeatureOfInterest實體。
查詢運算符
客戶向OGC SensorThings API服務發送HTTP GET請求以獲取數據。URL的資源路徑指定了請求的目標。其他查詢運算符可以通過查詢選項指定,顯示如下。
查詢運算符前綴為美元($)字符,並在請求URI中的問號(?)後面指定為鍵值對。許多OGC SensorThings API的查詢選項都是根據OData的查詢選項進行調整的。
查詢選項
$select和$expand系統查詢選項使客戶端能夠指定要包含在回應中的一組屬性。
OGC SensorThings API適用於許多OData的系統查詢選項及其使用情況。這些查詢選項允許優化請求。
服務請求的結果根據查詢選項按以下順序進行評估。
在應用任何服務驅動的分頁之前:
在應用任何服務驅動的分頁之後:
SensorThings API教學:
OGC SensorThings API服務將相同類型的實體分組為實體集合。每個實體都有唯一的標識符和一對多屬性。此外,如果實體與其他實體集合中的實體保持關係,則這種類型的關係用導航屬性(即navigationLink和associationLink)表示。 因此,為了對資源執行查詢,第一步是通過URI尋址目標資源。
以下API教學以空氣品質類之資料為範例加以說明:
資料來源(URI)路徑:
首先需取得資料服務的來源URI路徑:
https://sta.ci.taiwan.gov.tw/資料類別/v1.0/
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/
不知道URI的組成嗎? 請看這裡 URI組成說明
查詢選項:
$expand系統查詢選項指示內聯表示相關實體。$expand查詢選項的值應以逗號分隔的導航屬性名稱列表。此外,每個導航屬性後可跟一個斜線符號和另一個導航屬性,以便識別多級關係。
範例:$expand查詢選項的範例
範例請求1:
http://example.org/v1.0/Things?$expand=Datastreams
回傳事物的實體集以及與每個Thing實體關聯的每個Datastream。
回應範例:
{
"values":[{
"@iot.id": 1,
"@iot.selfLink": "http://example.org/v1.0/Things(1)",
"Locations@iot.navigationLink": "Things(1)/Locations",
"Datastreams@iot.count":1,
"Datastreams": [{
"@iot.id": 1,
"@iot.selfLink": "http://example.org/v1.0/Datastreams(1)",
"name": "oven temperature",
"description": "This is a datastream measuring the air temperature in an oven.",
"unitOfMeasurement": {
"name": "degree Celsius",
"symbol": "°C",
"definition": "http://unitsofmeasure.org/ucum.html#para-30"
},
"observationType":http://www.opengis.net/def/observationType/OGCOM/2.0/OM_Measurement",
"observedArea": {
"type": "Polygon",
"coordinates": [[[100,0],[101,0],[101,1],[100,1],[100,0]]]
},
"phenomenonTime": "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z",
"resultTime": "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z"
}],
"HistoricalLocations@iot.navigationLink": "Things(1)/HistoricalLocations",
"description": "This thing is a convection oven.",
"name": "Oven",
"properties": {
"owner": "John Doe",
"color": "Silver"
}
}]
}
範例請求2:
http://example.org/v1.0/Things?$expand=Datastreams/ObservedProperty
回傳Thing的集合,與每個Thing關聯的Datastreams以及與每個Datastream關聯的ObservedProperty。
範例請求3:
http://example.org/v1.0/Datastreams(1)?$expand=Observations,ObservedProperty
回傳id為1的Datastream以及與此Datastream關聯的Observations和ObservedProperty。
查詢選項可以通過在導航屬性名稱中附加括號中包含的以分號分隔的查詢選項列表來應用於擴展導航屬性。允許的系統查詢選項是$filter, $select, $orderby, $skip, $top, $count和$expand。
範例請求4:
http://example.org/v1.0/Datastreams(1)?$expand=Observations($filter=result eq 1)
回傳id為1的Datastream以及其結果等於1的Observations。
$select系統查詢選項請求服務僅返回客戶端顯式請求的屬性。$select查詢選項的值應該是逗號分隔的選擇子句列表。每個選擇條款應為屬性名稱(包括導航屬性名稱)。在響應中,服務應返回指定的內容(如果可用)以及任何可用的擴展導航屬性。
範例請求1:
http://example.org/v1.0/Observations?$select=result,resultTime
僅回傳每個Observation實體的result和resultTime屬性。
範例請求2:
http://example.org/v1.0/Datastreams(1)?$select=id,Observations&$expand=Observations/FeatureOfInterest
回傳Datastream實體的id屬性以及由Observations和FeatureOfInterest導航屬性標識的實體的所有屬性。
範例請求3:
http://example.org/v1.0/Datastreams(1)?$expand=Observations($select=result)
回傳id為1的Datastream以及由Observations導航屬性標識的實體的結果屬性。
$orderby系統查詢選項指定從服務返回項目的順序。$orderby系統查詢選項的值應包含逗號分隔的表達式列表,其原始結果值用於對項目進行排序。
表達式可以包含後綴asc,用於升序或降序以便降序,與屬性名稱相隔一個或多個空格。如果未指定asc或desc,則服務應按指定的屬性以升序排列。
在按降序排序時,空值應該在非空值之前,非空值在非空值之後。
項目應根據第一個表達式的結果值進行排序,然後將第一個表達式的值相同的項目按第二個表達式的結果值排序,依此類推。
範例:$orderby查詢選項的例子
範例請求1:
http://example.org/v1.0/Observations?$orderby=result
回傳結果屬性按升序排列的所有Observation實體。
範例請求2:
http://example.org/v1.0/Observations?$expand=Datastream&$orderby=Datastreams/id desc, phenomenonTime
以降序回傳由鏈接的Datastream實體的id屬性排序的所有Observation,然後按照觀測值的現象屬性升序排列。
$top系統查詢選項指定從實體集合返回的項目數限制。$top系統查詢選項的值應該是一個非負整數n。該服務應返回可用項目的數量,但不得大於指定值n。
如果沒有通過$orderby查詢選項執行排序,則服務應對包含$top的請求實施固定邏輯之排序。
範例:$top查詢選項的範例
範例請求1:
http://example.org/v1.0/Things?$top=5
只回傳Things集合中的前五個實體。
範例請求2:
http://example.org/v1.0/Observations?$top=5&$orderby=phenomenonTime%20desc
回傳按照時間降序排序後的前五個觀察項。
$skip系統查詢選項指定查詢集合中將從結果中排除的實體數量。$skip系統查詢選項的值應該是一個非負整數n。服務應從位置n
+1開始返回實體。
在$top和$skip一起使用的情況下,$skip應該在$top之前應用,無論它們在請求中出現的順序如何。
如果沒有通過$orderby查詢選項執行排序,則服務應對包含$skip的請求執行固定邏輯的排序。
範例:$skip查詢選項的範例
範例請求1:
http://example.org/v1.0/Things?$skip=5
從Things集合中的第六個Thing實體開始回傳Thing實體。
範例請求2:
http://example.org/v1.0/Observations?$skip=2&$top=2& $orderby=resultTime
在集合按resultTime屬性升序排列時,從所有Observation實體的集合中返回第三個和第四個Observation實體。
具有值為true的$count系統查詢選項指定匹配請求的集合中的項目總數應與結果一起回應。值為false(或未指定)的$count查詢選項提示服務不應回應計數。
如果指定的值不是true或false,服務應返回400錯誤請求的HTTP狀態碼。
$count系統查詢選項應忽略任何$top,
$skip或$expand查詢選項,並且應該返回所有實體的總數,僅包括匹配任何指定的$filter的結果。客戶應該知道,由於計算計數和枚舉最後一個值或由於服務的不精確計算之間的延遲,內聯返回的計數可能與實際返回的項數不完全相同。
範例:$count查詢選項的範例
範例請求1:
http://example.org/v1.0/Things?$count=true
回傳Things實體以及實體的總數。
回應範例:
{
"@iot.count": 2,
"value": [
{…},
{…}
]
}
$filter系統查詢選項允許客戶端過濾由請求URL尋址的實體集合。使用$filter指定的表達式針對集合中的每個實體進行評估,並且只有表達式評估為true的實體才會包含在回應中。表達式計算為false或null的實體,或者由於權限而不可用的引用屬性,應從回應中省略。
$filter運算符中使用的表達式語言應支持對屬性和文字的引用。字面值應該是用單引號,數字和布爾值(true或false)或日期時間值表示為ISO
8601時間字符串的字符串。
範例:$filter查詢選項的例子
範例請求1:
http://example.org/v1.0/Observations?$filter=result lt 10.00
回傳結果小於10.00的所有Observations。另外,客戶端可以選擇在$filter謂詞中使用鏈接實體的屬性。以下是SensorThings服務的數據模型中$filter可能用法的範例。
範例請求2:
http://example.org/v1.0/Observations?$filter=Datastream/id eq'1'
回傳Datastream id為1的所有Observation實體。
範例請求3:
http://example.org/v1.0/Things?$filter=geo.distance(Locations/location, geography'POINT(-122, 43)') gt 1
回傳距離Thing實體已知位置和POINT(-122 43)大於1的Thing實體。
範例請求4:
http://example.org/v1.0/Things?$expand=Datastreams/Observations/FeatureOfInterest&$filter=Datastreams/Observations/FeatureOfInterest/ideq 'FOI_1' and Datastreams/Observations/resultTime ge 2010-06-01T00:00:00Z and Datastreams/Observations/resultTime le 2010-07-01T00:00:00Z
回傳Things實體,其具有位在2010年6月Observations之FeatureOfInterest id等於'FOI_1'。
OGC SensorThings API支持一組內置過濾器的操作,如下表所述。
Things:
Thing可能是一個物理世界的物件,也可能是資訊世界(虛擬的物體),可被識別和整合進入通訊網路[ITU-T Y.2060]。
Thing是創建SensorThings模型結構的起點,一個Thing有Location(位置)和一個或多個Datastreams(資料流)來Observation(觀測)。
GET
範例1:取回所有Thing
GET /v1.0/Things
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/Things
範例2:取回一個指定的Thing
GET /v1.0/Things(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/Things(1)
範例3:使用$expand
使用 $expand 查詢選項,取回一個Thing和其所包含的實體(entity),可取回多實體集合或單一實體。
$expand相關實體 | 描述 |
---|---|
Locations | 展示Thing實體內Location詳細內容 |
Datastreams | 展示Thing實體內Datastreams詳細內容 |
HistoricalLocations | 展示Thing實體內HistoricalLocations詳細內容 |
GET /v1.0/Things(id)?$expand=Datastreams
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/Things(1)?$expand=Datastreams
範例4:使用$select
取回一個指定的Thing的特定屬性。
$select查詢屬性 | Description |
---|---|
name | Thing的實體名稱 |
description | Thing的實體描述 |
properties | Thing的實體屬性 |
Locations | Thing實體的最終已知位置 |
Datastreams | Thing實體觀測資料之集合,由相同的Sensor產生 |
HistoricalLocations | Thing實體之歷史位置與軌跡 |
GET /v1.0/Things(id)?$select=description
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/Things(1)?$select=description
Locations:
Location(位置)實體記錄 Thing(s)關聯的位置。一個 Thing 的 Location 實體被定義為 Thing 最後已知的位置(物理位置)。
當一個 location(物理位置)存在多種 encodingType(編碼類型)時,此時的 Thing 可關聯多個 Locations。
GET
範例1:取回所有的 Location
GET /v1.0/Locations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Locations
範例2:使用 id 取回一個指定的 Location
GET /v1.0/Locations(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Locations(1)
範例3:使用 Thing id
GET /v1.0/Things(id)/Locations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Things(1)/Locations
範例4:使用$expand
使用 $expand 查詢選項,取回一個指定的 Location 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
Things | 展示Location 實體內Thing 詳細內容 |
HistoricalLocations | 展示Location 實體內HistoricalLocations 詳細內容 |
GET /v1.0/Locations(id)?$expand=Things
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Locations(1)?$expand=Things
範例5:使用 filter (空間查詢)
取回指定的多邊形中的所有Locations,並擴展到Thing 實體來取回所有元數據。
GET /v1.0/Locations?$expand=Things&$filter=geo.intersects(Locations/location,geography'POLYGON ((-79.39 43.651,-79.371 43.651,-79.371 43.641,-79.39 43.641,-79.39 43.651))')
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality/v1.0/Locations?$expand=Things&$filter=geo.intersects(Locations/location,geography'POLYGON((120.9 25.3,120.8 24.7,121.9 24.6,122.1 25.3,120.9 25.3))')&$count=true
範例6:使用select
從指定Location 中取回特定的屬性。
$select查詢屬性 | Description |
---|---|
name | Location 的實體名稱 |
description | Location 的實體描述 |
encodingType | Location 的編碼類型 |
location | Location 屬性的內容 |
Thing | 物聯網物件,一個物理世界或虛擬世界的物件,可被辨識或結合至通訊網路 |
HistoricalLocations | Thing 物件之歷史位置與軌跡 |
GET /v1.0/Locations(id)?$select=description
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Locations(1)?$select=description
HistoricalLocations:
Thing 的 HistoricalLocation(歷史位置)單元提供了 Thing 的當前(最後已知)和之前所有 locations 的時間。
GET
範例1:取回所有的 HistoricalLocations。
GET /v1.0/HistoricalLocations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/HistoricalLocations
範例2:取回一個指定的 HistoricalLocation。
GET /v1.0/Locations(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Locations(1)
範例3:使用$expand
使用 $expand 查詢選項,取回一個指定的HistoricalLocations 和其所包含的相關實體資訊。
$expand相關實體 | 描述 |
---|---|
Locations | 展示HistoricalLocation 實體內Location 詳細內容 |
Thing | 展示HistoricalLocation 實體內Thing 詳細內容 |
GET /v1.0/HistoricalLocations(id)?$expand=Locations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/HistoricalLocations(1)?$expand=Locations
範例4:使用select
從指定 HistoricalLocations 中取回特定的屬性。
$select查詢屬性 | 描述 |
---|---|
time | HistoricalLocations 的時間 |
Locations | Thing 物件的已知位置 |
Thing | 物聯網物件,一個物理世界或虛擬世界的物件,可被辨識或結合至通訊網路 |
GET /v1.0/HistoricalLocations(id)?$select=time
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/HistoricalLocations(1)?$select=time
Datastreams:
同一個Sensor(感測器)測量同一個ObservedProperty(觀測屬性)Observations(觀測)的集合,稱之為Datastream(資料流)。
GET
範例1:取回所有的 Datastreams。
GET /v1.0/Datastreams
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Datastreams
範例2:使用id 取回一個指定的 Datastreams。
GET /v1.0/Datastreams(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Datastreams(1)
範例3:使用Thing id
GET /v1.0/Things(id)/Datastreams
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Things(1)/Datastreams
範例4:使用$expand
使用 $expand 查詢選項,取回一個指定的 Datastream 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
Things | 展示Datastream 實體內Thing 詳細內容 |
Sensor | 展示Datastream 實體內Sensor 詳細內容 |
ObservedProperty | 展示Datastream 實體內ObservedProperty 詳細內容 |
Observations | 展示Datastream 實體內Observations 詳細內容 |
GET /v1.0/Datastreams(id)?$expand=Observations,ObservedProperty
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Datastreams(1)?$expand=Observations,ObservedProperty
範例5:使用select
從指定 Datastream 中取回特定的屬性。
$select查詢屬性 | 描述 |
---|---|
name | Datastreams 的實體名稱 |
description | Datastreams 的實體描述 |
unitOfMeasurement | 此Datastream 之觀測結果所帶有的單位 |
observationType | Observation 的類型(具有唯一的結果類型),服務使用該類型來對觀察值進行編碼 |
observedArea | 此Datastream 的所有FeaturesOfInterest 的涵蓋範圍 |
phenomenonTime | 此Datastream 的所有觀測結果之時間區間 |
resultTime | 此Datastream 的所有觀測結果之結果時間區間 |
Thing | 從Datastream 到Thing 的鏈接間 |
Sensor | 針對現象或屬性進行觀測獲得評估值之裝置 |
ObservedProperty | 此Datasteam 所觀測的現象 |
Observations | 針對特定現象產生評估結果的量測行為 |
GET /v1.0/Datastreams(id)?$select=description,unitOfMeasurement
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Datastreams(1)?$select=description,unitOfMeasurement
Sensors:
同一個Sensor(感測器)測量同一個ObservedProperty(觀測屬性)Observations(觀測)的集合,稱之為Datastream(資料流)。
GET
範例1:取回所有的 Sensor
GET /v1.0/Sensors
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Sensors
範例2:使用id 取回一個指定的 Sensor。
GET /v1.0/Sensors(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Sensors(1)
範例3:使用$expand
使用 $expand 查詢選項,取回一個指定的Sensors 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
Datastreams | 展示Sensor 實體內Datastreams 詳細內容 |
GET /v1.0/Sensors(id)?$expand=Datastreams
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Sensors(1)?$expand=Datastreams
範例4:使用select
從指定 Sensor 中取回特定的屬性。
$select查詢屬性 | 描述 |
---|---|
name | Sensor 的實體名稱 |
description | Sensor 的實體描述 |
encodingType | metadata 屬性的編碼類型 |
metadata | Sensor 或系統的詳細描述, 描述類型由encodingType 定義 |
Datastreams | 觀測資料之集合,由相同的Sensor 產生 |
GET /v1.0/Sensors(id)?$select=description
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Sensors(1)?$select=description
ObservedProperty:
一個ObservedProperty 特指一個觀測值(Observation)的現象。
GET
範例1:取回所有的 ObservedProperty
GET /v1.0/ObservedProperties
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/ObservedProperties
範例2:使用id 取回一個指定的 ObservedProperty
GET /v1.0/ObservedProperties(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/ObservedProperties(1)
範例3:使用$expand
使用 $expand 查詢選項,取回一個指定的ObservedProperty 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
name | ObservedProperty 的實體名稱 |
definition | 定義ObservedProperty 的URI |
description | ObservedProperty 的實體描述 |
Datastreams | 觀測資料之集合,由相同的Sensor 產生 |
GET /v1.0/ObservedProperties(id)?$select=description
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/ObservedProperties(1)?$select=description
Observation:
一個Observation(觀測)是一種測量或者是計算一個屬性值的行為,SensorThings API 中的一個Observation 代表一個ObservedProperty中單個Sensor 的讀取值。
一個物理設備(Sensor)發送Observations 給一個指定的Datastream。同時,一個Observation 需要一個FeatureOfInterest(感興趣圖徵)實體。
如果請求中沒有提供FeatureOfInterest,此Datastream 所關聯的Thing 之Location 將被視作此Observation 的FeatureOfInterest。
GET
範例1:取回所有的 Observation
GET /v1.0/Observations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Observations
範例2:使用id 取回一個指定的 Observation
GET /v1.0/Observations(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Observations(1)
範例3:使用 Datastream id
GET /v1.0/Datastreams(id)/Observations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Datastreams(1)/Observations
範例4:使用$expand
使用 $expand 查詢選項,取回一個Observation 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
Datastreams | 展示Observations 實體內Datastreams 詳細內容 |
FeatureOfInterest | 展示Observations 實體內FeatureOfInterest 詳細內容 |
GET /v1.0/Observations(id)?$expand=Datastream
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Observations(1)?$expand=Datastream
範例5:使用 select
取回一個指定的Observation 的特定屬性。
$select查詢屬性 | 描述 |
---|---|
phenomenonTime | 觀測發生的時刻或時間區間 |
result | 對ObservedProperty 觀測所得之估計值 |
resultTime | 觀測結果產生的時間 |
resultQuality | 描述觀測結果的品質 |
validTime | 觀測結果可以使用的時間區間 |
parameters | 描述觀測期間的環境條件或設定 |
Datastreams | 觀測資料之集合,由相同的Sensor 產生 |
FeatureOfInterest | 觀測時所針對的圖徵 |
GET /v1.0/Observations(id)?$select=phenomenonTime,result
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/Observations(1)?$select=phenomenonTime,result
FeatureOfInterest:
FeatureOfInterest(感興趣圖徵)為一個Observation 所觀測的圖徵。若為在地感測器,FeatureOfInterest 將為Thing 之Location。
若為遙測感測器,FeatureOfInterest 將為該Observation 所觀測之圖徵或區域。
GET
範例1:取回所有的FeaturesOfInterest。
GET /v1.0/FeaturesOfInterest
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/FeaturesOfInterest
範例2:使用id 取回一個指定的 FeaturesOfInterest
GET /v1.0/FeaturesOfInterest(id)
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/FeaturesOfInterest(1)
範例3:使用$expand
使用 $expand 查詢選項,取回一個指定的FeatureOfInterest 和其所包含的實體。
$expand相關實體 | 描述 |
---|---|
Observations | 針對特定現象產生評估結果的量測行為 |
GET /v1.0/FeaturesOfInterest(id)?$expand=Observations
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/FeaturesOfInterest(1)?$expand=Observations
範例4:使用 select
取回一個指定的 FeaturesOfInterest 的特定屬性。
$select查詢屬性 | 描述 |
---|---|
name | FeatureOfInterest 實體名稱 |
description | FeatureOfInterest 實體描述 |
encodinType | FeatureOfInterest 屬性的編碼類型 |
feature | 該圖徴的詳細說明。資料類型由encodingType 定義。 |
Observations | 針對特定現象產生評估結果的量測行為 |
GET /v1.0/FeaturesOfInterest(id)?$select=description
此範例為空氣品質類之資料來源路徑:
https://sta.ci.taiwan.gov.tw/STA_AirQuality_EPAIoT/v1.0/FeaturesOfInterest(1)?$select=description