דלגו לתוכן

API ציבורי

← חזרה לאינדקס התיעוד

API HTTP קטן לקריאה בלבד לאחזור סטטוס שרתים מחוץ לפאנל: לוח מחוונים לסטטוס, צג זמינות, בוט Discord, כלל אוטומציה ביתית. הוא מוגש על ידי הפאנל עצמו ומחזיר את אותם נתונים חיים שהדפים של הפאנל מציגים (מהמטמון בזיכרון), כך שסקר שלו לעולם לא נוגע ב-Docker.

הוא כבוי עד שמנהל מערכת ישתמש בו ומוגן על ידי מנהל מערכת. שום דבר לא נחשף עד שקיים אסימון.

הגדרות → API ציבורי → מפתח חדש. תן לו שם, בחר מה הוא יכול לראות (כל השרתים, או קבוצה ספציפית), ואופציונלית תאריך תפוגה. המפתח המלא (אסימון Bearer) מוצג פעם אחת, בדיאלוג; העתק אותו כעת, מכיוון שרק קידומת קצרה נשמרת לאחר מכן, לצורך זיהוי ברשימה.

הגדרות API ציבורי

יצירת המפתח הראשון מפעילה את ה-API באופן אוטומטי (המתג אפשר לאפליקציות חיצוניות לקרוא סטטוס הוא בקרת השהיה: כבה אותו כדי להפסיק הגשה מבלי לבטל מפתחות כלשהם). בטל מפתח מהטבלה זהה בכל עת; לקוחות המשתמשים בו מאבדים גישה באופן מיידי.

אסימונים מאוחסנים כגיבוב 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 עבור מזהה לא ידוע וגם עבור שרת שהאסימון אינו מוגבל אליו (אין אורקל קיום), ו-400 עבור מזהה פגום.

שדה משמעות
total כמה שרתים גלויים לאסימון זה (לאחר סינון ההיקף שלו).
online כמה מהם במצב: running.
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