Μετάβαση στο περιεχόμενο

Δημόσιο API

← Επιστροφή στο ευρετήριο τεκμηρίωσης

Ένα μικρό, μόνο για ανάγνωση HTTP API για τη λήψη της κατάστασης του διακομιστή από έξω από τον πίνακα ελέγχου: ένας πίνακας κατάστασης, ένας παρακολουθητής χρόνου λειτουργίας, ένα bot Discord, ένας κανόνας αυτοματισμού σπιτιού. Εξυπηρετείται από τον ίδιο τον πίνακα ελέγχου και επιστρέφει τα ίδια ζωντανά δεδομένα που εμφανίζουν οι δικές του σελίδες (από την κρυφή μνήμη στη μνήμη), οπότε η αναζήτησή του δεν αγγίζει ποτέ το Docker.

Είναι απενεργοποιημένο μέχρι να το χρησιμοποιήσει ένας διαχειριστής και ελέγχεται από διαχειριστή. Τίποτα δεν εκτίθεται μέχρι να υπάρχει ένα token.

Ρυθμίσεις → Δημόσιο API → Νέο Κλειδί. Δώστε του ένα όνομα, επιλέξτε τι μπορεί να δει (όλοι οι διακομιστές ή ένα συγκεκριμένο υποσύνολο) και προαιρετικά μια ημερομηνία λήξης. Το πλήρες κλειδί (ένα token Bearer) εμφανίζεται μία φορά, σε ένα παράθυρο διαλόγου. αντιγράψτε το τώρα, επειδή μόνο μια σύντομη πρόθεμα διατηρείται στη συνέχεια, για αναγνώριση στη λίστα.

Ρυθμίσεις Δημόσιου API

Η δημιουργία του πρώτου κλειδιού ενεργοποιεί αυτόματα το API (ο διακόπτης Να επιτρέπονται σε εξωτερικές εφαρμογές η ανάγνωση κατάστασης είναι ένας έλεγχος παύσης: απενεργοποιήστε τον για να σταματήσετε την εξυπηρέτηση χωρίς να ακυρώσετε κανένα κλειδί). Ακυρώστε ένα κλειδί από τον ίδιο πίνακα ανά πάσα στιγμή. οι πελάτες που το χρησιμοποιούν χάνουν την πρόσβαση αμέσως.

Τα tokens αποθηκεύονται ως κατακερματισμός SHA-256 (ποτέ σε απλό κείμενο), επιβιώνουν από επανεκκίνηση του πίνακα ελέγχου και ξεπερνούν τους διακομιστές στους οποίους εστιάζουν (ένας διαγραμμένος διακομιστής απλώς εξαφανίζεται από τα αποτελέσματα αυτού του token).

Στείλτε το token ως διαπιστευτήριο Bearer:

Authorization: Bearer msm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Δεν υπάρχουν cookies και όχι CORS: αυτό είναι για καλούντες από διακομιστή σε διακομιστή και CLI, όχι για εφαρμογές προγράμματος περιήγησης από άλλη προέλευση. Εάν ο πίνακας ελέγχου βρίσκεται πίσω από έναν αντίστροφο διακομιστή μεσολάβησης, βεβαιωθείτε ότι ο διακομιστής μεσολάβησης προωθεί την κεφαλίδα Authorization.

Οι αποτυχίες επιστρέφουν 401 με { "ok": false, "error": "..." }. Οτιδήποτε άλλο εκτός από GET (ή HEAD) επιστρέφει 405. Άγνωστα μονοπάτια επιστρέφουν 404. Όταν το API είναι απενεργοποιημένο, όλες οι διαδρομές επιστρέφουν 404.

Κάθε token λαμβάνει τον δικό του προϋπολογισμό, RATE_LIMIT_PUBLIC_API_PER_MIN (προεπιλογή 120 αιτήματα/λεπτό, 0 απενεργοποιεί τον περιοριστή). Υπέρβαση του ορίου επιστρέφει 429. Κάθε αίτημα, προτού καν ελεγχθεί το token του, μετράται επίσης προς ένα όριο ανά IP πελάτη πέντε φορές αυτόν τον αριθμό, οπότε η διερεύνηση με ελλιπή, εσφαλμένα διαμορφωμένα, ανακληθέντα ή ληγμένα tokens δεν μπορεί να παρακάμψει τον προϋπολογισμό περιστρέφοντάς τα.

Κάθε διακομιστής στον οποίο εστιάζει το token.

{
"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 και για διακομιστή στον οποίο το token δεν εστιάζει (κανένας μάρτυρας ύπαρξης), και 400 για εσφαλμένα διαμορφωμένο id.

Πεδίο Σημασία
total Πόσοι διακομιστές είναι ορατοί σε αυτό το token (μετά το φίλτρο εστίασής του).
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