---
# System prepended metadata

title: 氣象與空氣品質
tags: [IDA]

---

# 氣象與空氣品質

:::success
本應用實務依據``5G智慧杆系統技術規範``，為氣象與空氣品質數據提供標準化資料結構與接口規則，確保系統整合與資料交換的可靠性與一致性，協助地方單位及系統整合業者高效建立智慧環境監測平台。
:::

[toc]

## 欄位與資料定義

| 欄位名稱 | 格式 | 必備 | 說明 | 備註 |
| -------- | -------- | -------- | -------- | -------- |
| **廠商資訊** |				
| Vendor | String |	M |	廠商	| 記錄設備實際製造廠商名稱 |
| Model | String |	M |	型號 	| 記錄設備型號 |
| Serial | String |	M |	序號 	| 記錄設備唯一序號 |
| **系統與應用欄位** |	
| Token | String | M |	使用者身份驗證 Token |	API 安全憑證，所有請求需帶此欄位。 |
| DEVSNo | String	| M | 設備代碼 |  |
| timestamp	| String | M |	感測數據採樣時間 |  ISO 8601 日期格式 |
| **感測器資訊** |				
| Latitude | 數值 |	O |	經度	| 以度表示 |
| Longitude | 數值 |	O |	緯度 	| 以度表示 |
| Status | Enum	| M |		感測器狀態 (NORMAL, FAULT, MAINTENANCE, OFFLINE)	| 用來判斷感測器健康狀況 |
| errorCode | String | O |	錯誤代碼 | 發生異常時填寫，否則空值 |
| **氣象資訊** |				
| Temp | 數值 |	M |	溫度	| 以攝氏溫度表示  |
| RH | 數值	| M |	相對濕度	| 以百分比表示  |
| WindSpeed | 數值	| O |	風速	| meter/sec  |
| SolarRadiation | 數值	| O |	日射量	| MJ/m^2^  |
| **空氣品質資訊** |					
| PM25	| 數值 | M |	細懸浮微粒濃度(µg/m^3^)	| 環保監測核心數據 |
| PM10	| 數值 | O | 	懸浮微粒濃度(µg/m^3^)	|  |	 
| SO2	| 數值 | O |	ppb  | 二氧化硫 |
| CO	| 數值 | O |	ppm | 一氧化碳 |
| NO2	| 數值 | O	|  ppb | 	二氧化氮 |
| NO	| 數值 | O	|  ppb | 	一氧化氮 |
| O3	| 數值 | O	|  ppb | 	臭氧 |

## 資料結構與操作規則

### 資料結構範例 (JSON)

```json
{
  "Token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "DEVSNo": "AQSensor001",
  "timestamp": "2025-04-28T14:15:00Z",
  "Temp": 25.4,
  "RH": 60.3,
  "PM25": 15.7,
  "PM10": 28.4,
  "CO": 0.4,
  "NO2": 12.1,
  "NO": 2.9,
  "O3": 20.5,
  "Status": "NORMAL",
  "errorCode": "",
}
```

### 操作規則

| 操作 | 說明 | 輸入內容 | 備註 |
| -------- | -------- | -------- | -------- |
| 新增 |	上報感測器數據	| 完整必填欄位及狀態資訊	| DEVSNo唯一識別，時間戳必須合理。 |
| 查詢 |	根據條件查詢歷史或即時感測資料	| Token、DEVSNo、時間區間等	| 支援分頁，避免大量資料一次回傳。 |
| 修改 |	更新感測器狀態或補充說明 |	Token、DEVSNo 及變更欄位 |	僅限狀態、錯誤碼及備註，不可更改設備基本參數。|
| 刪除 |	刪除感測器資料紀錄 |	Token、DEVSNo 及時間條件	| 謹慎操作，需記錄日誌。|


### Token 使用注意事項

* 透過 Token 控制授權。
* 所有通訊須使用 HTTPS 保障資料安全。
* Token 過期須重新認證，API拒絕無效 Token 的請求。

### 資料交換頻率

* 即時環境監控建議每5分鐘更新一次資料。
* 可視需求調整批次上報頻率。

### 錯誤處理與回應格式

| 錯誤碼 | 含義 | 建議處理方式 |
| -------- | -------- | -------- |
| 400	| 請求格式或資料錯誤	| 檢查 JSON 格式、必填欄位、資料合理性。|
| 401	| Token 無效或缺失	| 重新登入獲取有效 Token |
| 403	| 權限不足	| 確認使用者權限 |
| 404	| 查無資料	| 檢查輸入設備ID及查詢條件 |
| 409	| 資料衝突	| 避免重複新增或不合理狀態更新 |
| 500	| 伺服器內部錯誤	| 稍後再試，並向系統管理員回報問題。|

* 成功回應範例
```json
{
  "code": 200,
  "message": "感測資料回傳成功",
  "data": {}
}
```
## 資料格式與代碼支援

### JSON 格式

* 明確結構化數據，方便API前後端對應。

### 狀態說明

| 狀態值 | 說明 |
| -------- | -------- |
| Active     | 已啟用 / 運作中     |
| Inactive     | 已停用 / 未運作     |


### 測試資料建議

* 建議提供多筆測試資料涵蓋正常與異常狀態情境。
* 建議以模擬感測器裝置進行接口測試，驗證數據格式及狀態同步功能。

### 版本控管建議

* API及資料格式應明確標示版本號，方便後續維護。
