API Cảm biến
API Cảm biến của SmartTwin cho phép bạn tương tác với dữ liệu cảm biến từ các thiết bị IoT đã được kết nối. Bạn có thể truy vấn dữ liệu lịch sử, nhận dữ liệu thời gian thực và quản lý cấu hình cảm biến.
Cấu trúc dữ liệu cảm biến
Mỗi điểm dữ liệu cảm biến thường có cấu trúc sau:
{
"sensorId": "string",
"timestamp": "ISO 8601 datetime string",
"value": "number | string | boolean",
"unit": "string (optional)",
"location": {
"latitude": "number",
"longitude": "number",
"floor": "string (optional)",
"room": "string (optional)"
},
"metadata": {
"key": "value" (optional)
}
}
Điểm cuối API
1. Lấy dữ liệu cảm biến lịch sử
Truy vấn dữ liệu cảm biến trong một khoảng thời gian cụ thể.
GET /api/sensors/example-sensor-id/data
Tham số truy vấn:
startTime
(bắt buộc): Thời gian bắt đầu (ISO 8601).endTime
(bắt buộc): Thời gian kết thúc (ISO 8601).interval
(tùy chọn): Khoảng thời gian tổng hợp dữ liệu (ví dụ: "1h", "30m", "1d"). Mặc định là dữ liệu thô.limit
(tùy chọn): Số lượng bản ghi tối đa trả về. Mặc định là 100.
Ví dụ phản hồi:
[
{
"timestamp": "2023-10-26T10:00:00Z",
"value": 25.5,
"unit": "°C"
},
{
"timestamp": "2023-10-26T11:00:00Z",
"value": 26.1,
"unit": "°C"
}
]
2. Lấy thông tin cảm biến
Lấy thông tin chi tiết về một cảm biến cụ thể.
GET /api/sensors/example-sensor-id
Ví dụ phản hồi:
{
"sensorId": "temp-sensor-001",
"name": "Cảm biến nhiệt độ phòng A101",
"type": "temperature",
"buildingId": "building-alpha",
"location": {
"floor": "1",
"room": "A101"
},
"status": "active",
"lastReading": {
"timestamp": "2023-10-26T11:30:00Z",
"value": 26.3,
"unit": "°C"
}
}
3. Cập nhật cấu hình cảm biến
Cập nhật các thuộc tính của một cảm biến.
PUT /api/sensors/example-sensor-id
Body yêu cầu (JSON):
{
"name": "Cảm biến nhiệt độ phòng họp lớn",
"location": {
"room": "Meeting Room 203"
}
}
Ví dụ phản hồi:
{
"message": "Sensor configuration updated successfully."
}
4. Đăng ký cảm biến mới
Thêm một cảm biến mới vào hệ thống.
POST /api/sensors
Body yêu cầu (JSON):
{
"sensorId": "new-humidity-sensor-005",
"name": "Cảm biến độ ẩm kho",
"type": "humidity",
"buildingId": "building-beta",
"location": {
"floor": "ground",
"area": "warehouse"
}
}
Ví dụ phản hồi:
{
"message": "Sensor registered successfully.",
"sensorId": "new-humidity-sensor-005"
}
WebSockets cho dữ liệu thời gian thực
Để nhận dữ liệu cảm biến theo thời gian thực, bạn có thể thiết lập kết nối WebSocket đến điểm cuối sau:
ws://your-smarttwin-app.com/ws/sensors/data
Sau khi kết nối, bạn có thể gửi tin nhắn JSON để đăng ký nhận dữ liệu từ các cảm biến cụ thể:
{
"action": "subscribe",
"sensorIds": ["temp-sensor-001", "light-sensor-002"]
}
Bạn sẽ nhận được các tin nhắn JSON chứa dữ liệu cảm biến mới nhất khi có sự thay đổi:
{
"sensorId": "temp-sensor-001",
"timestamp": "2023-10-26T11:35:15Z",
"value": 26.5,
"unit": "°C"
}