sajad-dev/Backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35f4d09225d158e9f178418a58ffe4b90ad495ee
Backend/device_hub/API_GUIDE.md
T
sajad-dev 35f4d09225 UPDATE
2026-05-05 23:54:44 +03:30

735 lines
17 KiB
Markdown
Raw Blame History

# Device Hub API Guide
این فایل مستند API های تعریف‌شده در `device_hub/urls.py` را توضیح می‌دهد. مسیر پایه این API ها طبق `config/urls.py` برابر است با:
- `api/device-hub/`
بیشتر endpointها نیاز به احراز هویت کاربر دارند و معمولاً با ساختار زیر پاسخ می‌دهند:
```json
{
"code": 200,
"msg": "success",
"data": {}
}
```
## نحوه ارتباط با API ها
### 1) احراز هویت
- برای بیشتر endpointها باید کاربر لاگین باشد.
- معمولاً توکن را در هدر `Authorization` ارسال می‌کنید.
- نمونه:
```http
Authorization: Bearer <token>
Content-Type: application/json
```
### 2) آدرس پایه
اگر دامنه پروژه مثلاً `https://example.com` باشد، آدرس کامل endpointها به این صورت است:
- `https://example.com/api/device-hub/catalog/`
- `https://example.com/api/device-hub/devices/<physical_device_uuid>/latest/?device_code=<code>`
### 3) پارامترهای مهم
- `physical_device_uuid`: شناسه فیزیکی دستگاه
- `device_code`: کد نوع device داخل catalog
- `range`: بازه زمانی (`1h`, `24h`, `7d`, `30d`, `today` بسته به endpoint)
- `page` و `page_size`: برای صفحه‌بندی لاگ‌ها
---
## 1. دریافت لیست کاتالوگ دستگاه‌ها
### Endpoint
- `GET /api/device-hub/catalog/`
- `GET /api/device-hub/`
### کاربرد
برای گرفتن لیست همه device catalogها استفاده می‌شود.
### درخواست نمونه
```bash
curl -X GET "https://example.com/api/device-hub/catalog/" \
-H "Authorization: Bearer <token>"
```
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"data": [
{
"uuid": "11111111-1111-1111-1111-111111111111",
"code": "soil_sensor_v2",
"name": "Soil Sensor V2",
"description": "",
"device_communication_type": "output_only",
"customizable_fields": [],
"supported_power_sources": [],
"returned_data_fields": ["soil_moisture", "soil_temperature"],
"payload_mapping": {
"soil_moisture": ["moisture", "soil_moisture"],
"soil_temperature": ["temperature", "soil_temperature"]
},
"display_schema": {},
"supported_widgets": ["values_list", "comparison_chart", "radar_chart"],
"commands_schema": [],
"capabilities": [],
"sample_payload": {},
"is_active": true
}
]
}
```
### فیلدهای مهم پاسخ
- `device_communication_type`: نوع ارتباط دستگاه (`output_only` یا `input_only`)
- `returned_data_fields`: داده‌هایی که device برمی‌گرداند
- `payload_mapping`: نگاشت کلیدهای payload خام به فیلدهای نرمال
- `supported_widgets`: ویجت‌هایی که فرانت می‌تواند نمایش دهد
- `commands_schema`: لیست commandهای قابل ارسال برای deviceهای commandable
---
## 2. جزئیات یک دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/?device_code=<device_code>`
### کاربرد
اطلاعات کلی دستگاه ثبت‌شده در فارم را برمی‌گرداند.
### Query Params
- `device_code` اجباری
### درخواست نمونه
```bash
curl -X GET "https://example.com/api/device-hub/devices/22222222-2222-2222-2222-222222222222/?device_code=soil_sensor_v2" \
-H "Authorization: Bearer <token>"
```
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"data": {
"uuid": "33333333-3333-3333-3333-333333333333",
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"name": "Soil Device 1",
"sensor_type": "soil",
"is_active": true,
"specifications": {},
"power_source": {},
"device_catalog": {
"uuid": "11111111-1111-1111-1111-111111111111",
"code": "soil_sensor_v2",
"name": "Soil Sensor V2",
"description": "",
"device_communication_type": "output_only",
"customizable_fields": [],
"supported_power_sources": [],
"returned_data_fields": ["soil_moisture", "soil_temperature"],
"payload_mapping": {},
"display_schema": {},
"supported_widgets": ["values_list", "comparison_chart", "radar_chart"],
"commands_schema": [],
"capabilities": [],
"sample_payload": {},
"is_active": true
},
"device_catalogs": [],
"last_payload_at": "2025-01-01T10:00:00Z",
"created_at": "2025-01-01T09:00:00Z",
"updated_at": "2025-01-01T09:00:00Z"
}
}
```
### نکته
- اگر `physical_device_uuid` متعلق به کاربر نباشد، خطای 400 با متن `Device not found.` برمی‌گردد.
- اگر `device_code` به این دستگاه attach نشده باشد، خطای validation دریافت می‌کنید.
---
## 3. آخرین payload دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/latest/?device_code=<device_code>`
### کاربرد
آخرین payload خام و نرمال‌شده دستگاه را می‌دهد.
### Query Params
- `device_code` اجباری
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"data": {
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"device_code": "soil_sensor_v2",
"device_catalog_code": "soil_sensor_v2",
"raw_payload": {
"moisture": 52.4,
"temperature": 23.1
},
"normalized_payload": {
"soil_moisture": 52.4,
"soil_temperature": 23.1
},
"readings": {
"soil_moisture": 52.4,
"soil_temperature": 23.1
},
"created_at": "2025-01-01T10:00:00Z"
}
}
```
### معنی فیلدها
- `raw_payload`: داده خامی که از لاگ ذخیره‌شده آمده
- `normalized_payload`: داده تبدیل‌شده بر اساس `payload_mapping`
- `readings`: مقادیر قابل نمایش برای UI
---
## 4. خلاصه دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/summary/?device_code=<device_code>`
### کاربرد
یک summary مناسب UI برمی‌گرداند؛ مثلاً ویجت‌های قابل نمایش، values list، chartها و commandها.
### Query Params
- `device_code` اجباری
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"data": {
"sensor": {
"name": "Soil Device 1",
"physicalDeviceUuid": "22222222-2222-2222-2222-222222222222",
"sensorCatalogCode": "soil_sensor_v2",
"updatedAt": "2025-01-01T10:00:00Z"
},
"supportedWidgets": ["values_list", "comparison_chart", "radar_chart"],
"sensorValuesList": {
"sensor": {
"name": "Soil Device 1",
"physicalDeviceUuid": "22222222-2222-2222-2222-222222222222",
"sensorCatalogCode": "soil_sensor_v2",
"updatedAt": "2025-01-01T10:00:00Z"
},
"sensors": [
{
"id": "soil_moisture",
"title": "رطوبت خاک",
"subtitle": "45-65%",
"trendNumber": 52.4,
"trend": "normal",
"unit": "%"
}
]
},
"commands": []
}
}
```
### نکته
- شکل دقیق `data` بسته به `supported_widgets` و نوع catalog تغییر می‌کند.
- اگر history وجود نداشته باشد، معمولاً خطای 400 برمی‌گردد.
---
## 5. نمودار مقایسه‌ای دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/comparison-chart/?device_code=<device_code>&range=7d`
### Query Params
- `device_code` اجباری
- `range` اختیاری: `7d` یا `30d`
### پاسخ نمونه
```json
{
"series": [
{
"name": "Moisture",
"data": [50.0, 51.2, 52.4]
},
{
"name": "Temperature",
"data": [22.0, 22.4, 23.1]
}
],
"categories": ["شنبه", "یکشنبه", "دوشنبه"],
"currentValue": 52.4,
"vsLastWeek": "+3.1%"
}
```
### نکته
- این endpoint برخلاف بعضی endpointهای دیگر wrapper `code/msg` ندارد و مستقیم data chart را برمی‌گرداند.
---
## 6. لیست مقادیر دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/values-list/?device_code=<device_code>&range=7d`
### Query Params
- `device_code` اجباری
- `range` اختیاری: `1h`، `24h`، `7d`
### پاسخ نمونه
```json
{
"sensors": [
{
"title": "Moisture",
"subtitle": "45-65%",
"trendNumber": 52.4,
"trend": "positive",
"unit": "%"
},
{
"title": "Temperature",
"subtitle": "18-28°C",
"trendNumber": 23.1,
"trend": "positive",
"unit": "°C"
}
]
}
```
### نکته
- این endpoint هم مستقیم JSON داده را برمی‌گرداند و wrapper `code/msg` ندارد.
---
## 7. رادار چارت دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/radar-chart/?device_code=<device_code>&range=7d`
### Query Params
- `device_code` اجباری
- `range` اختیاری: `today`، `7d`، `30d`
### پاسخ نمونه
```json
{
"labels": ["Moisture", "Temperature", "PH", "EC"],
"series": [
{
"name": "Current",
"data": [52.4, 23.1, 6.7, 1.1]
}
]
}
```
### نکته
- این endpoint هم مستقیم data را برمی‌گرداند.
---
## 8. لاگ‌های دستگاه
### Endpoint
- `GET /api/device-hub/devices/<physical_device_uuid>/logs/?device_code=<device_code>&page=1&page_size=20`
### Query Params
- `device_code` اجباری
- `page` اختیاری، پیش‌فرض `1`
- `page_size` اختیاری، پیش‌فرض `20`، حداکثر `100`
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"count": 1,
"next": null,
"previous": null,
"data": [
{
"id": 10,
"farm_uuid": "44444444-4444-4444-4444-444444444444",
"sensor_catalog_uuid": "11111111-1111-1111-1111-111111111111",
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"farm_device": {
"uuid": "33333333-3333-3333-3333-333333333333",
"sensor_catalog_uuid": "11111111-1111-1111-1111-111111111111",
"device_catalogs": [],
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"name": "Soil Device 1",
"sensor_type": "soil",
"is_active": true,
"specifications": {},
"power_source": {},
"created_at": "2025-01-01T09:00:00Z",
"updated_at": "2025-01-01T09:00:00Z"
},
"sensor_catalog": {
"uuid": "11111111-1111-1111-1111-111111111111",
"code": "soil_sensor_v2",
"name": "Soil Sensor V2",
"description": "",
"device_communication_type": "output_only",
"customizable_fields": [],
"supported_power_sources": [],
"returned_data_fields": [],
"payload_mapping": {},
"display_schema": {},
"supported_widgets": [],
"commands_schema": [],
"capabilities": [],
"sample_payload": {},
"is_active": true,
"created_at": "2025-01-01T09:00:00Z",
"updated_at": "2025-01-01T09:00:00Z"
},
"payload": {
"moisture": 52.4,
"temperature": 23.1
},
"created_at": "2025-01-01T10:00:00Z"
}
]
}
```
### کاربرد
- برای history دستگاه
- برای نمایش payloadهای دریافت‌شده از device
- برای debug یا audit
---
## 9. ارسال command به دستگاه
### Endpoint
- `POST /api/device-hub/devices/<physical_device_uuid>/commands/`
### کاربرد
برای deviceهایی که `input_only` یا commandable هستند، command ارسال می‌کند.
### Body
```json
{
"device_code": "valve_v1",
"command": "open",
"payload": {
"duration_seconds": 120
}
}
```
### درخواست نمونه
```bash
curl -X POST "https://example.com/api/device-hub/devices/22222222-2222-2222-2222-222222222222/commands/" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"device_code": "valve_v1",
"command": "open",
"payload": {
"duration_seconds": 120
}
}'
```
### پاسخ نمونه
```json
{
"code": 200,
"msg": "command accepted",
"data": {
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"command": "open",
"status": "accepted"
}
}
```
### نکات
- `device_code` باید جزو catalogهای متصل به آن device باشد.
- اگر command یا device code معتبر نباشد، خطای 400 برمی‌گردد.
---
## 10. خلاصه سنسور 7in1
### Endpoint
- `GET /api/device-hub/summary/?farm_uuid=<farm_uuid>`
### کاربرد
خلاصه‌ای از سنسور اصلی مزرعه برای UI برمی‌گرداند.
### Query Params
- `farm_uuid` اجباری
### پاسخ نمونه
```json
{
"code": 200,
"msg": "OK",
"data": {
"sensor": {
"name": "Main Soil Sensor",
"physicalDeviceUuid": "22222222-2222-2222-2222-222222222222",
"sensorCatalogCode": "sensor-7-in-1",
"updatedAt": "2025-01-01T10:00:00Z"
},
"sensorValuesList": {},
"avgSoilMoisture": {},
"sensorRadarChart": {},
"sensorComparisonChart": {},
"anomalyDetectionCard": {},
"soilMoistureHeatmap": {}
}
}
```
---
## 11. ثبت payload خارجی دستگاه
### Endpoint
- `POST /api/device-hub/external/`
### کاربرد
این endpoint برای سیستم یا دستگاه خارجی است تا payload را به backend ارسال کند.
این endpoint با API key اختصاصی کار می‌کند، نه با توکن کاربر.
### Header
```http
X-API-Key: <api_key>
Content-Type: application/json
```
### Body
```json
{
"uuid": "22222222-2222-2222-2222-222222222222",
"payload": {
"moisture_percent": 32.5,
"temperature_c": 21.3,
"ph": 6.7,
"ec_ds_m": 1.1,
"nitrogen_mg_kg": 42,
"phosphorus_mg_kg": 18,
"potassium_mg_kg": 210
}
}
```
### رفتار endpoint
- payload را در `SensorExternalRequestLog` ذخیره می‌کند
- notification می‌سازد
- payload را به farm-data service فوروارد می‌کند
### پاسخ موفق نمونه
```json
{
"code": 201,
"msg": "success",
"data": {
"id": 1,
"title": "Sensor external API request"
}
}
```
### خطاهای مهم
- `401`: اگر `X-API-Key` اشتباه یا خالی باشد
- `404`: اگر `physical device` پیدا نشود
- `503`: اگر migrationها آماده نباشند یا سرویس farm-data در دسترس نباشد
---
## 12. لیست لاگ‌های ورودی خارجی
### Endpoint
- `GET /api/device-hub/external/logs/?farm_uuid=<farm_uuid>&page=1&page_size=20`
### Query Params
- `farm_uuid` اجباری
- `page` اجباری در داکیومنت، ولی در عمل اگر نفرستید پیش‌فرض `1` دارد در paginator
- `page_size` اجباری در داکیومنت
- `physical_device_uuid` اختیاری
- `sensor_type` اختیاری
- `date_from` اختیاری
- `date_to` اختیاری
### پاسخ نمونه
```json
{
"code": 200,
"msg": "success",
"count": 25,
"next": "https://example.com/api/device-hub/external/logs/?page=2",
"previous": null,
"data": [
{
"id": 10,
"farm_uuid": "44444444-4444-4444-4444-444444444444",
"sensor_catalog_uuid": "11111111-1111-1111-1111-111111111111",
"physical_device_uuid": "22222222-2222-2222-2222-222222222222",
"farm_device": null,
"sensor_catalog": null,
"payload": {
"moisture": 52.4
},
"created_at": "2025-01-01T10:00:00Z"
}
]
}
```
---
## الگوی خطاها
### Validation Error
در بیشتر خطاهای اعتبارسنجی، پاسخ شبیه این است:
```json
{
"device_code": [
"Device code is not attached to this farm device."
]
}
```
یا:
```json
{
"physical_device_uuid": [
"Device not found."
]
}
```
### Unauthorized
اگر توکن کاربر یا API key درست نباشد، پاسخ 401 دریافت می‌کنید.
### Service Unavailable
در endpointهای `external` اگر migration یا سرویس وابسته آماده نباشد:
```json
{
"code": 503,
"msg": "Required tables are not ready. Run migrations."
}
```
---
## ترتیب پیشنهادی استفاده در فرانت
برای صفحه جزئیات device معمولاً این ترتیب مناسب است:
1. گرفتن catalogها از `GET /api/device-hub/catalog/`
2. گرفتن جزئیات device از `GET /api/device-hub/devices/<uuid>/?device_code=...`
3. گرفتن summary از `GET /api/device-hub/devices/<uuid>/summary/?device_code=...`
4. در صورت نیاز گرفتن:
- latest payload
- comparison chart
- radar chart
- values list
- logs
برای deviceهای commandable:
1. از `commands_schema` در catalog commandهای مجاز را بخوانید
2. سپس به `POST /api/device-hub/devices/<uuid>/commands/` درخواست بزنید
---
## محل فایل‌های مرتبط در کد
- مسیرها: `device_hub/urls.py`
- ویوها: `device_hub/views.py`
- serializerها: `device_hub/serializers.py`
- serializerهای summary/chart: `device_hub/sensor_serializers.py`
- مسیر پایه پروژه: `config/urls.py`
Reference in New Issue View Git Blame Copy Permalink