REST API · CoreDash HydroLink
API สำหรับเชื่อมต่อข้อมูล SCADA เข้ากับระบบอื่นขององค์กร (ERP, BI, BMS) ใช้มาตรฐาน REST และข้อมูล JSON ไม่ผูกขาดกับผู้พัฒนา
| Base URL | https://scada.hydrolink.example (กำหนดจริงเมื่อส่งมอบ) |
|---|---|
| เวอร์ชัน | v1 — เส้นทางขึ้นต้นด้วย /api/v1 |
| รูปแบบ | JSON (UTF-8) · เวลาเป็น ISO 8601 พร้อมเขตเวลา (+07:00) |
| Spec | OpenAPI 3.0 (openapi.yaml) — นำเข้า Postman / Swagger UI ได้ทันที |
การยืนยันตัวตน
ทุกคำขอต้องแนบ API Key ที่ผู้ดูแลระบบสร้างจากเมนู REST API ในระบบ เลือกแบบใดแบบหนึ่ง
X-API-Key: cdhl_live_xxxxxxxxxxxxxxxxxxxxxxxx
# หรือ
Authorization: Bearer cdhl_live_xxxxxxxxxxxxxxxxxxxxxxxx
คีย์แต่ละตัวกำหนดสิทธิ์ (scope) ได้ และยกเลิกสิทธิ์ได้ทันทีโดยไม่กระทบคีย์อื่น
| Scope | อนุญาต |
|---|---|
read:latest | /latest, /points, /meta/last-update |
read:history | /history |
read:status | /devices/status |
read:alarms | /alarms |
control | /control, /sim/scenario (ผู้ปฏิบัติงานขึ้นไป) |
จำกัดจำนวนการเรียก
กำหนดได้ต่อคีย์ (30 / 60 / 120 / 600 ครั้งต่อนาที) ทุกคำตอบมี header
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1794667380 # epoch seconds เมื่อโควตารีเซ็ต
Retry-After: 23 # เฉพาะเมื่อได้ 429
รูปแบบข้อมูล
ค่าตัวเลขเป็นหน่วยตามจุดตรวจวัด quality บอกคุณภาพข้อมูล: good ปกติ, bad_comm ขาดการสื่อสารกับอุปกรณ์, uncertain ค่าไม่แน่นอน
ตัวกลาง (Edge Gateway) — ข้อมูลกลายเป็น JSON ได้อย่างไร
อุปกรณ์ในตู้ควบคุมใช้โปรโตคอลอุตสาหกรรมคนละแบบ ระบบภายนอกต้องการ JSON ผ่าน HTTPS จึงมี CoreDash Edge Gateway เป็นตัวกลางในตู้ควบคุม
Inverter ACS580 ×2 ─┐
Power Meter M1M 20 ─┼─► PLC FX5U ──Modbus TCP──► Edge Gateway ──HTTPS + JSON──► Web App · มือถือ · ERP · BI
Flowmeter (RS-485) ─┘ (D-register) อ่านทุก 1 วินาที
Alarm → LINE / Telegram / Email
ประวัติ + Audit log · AES-256-GCM
| ขั้น | ทำอะไร |
|---|---|
| 1. อ่าน | Gateway อ่าน D-register ของ PLC ทุก 1 วินาทีตาม Register Map (เช่น D100–D101 = system.pressure แบบ float32) |
| 2. แปลง | คูณ scale ใส่หน่วย ตรวจคุณภาพข้อมูล แล้วเก็บเป็นจุดตรวจวัดชื่อเดียวกับ API |
| 3. ให้บริการ | ตอบคำขอ REST เป็น JSON ตรวจ API Key, scope, rate limit และเข้ารหัสเพิ่มได้ |
| 4. สั่งงาน | รับ POST /control ตรวจสิทธิ์และ Interlock แล้วเขียนกลับไปที่ PLC พร้อมบันทึก Audit log |
ทำไมไม่ต่อ PLC ตรงกับ Cloud: PLC ส่ง HTTPS/JSON ไม่ได้ และการเปิด Modbus ออกอินเทอร์เน็ตเสี่ยงถูกสั่งงานจากภายนอก Gateway จึงเป็นจุดเดียวที่คุยกับ PLC และตรวจสิทธิ์ทุกคำสั่ง ถ้าอินเทอร์เน็ตหลุด Gateway ยังเก็บข้อมูลต่อ แล้วส่งย้อนหลังเมื่อกลับมา
เข้ารหัสข้อมูล (AES-256-GCM)
ทุกการเชื่อมต่อใช้ HTTPS อยู่แล้ว ถ้าระบบปลายทางต้องการเข้ารหัสตัวข้อมูลเพิ่ม ส่ง header นี้ (หรือผู้ดูแลกำหนดให้ API Key นั้นเข้ารหัสทุกครั้ง)
X-CD-Encrypt: aes-256-gcm
คำตอบจะเป็นซอง JSON แทนข้อมูลปกติ ถอดรหัสแล้วได้ JSON เดิมทุกประการ
{ "enc": "aes-256-gcm", "kid": "v1", "iv": "base64 12 byte", "tag": "base64 16 byte", "data": "base64" }
| กุญแจ | 32 byte (CD_AES_KEY) สร้างด้วย node tools/keygen.js บน Gateway |
|---|---|
| IV | สุ่มใหม่ 12 byte ทุกคำตอบ |
| ตรวจการแก้ไข | tag 16 byte ในตัว (GCM) — ข้อมูลถูกแก้แม้ 1 bit ถอดรหัสจะล้มเหลว |
วิธีใช้
- ผู้ดูแลระบบสร้างกุญแจด้วย
node tools/keygen.jsบน Gateway - ส่งกุญแจให้ระบบปลายทางทางช่องทางปลอดภัย (ไม่ส่งทางอีเมล/แชท) และเปลี่ยนกุญแจทุก 90 วัน
- ระบบปลายทางเรียก API พร้อม
X-CD-Encrypt: aes-256-gcmแล้วถอดรหัสตามตัวอย่าง
# Python (pip install requests cryptography)
import base64, json, requests
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
env = requests.get(URL + "/api/v1/latest", headers={"X-API-Key": KEY, "X-CD-Encrypt": "aes-256-gcm"}).json()
b = base64.b64decode
payload = json.loads(AESGCM(AES_KEY).decrypt(b(env["iv"]), b(env["data"]) + b(env["tag"]), None))
// Node.js
const b = (s) => Buffer.from(s, 'base64');
const d = crypto.createDecipheriv('aes-256-gcm', AES_KEY, b(env.iv)); d.setAuthTag(b(env.tag));
const payload = JSON.parse(Buffer.concat([d.update(b(env.data)), d.final()]));
ค่าล่าสุด
| พารามิเตอร์ | ชนิด | คำอธิบาย |
|---|---|---|
points | string | รหัสจุดตรวจวัด คั่นด้วย , (ดู รายการจุดตรวจวัด) |
ตัวอย่าง
curl -s "https://scada.hydrolink.example/api/v1/latest?points=system.pressure,FT-01.flow,P-01.current" \
-H "X-API-Key: $CDPS_KEY"
{
"data": [
{ "point": "system.pressure", "value": 4.01, "unit": "bar", "quality": "good", "ts": "2026-11-14T21:42:24+07:00" },
{ "point": "FT-01.flow", "value": 104.49,"unit": "m3/h", "quality": "good", "ts": "2026-11-14T21:42:24+07:00" },
{ "point": "P-01.current", "value": 35.7, "unit": "A", "quality": "good", "ts": "2026-11-14T21:42:24+07:00" }
],
"meta": { "site": "DEMO-01", "generated_at": "2026-11-14T21:42:24+07:00" }
}
ข้อมูลย้อนหลัง
| พารามิเตอร์ | ชนิด | คำอธิบาย |
|---|---|---|
point * | string | จุดตรวจวัด เช่น FT-01.flow |
start * | ISO 8601 | เวลาเริ่มต้น |
end * | ISO 8601 | เวลาสิ้นสุด (ต้องมากกว่า start) |
interval | enum | ช่วงเวลารวมข้อมูล 1m 5m 15m 1h 1d (ค่าเริ่มต้น 5m) |
agg | enum | วิธีรวม avg min max (ค่าเริ่มต้น avg) |
400 RANGE_TOO_LARGE ให้เพิ่ม interval หรือแบ่งช่วงเวลาcurl -s "https://scada.hydrolink.example/api/v1/history?point=FT-01.flow&start=2026-11-13T00:00:00%2B07:00&end=2026-11-14T00:00:00%2B07:00&interval=1h&agg=avg" \
-H "X-API-Key: $CDPS_KEY"
{
"point": "FT-01.flow", "unit": "m3/h",
"start": "2026-11-13T00:00:00+07:00", "end": "2026-11-14T00:00:00+07:00",
"interval": "1h", "agg": "avg", "count": 24, "truncated": false,
"data": [
{ "ts": "2026-11-13T00:00:00+07:00", "value": 96.412 },
{ "ts": "2026-11-13T01:00:00+07:00", "value": 88.905 },
...
],
"meta": { "site": "DEMO-01", "generated_at": "2026-11-14T21:45:02+07:00" }
}
สถานะอุปกรณ์
{
"devices": [
{ "id": "PLC", "name": "PLC Mitsubishi FX5U-32MR/DS", "address": "192.168.10.10", "protocol": "SLMP (MC) / Modbus TCP", "online": true, "last_update": "2026-11-14T21:42:24+07:00" },
{ "id": "INV-01", "name": "ABB ACS580-01-073A-4 + FMBT-21", "address": "192.168.10.21", "protocol": "Modbus TCP :502", "online": true, "last_update": "..." }
],
"pumps": [
{ "id": "P-01", "status": "RUN", "ready": true, "role": "LEAD", "frequency_hz": 44.62, "active_fault": null },
{ "id": "P-02", "status": "STOP", "ready": true, "role": "LAG", "frequency_hz": 0, "active_fault": null }
],
"control": { "mode": "AUTO", "setpoint_bar": 4.0, "alternation_hours": 6, "next_alternation": "2026-11-15T01:20:00+07:00" }
}
รายการ Alarm
| พารามิเตอร์ | คำอธิบาย |
|---|---|
state | active (ค่าเริ่มต้น) หรือ all |
from, to | ISO 8601 ช่วงเวลาที่เกิด Alarm |
{
"state": "active", "count": 1,
"data": [
{ "id": "ALM-1001", "code": "P1_FAULT", "severity": "critical", "tag": "INV-01",
"message": "P-01 Inverter Fault 2310 Overcurrent — กระแสเกิน",
"raised_at": "2026-11-14T21:42:19+07:00", "cleared_at": null, "ack_by": null, "ack_at": null }
]
}
เวลาอัปเดตล่าสุด
{ "last_update": "2026-11-14T21:42:24+07:00", "age_seconds": 1, "source": "PLC FX5U-32MR/DS" }
รายการจุดตรวจวัด
ภาพรวมทั้งหมดเป็นไฟล์ JSON
ได้ค่าล่าสุดทุกจุด ค่าตั้ง และ Alarm ที่ค้างอยู่ในไฟล์เดียว (รูปแบบเดียวกับปุ่ม “ส่งออกภาพรวม” ใน Web App)
{ "format": "coredash.snapshot/v1", "site": "DEMO-01", "generated_at": "2026-11-15T09:30:00Z",
"values": { "system.pressure": 4.01, "FT-01.flow": 106.2, "P-01.run": 1, "P-01.freq": 45.0, "…": "…" },
"settings": { "CTRL.sp": 4.0, "CTRL.int_start": 30, "CTRL.int_stop": 60, "CTRL.alt_hours": 6, "…": "…" },
"alarms_active": [] }
สั่งงาน
| command | args | ผล |
|---|---|---|
start / stop | {"pump": 1} | สั่งเดิน/หยุดปั๊ม (โหมด MANUAL) |
reset | {"pump": 2} | Reset Fault (DI02) |
alternate | — | สลับปั๊มหลักทันที |
mode | {"mode": "AUTO"} | AUTO / MANUAL |
config | {"sp": 4.2, "intervalStart": 30, "intervalStop": 60, "altHours": 6, "kp": 0.8, "ti": 3, "deadband": 0.15, "lowAlarm": 3.5, "highAlarm": 5.5} | ตั้งค่าควบคุม (ตรวจช่วงค่า เช่น sp 2–6 bar) |
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"command":"config","args":{"sp":4.2}}' https://scada.hydrolink.example/api/v1/control
# 202 { "accepted": true, "command": "config", "writes": [ { "point": "CTRL.sp", "value": 4.2 } ] }
# 409 INTERLOCK — เช่น กด E-Stop อยู่แล้วสั่งเดินปั๊ม
ทดสอบด้วยไฟล์ JSON
เตรียมไฟล์ค่าตามเวลา แล้วอัปโหลดใน Web App (แถบ 📄 ไฟล์ทดสอบ) หรือส่งให้ Gateway ขณะรันโหมดจำลอง ทุกหน้าจอ ค่าตั้ง และ Alarm ทำงานตามไฟล์ — ใช้ทดสอบระบบและสาธิตก่อนติดตั้งจริง
{ "format": "coredash.scenario/v1",
"description": "P-01 Fault → ปั๊มสำรองรับงาน",
"loop": true, "interpolate": true,
"settings": { "CTRL.sp": 4.0 },
"frames": [
{ "t": 0, "values": { "system.pressure": 4.0, "P-01.run": 1, "P-01.freq": 45 } },
{ "t": 41, "values": { "system.pressure": 3.6, "P-01.run": 0, "P-01.fault": 2310 }, "note": "P-01 Fault" },
{ "t": 46, "values": { "P-02.run": 1, "P-02.freq": 30, "CTRL.lead": 2 }, "note": "Failover" } ] }
| ฟิลด์ | ความหมาย |
|---|---|
t | วินาทีนับจากเริ่ม เรียงจากน้อยไปมาก |
values | ชื่อจุดตรวจวัดเหมือน API · จุดที่ไม่ระบุจะคงค่าเดิม |
interpolate | ค่าตัวเลขเปลี่ยนแบบต่อเนื่องระหว่าง frame (สถานะ 0/1 และ Fault code เปลี่ยนทันที) |
note | ข้อความแสดงบนแถบด้านบนขณะเล่นถึงช่วงนั้น |
ตัวอย่างพร้อมใช้: scenario-peak.json · scenario-p01-fault.json · scenario-power-estop.json
รหัสข้อผิดพลาด
{ "error": { "status": 429, "code": "RATE_LIMITED", "message": "เกินจำนวนการเรียกที่กำหนด 60 ครั้ง/นาที" } }
| HTTP | code | สาเหตุ | แนวทางแก้ |
|---|---|---|---|
| 400 | INVALID_PARAMETER | พารามิเตอร์ผิดรูปแบบ | ตรวจ start/end/interval/agg |
| 400 | RANGE_TOO_LARGE | เกิน 10,000 จุดข้อมูล | เพิ่ม interval หรือแบ่งช่วง |
| 401 | UNAUTHORIZED | ไม่ได้ส่ง API Key | แนบ X-API-Key |
| 401 | INVALID_API_KEY | คีย์ผิดหรือถูกยกเลิก | ขอคีย์ใหม่จากผู้ดูแลระบบ |
| 403 | FORBIDDEN | คีย์ไม่มี scope ที่ต้องใช้ | ขอเพิ่ม scope |
| 409 | INTERLOCK | คำสั่งขัดกับ Interlock (เช่น E-Stop) | แก้สาเหตุที่หน้างานก่อน |
| 501 | ENCRYPTION_NOT_CONFIGURED | ขอเข้ารหัสแต่ยังไม่ได้ตั้งกุญแจ | ผู้ดูแลรัน tools/keygen.js |
| 400 | ENCRYPTION_NOT_ALLOWED | ขอวิธีเข้ารหัสอื่นที่ไม่ใช่ AES-256-GCM | ใช้ X-CD-Encrypt: aes-256-gcm |
| 404 | POINT_NOT_FOUND | ไม่พบจุดตรวจวัด | ดู GET /points |
| 429 | RATE_LIMITED | เกินโควตาต่อนาที | รอตาม Retry-After |
| 503 | DEVICE_OFFLINE | อุปกรณ์ต้นทางขาดการสื่อสาร | ลองใหม่ / ตรวจสถานะ |
| 500 | INTERNAL_ERROR | ข้อผิดพลาดภายใน | แจ้งผู้ดูแลพร้อม X-Request-Id |
รายการจุดตรวจวัด
ครอบคลุมค่าที่ PLC อ่านจากปั๊ม Inverter มิเตอร์ และ Flowmeter ทั้งหมด
| point | ชื่อ | หน่วย |
|---|
ตัวอย่างโค้ด
Python
import requests
r = requests.get("https://scada.hydrolink.example/api/v1/latest",
params={"points": "system.pressure,FT-01.flow"},
headers={"X-API-Key": CDPS_KEY}, timeout=10)
r.raise_for_status()
for p in r.json()["data"]:
print(p["point"], p["value"], p["unit"])
JavaScript
const res = await fetch("https://scada.hydrolink.example/api/v1/devices/status", {
headers: { Authorization: `Bearer ${CDPS_KEY}` }
});
const { pumps } = await res.json();
console.table(pumps);
Power BI / Excel (Power Query)
let
Src = Json.Document(Web.Contents("https://scada.hydrolink.example/api/v1/history",
[Query=[point="FT-01.flow", start="2026-11-01T00:00:00+07:00", end="2026-12-01T00:00:00+07:00", interval="1d"],
Headers=[#"X-API-Key"=CDPS_KEY]])),
T = Table.FromRecords(Src[data])
in T
CoreDash Technology · โทร 081-923-2380