API
MuteCloud von außen über HTTP und WebSocket steuern und aus Plugins über die Bridge-API.
MuteCloud spricht HTTP und WebSocket auf derselben Adresse, standardmäßig 127.0.0.1:8770.
Beides stellst du in der mutecloud.toml ein:
[api]
bind = "127.0.0.1:8770"
token = "..."Ist die API ohne Token von außen erreichbar, warnt die Cloud beim Start. Ohne Token sind nur Anfragen vom selben Server erlaubt.
HTTP
A="Authorization: Bearer $TOKEN"
H="http://127.0.0.1:8770"
curl -H "$A" $H/api/services| Route | Was sie macht | Recht |
|---|---|---|
GET /api/health | ob die Cloud läuft, kein Token nötig | keins |
GET /api/openapi.json | Beschreibung dieser API | keins |
GET /api/status | Node, Version, Zähler | jedes gültige Token |
GET /api/nodes | alle Nodes im Verbund | groups.view |
GET /api/groups | alle Gruppen | groups.view |
GET /api/groups/{name} | eine Gruppe mit ihren Servern | groups.view |
POST /api/groups/{name}/{action} | start, stop, restart, rollout, disable, backup | je nach Aktion |
GET /api/services | laufende Server | service.view |
GET /api/services/{id} | ein Server | service.view |
GET /api/services/{id}/logs | die letzten Log-Zeilen | service.view |
GET /api/services/{id}/properties | Eigenschaften, die der Server gesetzt hat | service.view |
POST /api/services/{id}/{action} | stop, drain, restart | je nach Aktion |
POST /api/services/{id}/exec | ein Befehl an die Konsole dieses Servers | service.console |
GET /api/players | wer online ist | players.view |
GET /api/players/{name} | ein einzelner Spieler | players.view |
GET /api/ranks | Ränge | ranks.view |
GET /api/ranks/{player} | die Rechte eines Spielers | ranks.view |
GET /api/data/{namespace} | gemeinsamer Speicher | data.view |
GET PUT DELETE /api/data/{namespace}/{key} | ein Eintrag, PUT nimmt den Wert als reinen Text im Body | data.view / data.edit |
POST /api/announce | Nachricht an alle Spieler | announce |
POST /api/channels/{channel} | Nachricht an Plugins, optional mit target | channels.publish |
POST /api/maintenance | Wartungsmodus umschalten | maintenance |
GET /api/layers | Vorlagen mit ihrer Revision | layers.read |
GET /api/layers/{name} | eine Vorlage als tar.gz | layers.read |
GET /api/update | Version und ob eine neuere bereitsteht | groups.view |
POST /api/command | jeder Befehl, Antwort als Zeilen | je nach Befehl |
GET /metrics | Prometheus-Text, siehe Metriken | groups.view |
Fehlt ein Recht, antwortet die API mit 403 und nennt das fehlende Recht. Nach acht falschen Tokens wird die Adresse für eine Minute gesperrt.
curl -H "$A" -X POST $H/api/groups/Lobby/start
curl -H "$A" -X POST -H 'Content-Type: application/json' \
-d '{"line":"say Restart in 5 minutes"}' $H/api/services/Lobby-1/exec
curl -H "$A" -X POST -H 'Content-Type: application/json' \
-d '{"message":"&bBack in a moment","title":true}' $H/api/announceDie vollständige Beschreibung liegt unter /api/openapi.json. Damit lassen sich Clients erzeugen
oder die Routen in Werkzeuge wie Postman oder Insomnia importieren.
Tokens
token create website groups.view players.view
token list
token delete websiteEin Token bekommt nur die Rechte, die es braucht. * gibt vollen Zugriff und gehört nicht in ein
Web-Frontend.
WebSocket
ws://127.0.0.1:8770/ws nutzt dasselbe Protokoll wie die Bridges. Nach dem Verbinden sendest du:
{"t":"hello","d":{"version":1,"role":"operator","token":"..."}}Ab dann kommen Ereignisse an, sobald sie passieren: snapshot, service_update,
service_gone, log, network, permissions, node_info. Zum Steuern sendest du command,
die Antwort kommt als output mit derselben Anfrage-ID zurück. Kanal-Nachrichten kommen als
message an, sobald du dich mit listen angemeldet hast, und mit publish sendest du eigene.
Das ist die passende Schnittstelle für ein Web-Frontend oder einen Bot, der Ereignisse empfangen soll, statt ständig nachzufragen.
Für Plugins
Die Bridge liegt auf jedem Server und bietet eine API, dazu Eigenschaften, Kanäle zwischen Servern und Events für Paper und Velocity. Alles dazu steht unter Plugins.
MuteCloud.best("Lobby"); // der leerste Server, der Spieler annimmt
MuteCloud.send(player, "Lobby"); // einen Spieler verschieben
MuteCloud.setState("INGAME"); // Eigenschaft dieses Servers
MuteCloud.channel("party").publish(invite); // Nachricht an andere Server
MuteCloud.data("myplugin").set(k, v); // gemeinsamer SpeicherDazu kommen Platzhalter wie %mutecloud_service%, %mutecloud_network_players% und
%mutecloud_players_lobby%, sobald PlaceholderAPI installiert ist.