【API說明】－民生公共物聯網-資料服務平台

$expand

$expand系統查詢選項指示內聯表示相關實體。$expand查詢選項的值應以逗號分隔的導航屬性名稱列表。此外，每個導航屬性後可跟一個斜線符號和另一個導航屬性，以便識別多級關係。

範例：$expand查詢選項的範例
請求範例1：

http://example.org/v1.0/Things?$expand=Datastreams

回應範例：

回應範例的 Json 文字字串如下：

回傳事物的實體集以及與每個 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 的 Datastreams 以及與此 Datastreams 關聯的 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 的 Datastreams 以及其結果等於 1 的 Observations 。

$select

$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系統查詢選項指定從服務返回項目的順序。$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系統查詢選項指定從實體集合返回的項目數限制。$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 desc

回應說明：

回傳按照時間降序排序後的前五個觀察項。

$skip

$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 實體。

$count

具有值為 true 的$count系統查詢選項指定匹配請求的集合中的項目總數應與結果一起回應。值為 false（或未指定）的$count查詢選項提示服務不應回應計數。如果指定的值不是 true 或 false，服務應返回 400 錯誤請求的 HTTP 狀態碼。$count系統查詢選項應忽略任何$top, $skip或$expand查詢選項，並且應該返回所有實體的總數，僅包括匹配任何指定的$filter的結果。客戶應該知道，由於計算計數和枚舉最後一個值或由於服務的不精確計算之間的延遲，內聯返回的計數可能與實際返回的項數不完全相同。

範例：$count查詢選項的範例
請求範例：

http://example.org/v1.0/Things?$count=true

回應範例：

回應範例的 Json 文字字串如下：

回傳 Things 實體以及實體的總數。

              {
                  "@iot.count": 2,
                  "value": [
                      {…},
                      {…}
                  ]
              }

$filter

$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'。

查詢選項

$expand

$select

$orderby

$top

$skip

$count

$filter

主辦單位

執行單位

合作單位

查詢選項

$expand

JsonJson 文字格式

$select

$orderby

$top

$skip

$count

JsonJson 文字格式

$filter

主辦單位

執行單位