Δημόσιο API
← Επιστροφή στο ευρετήριο τεκμηρίωσης
Ένα μικρό, μόνο για ανάγνωση HTTP API για τη λήψη της κατάστασης του διακομιστή από έξω από τον πίνακα ελέγχου: ένας πίνακας κατάστασης, ένας παρακολουθητής χρόνου λειτουργίας, ένα bot Discord, ένας κανόνας αυτοματισμού σπιτιού. Εξυπηρετείται από τον ίδιο τον πίνακα ελέγχου και επιστρέφει τα ίδια ζωντανά δεδομένα που εμφανίζουν οι δικές του σελίδες (από την κρυφή μνήμη στη μνήμη), οπότε η αναζήτησή του δεν αγγίζει ποτέ το Docker.
Είναι απενεργοποιημένο μέχρι να το χρησιμοποιήσει ένας διαχειριστής και ελέγχεται από διαχειριστή. Τίποτα δεν εκτίθεται μέχρι να υπάρχει ένα token.
Ενεργοποίηση
Ενότητα με τίτλο «Ενεργοποίηση»Ρυθμίσεις → Δημόσιο API → Νέο Κλειδί. Δώστε του ένα όνομα, επιλέξτε τι μπορεί να δει (όλοι οι διακομιστές ή ένα συγκεκριμένο υποσύνολο) και προαιρετικά μια ημερομηνία λήξης. Το πλήρες κλειδί (ένα token Bearer) εμφανίζεται μία φορά, σε ένα παράθυρο διαλόγου. αντιγράψτε το τώρα, επειδή μόνο μια σύντομη πρόθεμα διατηρείται στη συνέχεια, για αναγνώριση στη λίστα.

Η δημιουργία του πρώτου κλειδιού ενεργοποιεί αυτόματα το 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 δεν μπορεί να παρακάμψει τον προϋπολογισμό περιστρέφοντάς τα.
Τελικά σημεία
Ενότητα με τίτλο «Τελικά σημεία»GET /api/v1/servers
Ενότητα με τίτλο «GET /api/v1/servers»Κάθε διακομιστής στον οποίο εστιάζει το 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 } } ]}GET /api/v1/servers/:id
Ενότητα με τίτλο «GET /api/v1/servers/:id»Ένας διακομιστής, ίδιο αντικείμενο κάτω από ένα κλειδί 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 μέχρι ο διακομιστής να αναφέρει μια λίστα παικτών. |
Παράδειγμα
Ενότητα με τίτλο «Παράδειγμα»curl -s https://panel.example.com/api/v1/servers \ -H "Authorization: Bearer $MSM_TOKEN" | jq