ข้ามไปยังเนื้อหา

Public API

← กลับไปยังดัชนีเอกสาร

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

มัน ปิดอยู่จนกว่าผู้ดูแลระบบจะใช้งาน และ จำกัดการเข้าถึงโดยผู้ดูแลระบบ จะไม่มีการเปิดเผยสิ่งใดจนกว่าจะมีโทเค็น

การตั้งค่า → Public API → New Key ตั้งชื่อ เลือกสิ่งที่สามารถมองเห็นได้ (เซิร์ฟเวอร์ทั้งหมด หรือชุดย่อยที่ระบุ) และวันหมดอายุที่เป็นทางเลือก คีย์เต็ม (โทเค็น Bearer) จะแสดง เพียงครั้งเดียว ในกล่องโต้ตอบ ให้คัดลอกตอนนี้ เพราะหลังจากนั้นจะเก็บไว้เพียงส่วนต้นสั้นๆ เพื่อระบุในรายการเท่านั้น

การตั้งค่า Public API

การสร้างคีย์แรกจะเปิดใช้งาน 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 ไคลเอ็นต์เป็นห้าเท่าของจำนวนนั้น ดังนั้นการสุ่มตัวอย่างด้วยโทเค็นที่ขาดหายไป ผิดรูปแบบ ถูกเพิกถอน หรือหมดอายุ จะไม่สามารถหลีกเลี่ยงงบประมาณได้ด้วยการหมุนเวียน

เซิร์ฟเวอร์ทุกเครื่องที่โทเค็นถูกกำหนดขอบเขตไว้

{
"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 }
}
]
}

เซิร์ฟเวอร์หนึ่งเครื่อง วัตถุเดียวกันภายใต้คีย์ 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 จนกว่าเซิร์ฟเวอร์จะรายงานรายการผู้เล่น
Terminal window
curl -s https://panel.example.com/api/v1/servers \
-H "Authorization: Bearer $MSM_TOKEN" | jq