واجهة برمجة التطبيقات العامة
واجهة برمجة تطبيقات HTTP صغيرة للقراءة فقط لجلب حالة الخادم من خارج اللوحة: لوحة معلومات الحالة، ومراقب وقت التشغيل، وروبوت Discord، وقاعدة أتمتة منزلية. يتم تقديمها بواسطة اللوحة نفسها وتعيد نفس البيانات الحية التي تعرضها صفحات اللوحة الخاصة (من ذاكرة التخزين المؤقت في الذاكرة)، لذا فإن استطلاعها لا يلمس Docker أبدًا.
إنها متوقفة حتى يستخدمها مسؤول و يتحكم فيها المسؤول. لا يتم كشف أي شيء حتى يوجد رمز مميز.
تمكينها
Section titled “تمكينها”الإعدادات ← واجهة برمجة التطبيقات العامة ← مفتاح جديد. امنحها اسمًا، واختر ما يمكنها رؤيته (جميع الخوادم، أو مجموعة فرعية محددة)، وتاريخ انتهاء اختياري. يتم عرض المفتاح الكامل (رمز مميز للحامل) مرة واحدة، في مربع حوار؛ انسخه الآن، لأنه لا يتم الاحتفاظ إلا ببادئة قصيرة بعد ذلك، لتحديد الهوية في القائمة.

إنشاء المفتاح الأول يقوم بتشغيل واجهة برمجة التطبيقات تلقائيًا (المفتاح السماح للتطبيقات الخارجية بقراءة الحالة هو عنصر تحكم للإيقاف المؤقت: قم بإيقافه لإيقاف التقديم دون إلغاء أي مفاتيح). قم بإلغاء مفتاح من نفس الجدول في أي وقت؛ يفقد العملاء الذين يستخدمونه الوصول على الفور.
يتم تخزين الرموز المميزة كـ SHA-256 تجزئة (لا يتم تخزينها أبدًا كنص عادي)، وتنجو من إعادة تشغيل اللوحة، وتتجاوز الخوادم التي تم تحديد نطاقها لها (يتم إسقاط الخادم المحذوف ببساطة من نتائج هذا الرمز المميز).
المصادقة
Section titled “المصادقة”أرسل الرمز المميز كبيانات اعتماد للحامل:
Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxلا توجد ملفات تعريف ارتباط و لا CORS: هذا مخصص للمكالمات من خادم إلى خادم ومن سطر الأوامر، وليس لتطبيقات المتصفح من أصل آخر. إذا كانت اللوحة خلف وكيل عكسي، فتأكد من أن الوكيل يقوم بإعادة توجيه رأس Authorization.
تعيد الأخطاء 401 مع { "ok": false, "error": "..." }. أي شيء آخر غير GET (أو HEAD) يعيد 405. المسارات غير المعروفة تعيد 404. عندما يتم تعطيل واجهة برمجة التطبيقات، تعيد كل مسارات 404.
حد المعدل
Section titled “حد المعدل”يحصل كل رمز مميز على ميزانيته الخاصة، RATE_LIMIT_PUBLIC_API_PER_MIN (الافتراضي 120 طلبًا/دقيقة؛ 0 يعطل المحدد). تجاوز الحد يعيد 429. كل طلب، قبل التحقق من الرمز المميز الخاص به، يتم احتسابه أيضًا ضمن حد لكل عنوان IP للعميل بخمسة أضعاف هذا الرقم، لذا فإن الاستطلاع برموز مميزة مفقودة أو غير صحيحة أو ملغاة أو منتهية الصلاحية لا يمكنه تجاوز الميزانية عن طريق تدويرها.
نقاط النهاية
Section titled “نقاط النهاية”GET /api/v1/servers
Section titled “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
Section titled “GET /api/v1/servers/:id”خادم واحد، نفس الكائن تحت مفتاح server. يعيد 404 لمعرف غير معروف و لخادم لم يتم تحديد نطاق الرمز المميز له (لا يوجد مصدر وجود)، و 400 لمعرف غير صحيح.
حقول الاستجابة
Section titled “حقول الاستجابة”| الحقل | المعنى |
|---|---|
total |
عدد الخوادم المرئية لهذا الرمز المميز (بعد تصفية نطاقه). |
online |
عدد تلك الخوادم في الحالة: running. |
id |
معرف الخادم الثابت (srv_...). |
name |
اسم العرض. |
type |
نوع خادم itzg (PAPER, FABRIC, AUTO_CURSEFORGE, …). |
state |
running, starting, stopped, أو crashed: ملخص ثابت لحالة اللوحة الداخلية. |
cpuPct |
نسبة استخدام وحدة المعالجة المركزية الأخيرة، أو null عندما لا يكون الخادم قيد التشغيل. |
memoryMb |
الذاكرة المقيمة بالميجابايت، أو null. |
memoryLimitMb |
حد الذاكرة المحدد للحاوية بالميجابايت، أو null. |
uptimeSeconds |
الثواني منذ بدء تشغيل الحاوية، أو null. |
players |
{ online, max }، أو null حتى يقوم الخادم بالإبلاغ عن قائمة اللاعبين. |
curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq