Public API
API HTTP ขนาดเล็กแบบอ่านอย่างเดียวสำหรับดึงสถานะเซิร์ฟเวอร์จากภายนอกแผงควบคุม: แผงควบคุมสถานะ, ตัวตรวจสอบความพร้อมใช้งาน, บอท Discord, กฎระบบอัตโนมัติภายในบ้าน มันถูกให้บริการโดยแผงควบคุมเองและส่งคืนข้อมูลสดเดียวกันกับที่หน้าของแผงควบคุมแสดง (จากแคชในหน่วยความจำ) ดังนั้นการเรียกดูจึงไม่เคยแตะต้อง Docker
มัน ปิดอยู่จนกว่าผู้ดูแลระบบจะใช้งาน และ จำกัดการเข้าถึงโดยผู้ดูแลระบบ จะไม่มีการเปิดเผยสิ่งใดจนกว่าจะมีโทเค็น
การเปิดใช้งาน
หัวข้อที่มีชื่อว่า “การเปิดใช้งาน”การตั้งค่า → Public API → New Key ตั้งชื่อ เลือกสิ่งที่สามารถมองเห็นได้ (เซิร์ฟเวอร์ทั้งหมด หรือชุดย่อยที่ระบุ) และวันหมดอายุที่เป็นทางเลือก คีย์เต็ม (โทเค็น Bearer) จะแสดง เพียงครั้งเดียว ในกล่องโต้ตอบ ให้คัดลอกตอนนี้ เพราะหลังจากนั้นจะเก็บไว้เพียงส่วนต้นสั้นๆ เพื่อระบุในรายการเท่านั้น

การสร้างคีย์แรกจะเปิดใช้งาน API โดยอัตโนมัติ (สวิตช์ Let outside apps read status เป็นตัวควบคุมการหยุดชั่วคราว: ปิดเพื่อหยุดการให้บริการโดยไม่ยกเลิกคีย์ใดๆ) ยกเลิกคีย์จากตารางเดียวกันได้ตลอดเวลา ลูกค้าที่ใช้คีย์นั้นจะสูญเสียการเข้าถึงทันที
โทเค็นจะถูกจัดเก็บเป็นแฮช SHA-256 (ไม่เคยเก็บเป็นข้อความธรรมดา) จะคงอยู่หลังจากการรีสตาร์ทแผงควบคุม และจะมีอายุยืนยาวกว่าเซิร์ฟเวอร์ที่กำหนดขอบเขตไว้ (เซิร์ฟเวอร์ที่ถูกลบจะถูกตัดออกจากผลลัพธ์ของโทเค็นนั้น)
การยืนยันตัวตน
หัวข้อที่มีชื่อว่า “การยืนยันตัวตน”ส่งโทเค็นเป็นข้อมูลรับรอง Bearer:
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxไม่มีคุกกี้และ ไม่มี CORS: นี่สำหรับผู้เรียกจากเซิร์ฟเวอร์ไปยังเซิร์ฟเวอร์และ CLI ไม่ใช่แอปเบราว์เซอร์จากต้นทางอื่น หากแผงควบคุมอยู่หลังพร็อกซีผกผัน ตรวจสอบให้แน่ใจว่าพร็อกซีส่งต่อส่วนหัว Authorization
ความล้มเหลวจะส่งคืน 401 พร้อมกับ { "ok": false, "error": "..." } สิ่งอื่นนอกเหนือจาก GET (หรือ HEAD) จะส่งคืน 405 เส้นทางที่ไม่รู้จักจะส่งคืน 404 เมื่อ API ถูกปิดใช้งาน ทุกเส้นทางจะส่งคืน 404
การจำกัดอัตรา
หัวข้อที่มีชื่อว่า “การจำกัดอัตรา”แต่ละโทเค็นจะได้รับงบประมาณของตัวเอง RATE_LIMIT_PUBLIC_API_PER_MIN (ค่าเริ่มต้น 120 คำขอ/นาที; 0 ปิดใช้งานตัวจำกัด) เกินขีดจำกัดจะส่งคืน 429 ทุกคำขอ ก่อนที่โทเค็นจะถูกตรวจสอบ จะถูกนับรวมกับขีดจำกัดต่อ IP ไคลเอ็นต์เป็นห้าเท่าของจำนวนนั้น ดังนั้นการสุ่มตัวอย่างด้วยโทเค็นที่ขาดหายไป ผิดรูปแบบ ถูกเพิกถอน หรือหมดอายุ จะไม่สามารถหลีกเลี่ยงงบประมาณได้ด้วยการหมุนเวียน
Endpoints
หัวข้อที่มีชื่อว่า “Endpoints”GET /api/v1/servers
หัวข้อที่มีชื่อว่า “GET /api/v1/servers”เซิร์ฟเวอร์ทุกเครื่องที่โทเค็นถูกกำหนดขอบเขตไว้
{ "ok": true, "total": 1, "online": 1, "servers": [ { "id": "srv_ab12cd34", "name": "SMP", "type": "PAPER", "state": "running", "cpuPct": 18.4, "memoryMb": 2048, "memoryLimitMb": 4096, "uptimeSeconds": 11722, "players": { "online": 3, "max": 20 } } ]}GET /api/v1/servers/:id
หัวข้อที่มีชื่อว่า “GET /api/v1/servers/:id”เซิร์ฟเวอร์หนึ่งเครื่อง วัตถุเดียวกันภายใต้คีย์ server ส่งคืน 404 สำหรับ id ที่ไม่รู้จัก และ สำหรับเซิร์ฟเวอร์ที่โทเค็นไม่ได้กำหนดขอบเขตไว้ (ไม่มีตัวบ่งชี้การมีอยู่) และ 400 สำหรับ id ที่ผิดรูปแบบ
ฟิลด์การตอบกลับ
หัวข้อที่มีชื่อว่า “ฟิลด์การตอบกลับ”| ฟิลด์ | ความหมาย |
|---|---|
total |
จำนวนเซิร์ฟเวอร์ที่มองเห็นได้สำหรับโทเค็นนี้ (หลังจากการกรองขอบเขต) |
online |
จำนวนเซิร์ฟเวอร์ที่อยู่ในสถานะ: running |
id |
id เซิร์ฟเวอร์ที่เสถียร (srv_...) |
name |
ชื่อที่แสดง |
type |
ประเภทเซิร์ฟเวอร์ itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …) |
state |
running, starting, stopped, หรือ crashed: สรุปสถานะภายในของแผงควบคุมที่เสถียร |
cpuPct |
เปอร์เซ็นต์ CPU ล่าสุด หรือ null เมื่อเซิร์ฟเวอร์ไม่ทำงาน |
memoryMb |
หน่วยความจำที่ใช้งานจริงในหน่วย MB หรือ null |
memoryLimitMb |
ขีดจำกัดหน่วยความจำคอนเทนเนอร์ที่กำหนดค่าไว้ในหน่วย MB หรือ null |
uptimeSeconds |
วินาทีตั้งแต่คอนเทนเนอร์เริ่มทำงาน หรือ null |
players |
{ online, max } หรือ null จนกว่าเซิร์ฟเวอร์จะรายงานรายการผู้เล่น |
ตัวอย่าง
หัวข้อที่มีชื่อว่า “ตัวอย่าง”curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq