コンテンツにスキップ

公開API

ドキュメントインデックスへ戻る

パネル外からサーバーのステータスを取得するための、小さく読み取り専用のHTTP APIです。ステータスダッシュボード、アップタイムモニター、Discordボット、ホームオートメーションルールなどに利用できます。これはパネル自体によって提供され、パネルのページが表示するのと同じライブデータ(インメモリキャッシュから)を返します。そのため、ポーリングしてもDockerにアクセスすることはありません。

これは管理者が使用するまで無効であり、管理者によって保護されています。トークンが存在しない限り、何も公開されません。

設定 → パブリックAPI → 新規キー。名前を付け、表示するサーバー(全サーバー、または特定のサブセット)を選択し、オプションで有効期限を設定します。完全なキー(Bearerトークン)は、ダイアログで一度だけ表示されます。後で識別するために短いプレフィックスしか保持されないため、今すぐコピーしてください。

Public API settings

最初のキーを作成すると、APIは自動的にオンになります(外部アプリにステータスの読み取りを許可するスイッチは一時停止コントロールです。キーをキャンセルせずに、提供を停止するにはオフにします)。いつでも同じテーブルからキーをキャンセルできます。それを使用しているクライアントは、すぐにアクセスできなくなります。

トークンはSHA-256ハッシュとして保存され(平文では決して保存されません)、パネルの再起動後も保持され、スコープが設定されたサーバーよりも長く存続します(削除されたサーバーは、そのトークンの結果から単純に除外されます)。

トークンをBearer認証情報として送信します。

Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cookieはなく、CORSもありません。これはサーバー間通信やCLIからの呼び出し用であり、他のオリジンのブラウザアプリ用ではありません。パネルがリバースプロキシの背後にある場合は、プロキシがAuthorizationヘッダーを転送するようにしてください。

エラーは401と{ "ok": false, "error": "..." }を返します。GET(またはHEAD)以外のメソッドは405を返します。パスが見つからない場合は404を返します。APIが無効な場合、すべてのルートが404を返します。

各トークンには独自の予算があります。RATE_LIMIT_PUBLIC_API_PER_MIN(デフォルトは120リクエスト/分、0はリミッターを無効にします)。制限を超えると429を返します。各リクエストは、トークンがチェックされる前に、クライアントIPごとの上限(その数値の5倍)にもカウントされます。そのため、存在しない、不正な形式の、取り消された、または期限切れのトークンを使用してプローブしても、ローテーションによって予算を回避することはできません。

トークンがスコープされているすべてのサーバー。

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

1つのサーバー。serverキーの下に同じオブジェクトが返されます。不明なIDおよびトークンがスコープされていないサーバー(存在しない場合)に対しては404を返します。不正な形式のIDに対しては400を返します。

フィールド 説明
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