เริ่มต้นใช้งาน REST API บน Sangfor Athena NGFW (เปิดใช้งาน Web API, Login รับ Token, โครงสร้าง API)

Sangfor Athena NGFW มี RESTful API (Web API) ให้ระบบภายนอกเข้ามาอ่านข้อมูลและตั้งค่าอุปกรณ์ได้ โดยรองรับงานอัตโนมัติหลากหลาย เช่น ดึงข้อมูล monitoring เข้าระบบ dashboard/SIEM, สั่งบล็อก IP จากระบบ SOC/SOAR โดยอัตโนมัติ, จัดการ Network Object และ policy object จากสคริปต์ บทความนี้อธิบายตั้งแต่การเปิดสิทธิ์ Web API, ขั้นตอน login รับ token, โครงสร้าง URL, รูปแบบ response ไปจนถึงตัวอย่าง curl ที่ใช้ได้จริง

เปิดสิทธิ์ Web API ให้บัญชีผู้ดูแล

1. ล็อกอิน Web UI แล้วไปที่ System > Administrator
2. เปิดการแก้ไขบัญชีผู้ดูแลที่จะใช้เรียก API (แนะนำให้สร้างบัญชีแยกเฉพาะสำหรับ API ไม่ใช้บัญชี admin หลัก) แล้วติ๊กเปิดสิทธิ์ Web API
3. บันทึกการตั้งค่า — บัญชีนี้จะสามารถเรียก login API เพื่อรับ token ได้

การยืนยันตัวตน: Login รับ Token / Keepalive / Logout

ลำดับการทำงานของ API client เป็นดังนี้

1. Login — ส่ง POST ไปที่ /api/v1/namespaces/public/login พร้อม username/password ใน body จะได้ token กลับมา
2. เรียก API อื่น ๆ — แนบ token ใน HTTP header: Cookie: token=<ค่า token> ทุก request
3. Session timeout — หากไม่มี request ติดต่อกัน 10 นาที (ค่าเริ่มต้น) token จะหมดอายุ ต้อง login ใหม่ หรือเรียก GET /api/v1/namespaces/public/keepalive เป็นระยะเพื่อต่ออายุ
4. Logout — เมื่อจบงาน ส่ง POST ไปที่ /api/v1/namespaces/public/logout

POST https://<ip-อุปกรณ์>/api/v1/namespaces/public/login
Content-Type: application/json

{
    "name": "api-user",
    "password": "<รหัสผ่าน>"
}

ตัวอย่าง response เมื่อสำเร็จ — token อยู่ที่ data.loginResult.token:

{
    "code": 0,
    "message": "success",
    "data": {
        "loginResult": {
            "token": "3869A36E56525592B3AD88DADD6E87C0F67A3EAA4DFB3C223541EA10E611761"
        },
        "role": "ADMINISTRATOR",
        "name": "api-user",
        "passwdStatus": true
    }
}

โครงสร้าง URL และ HTTP Method

<METHOD> /api/<version>/namespaces/<namespace>/<resource>/<name>?<query>

• METHOD — GET (อ่าน), POST (สร้าง), PUT (แก้ทั้ง object), PATCH (แก้บางฟิลด์), DELETE (ลบ)
• version — ปัจจุบันคือ v1
• namespace — ระบบหลักใช้ public (กรณีใช้ Virtual System จะเป็นชื่อ namespace ของระบบนั้น)
• resource — ชื่อทรัพยากร เช่น ipgroups (Network Objects), iptraffics (traffic ranking)
• name — ชื่อ object เฉพาะเจาะจง (บาง resource ใช้ UUID)

สำหรับการทำงานเป็นชุด (bulk) ใช้รูปแบบ batch: /api/batch/v1/namespaces/public/<resource> และบาง endpoint ใช้ query ?_method=GET / ?_method=DELETE ร่วมกับ POST เพื่อส่งเงื่อนไขใน body ได้

รูปแบบ Response และ Return Code

ทุก response มีโครงสร้างเดียวกัน:

{
    "code": 0,          <- 0 = สำเร็จ, อื่น ๆ = error
    "message": "success",
    "data": { ... }     <- ข้อมูลที่ขอ (ว่างเมื่อไม่สำเร็จ)
}

ตัวอย่างครบวงจรด้วย curl

ตัวอย่าง: login → ดึงข้อมูล traffic ranking ราย IP → logout (ตัวเลือก -k ใช้ข้ามการตรวจ certificate กรณีอุปกรณ์ยังใช้ self-signed certificate — เหมาะกับการทดสอบใน lab เท่านั้น บน production ควรติดตั้ง certificate ที่ถูกต้อง)

# 1) Login เก็บ token
TOKEN=$(curl -sk -X POST "https://192.168.1.1/api/v1/namespaces/public/login" \
  -H "Content-Type: application/json" \
  -d '{"name":"api-user","password":"<รหัสผ่าน>"}' \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['data']['loginResult']['token'])")

# 2) เรียก API โดยแนบ token ใน Cookie header
curl -sk "https://192.168.1.1/api/v1/namespaces/public/iptraffics" \
  -H "Cookie: token=$TOKEN"

# 3) Logout เมื่อจบงาน
curl -sk -X POST "https://192.168.1.1/api/v1/namespaces/public/logout" \
  -H "Cookie: token=$TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"loginResult\":{\"token\":\"$TOKEN\"}}"

ข้อควรระวังด้านความปลอดภัย

ดาวน์โหลดคู่มือฉบับเต็ม

บทความนี้คัดเฉพาะส่วนที่ใช้งานบ่อยมาสรุป หากต้องการรายละเอียดครบทุกคำสั่ง/ทุก endpoint สามารถดาวน์โหลดคู่มือทางการของ Sangfor ได้จาก Sangfor Community โดยตรง:

• Athena NGFW API Userguide (PDF) — คู่มือ REST API ฉบับเต็ม ครอบคลุมทุก endpoint พร้อมโครงสร้าง request/response