رفتن به محتوا

API عمومی

← بازگشت به فهرست مستندات

یک API کوچک و فقط خواندنی HTTP برای دریافت وضعیت سرور از خارج از پنل: یک داشبورد وضعیت، یک مانیتور آپ‌تایم، یک ربات Discord، یک قانون اتوماسیون خانگی. این توسط خود پنل ارائه می‌شود و همان داده‌های زنده‌ای را برمی‌گرداند که صفحات خود پنل نشان می‌دهند (از حافظه پنهان در حافظه)، بنابراین درخواست آن هرگز با Docker تماس نمی‌گیرد.

این تا زمانی که مدیر آن را فعال نکند خاموش است و تحت کنترل مدیر است. هیچ چیزی فاش نمی‌شود تا زمانی که یک توکن وجود داشته باشد.

تنظیمات → API عمومی → کلید جدید. یک نام به آن بدهید، انتخاب کنید چه چیزی را می‌تواند ببیند (همه سرورها، یا زیرمجموعه خاصی)، و به صورت اختیاری تاریخ انقضا. کلید کامل (یک توکن Bearer) یک بار در یک پنجره نمایش داده می‌شود؛ آن را اکنون کپی کنید، زیرا پس از آن فقط یک پیشوند کوتاه برای شناسایی در لیست نگهداری می‌شود.

تنظیمات API عمومی

ایجاد اولین کلید به طور خودکار API را روشن می‌کند (سوئیچ اجازه دادن به برنامه‌های خارجی برای خواندن وضعیت یک کنترل مکث است: آن را خاموش کنید تا بدون لغو هیچ کلیدی، سرویس‌دهی متوقف شود). در هر زمان می‌توانید یک کلید را از همان جدول لغو کنید؛ کلاینت‌هایی که از آن استفاده می‌کنند بلافاصله دسترسی خود را از دست می‌دهند.

توکن‌ها به صورت هش SHA-256 (هرگز به صورت متن ساده) ذخیره می‌شوند، از راه‌اندازی مجدد پنل جان سالم به در می‌برند و از سرورهایی که برای آن‌ها محدود شده‌اند طولانی‌تر عمر می‌کنند (یک سرور حذف شده به سادگی از نتایج آن توکن حذف می‌شود).

توکن را به عنوان یک اعتبارنامه Bearer ارسال کنید:

Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

هیچ کوکی و هیچ CORS وجود ندارد: این برای کلاینت‌های سرور به سرور و خط فرمان است، نه برنامه‌های مرورگر در مبدأ دیگر. اگر پنل پشت یک پروکسی معکوس قرار دارد، مطمئن شوید که پروکسی هدر 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 حافظه مقیم در مگابایت، یا null.
memoryLimitMb محدودیت حافظه کانتینر پیکربندی شده در مگابایت، یا null.
uptimeSeconds ثانیه‌ها از زمان شروع کانتینر، یا null.
players { online, max }، یا null تا زمانی که سرور لیستی از بازیکنان را گزارش کند.
Terminal window
curl -s https://panel.example.com/api/v1/servers \
-H "Authorization: Bearer $MSM_TOKEN" | jq