Die Servers API ermöglicht das Abfragen, Starten, Stoppen und Aktualisieren von laufenden Servern. Zugriff über api.server().
Server abrufen
// Alle Server
api.server().getAllServers()
.thenAccept(servers -> System.out.println("Total: " + servers.size()));
// Server nach ID
api.server().getServerById("server-uuid")
.thenAccept(server -> System.out.println(server.getState()));
// Server in einer Gruppe
api.server().getServersByGroup("lobby")
.thenAccept(servers -> servers.forEach(s ->
System.out.println(s.getServerId() + ": " + s.getState())));
// Server nach Gruppe und numerischer ID (z.B. Lobby-1)
api.server().getServerByNumericalId("lobby", 1)
.thenAccept(server -> System.out.println(server.getServerId()));
// Aktuellen Server (aus laufendem Server)
api.server().getCurrentServer()
.thenAccept(server -> System.out.println("Läuft auf: " + server.getServerId()));
Server starten
StartServerRequest request = new StartServerRequest("group-uuid", "lobby");
api.server().startServer(request)
.thenAccept(server -> System.out.println("Gestartet: " + server.getServerId()));
Server stoppen
api.server().stopServer("server-uuid")
.thenAccept(success -> System.out.println("Gestoppt: " + success));
Server aktualisieren
UpdateServerRequest update = UpdateServerRequest.builder()
.maxPlayers(64)
.build();
api.server().updateServer("server-uuid", update)
.thenAccept(server -> System.out.println("Aktualisiert: " + server.getMaxPlayers()));
Server auflisten (REST)
Um Server in einem Netzwerk mit optionalen Filtern aufzulisten, verwende den REST-API-Endpunkt GET /v0/servers. Die Antwort enthält Server-Details, Server-Gruppen- oder Persistent-Server-Metadaten, Blueprint-Informationen und Workflow-Konfigurationen.
curl "https://your-controller/v0/servers?state=AVAILABLE&type=lobby" \
-H "X-Network-ID: your-network-id" \
-H "X-Network-Secret: your-network-secret"
| Parameter | Ort | Erforderlich | Beschreibung |
|---|
X-Network-ID | Header | Ja | Deine Netzwerk-ID |
X-Network-Secret | Header | Ja | Dein Netzwerk-Secret oder ein App-JWT für das Zielnetzwerk. Wenn der Controller mit JWT-Authentifizierung konfiguriert ist, werden beide Credential-Typen akzeptiert. JWTs müssen für das in X-Network-ID angegebene Netzwerk gültig sein und werden mit subject-basierten Berechtigungen gescoped; Netzwerk-Secrets gewähren vollen Netzwerkzugriff. |
X-SC-Component | Header | Nein | Optionaler Name der aufrufenden Komponente (zum Beispiel serverhost). Wenn gesetzt, wird der Wert dem Request-Wide-Event des Controllers als Feld component angehängt, sodass Request-Logs nach der ursprünglichen SimpleCloud-Komponente gefiltert werden können. Führende und nachgestellte Leerzeichen werden entfernt. |
server_group_id | Query | Nein | Nach Server-Gruppen-ID(s) filtern, kommagetrennt |
state | Query | Nein | Nach Status filtern, kommagetrennt (z.B. AVAILABLE,STARTING) |
serverhost_id | Query | Nein | Nach Serverhost-ID filtern |
persistent_server_id | Query | Nein | Nach Persistent-Server-ID filtern |
type | Query | Nein | Nach Typ(en) filtern, kommagetrennt (Server-Gruppen- ODER Persistent-Server-Typ) |
name | Query | Nein | Nach Name(n) filtern, kommagetrennt (Server-Gruppen- ODER Persistent-Server-Name) |
tags | Query | Nein | Nach Tag(s) filtern, kommagetrennt (matcht wenn irgendein Tag passt) |
numerical_id | Query | Nein | Nach numerischer ID filtern, kommagetrennt (z.B. 1,5,10) |
sort_by | Query | Nein | Sortierfeld: created_at, updated_at, numerical_id, state |
sort_order | Query | Nein | Sortierreihenfolge: asc (Standard) oder desc |
Response-Cache
Um die Datenbanklast durch hochfrequente Aufrufer (Dashboards, Panels, Polling-Clients) zu reduzieren, cached der Controller die zugrundeliegenden Datenbankzeilen für GET /v0/servers für 2 Sekunden. Identische, aufeinanderfolgende Anfragen innerhalb dieses Fensters werden aus dem In-Memory-Response-Cache bedient anstatt Postgres erneut abzufragen.
Caching greift nur, wenn der Aufrufer keine benutzerspezifische Berechtigungsfilterung anwendet. Berechtigungsgefilterte Aufrufer umgehen den Cache immer, um zu verhindern, dass Ergebnisse zwischen Aufrufern mit unterschiedlichen Berechtigungen vermischt werden.
Wenn Caching aktiv ist, enthält die Antwort einen X-DB-Cache-Header zur Beobachtbarkeit:
| Header-Wert | Bedeutung |
|---|
X-DB-Cache: HIT | Zeilen wurden aus dem Response-Cache bedient |
X-DB-Cache: MISS | Zeilen wurden aus der Datenbank geladen und in den Cache geschrieben |
Die TTL von 2 Sekunden ist kurz genug, damit Antworten für UI-Anwendungsfälle effektiv in Echtzeit bleiben. Wenn striktere Aktualitätsgarantien benötigt werden, behandle jede Antwort mit X-DB-Cache: HIT als bis zu 2 Sekunden veraltet.
Server-Datensatz löschen
Um einen Server-Datensatz direkt aus der Datenbank zu entfernen, ohne den Prozess zu stoppen oder Lifecycle-Events auszulösen, verwende den REST-API-Endpunkt DELETE /v0/servers/database. Dies ist nützlich, um veraltete oder verwaiste Datensätze zu bereinigen, wenn der Serverprozess bereits beendet wurde.
Diese Operation entfernt nur den Datenbankeintrag. Sie stoppt nicht den Serverprozess, löst keine Cleanup-Workflows aus und sendet keine Events. Verwende stopServer für normales Herunterfahren.
curl -X DELETE "https://your-controller/v0/servers/database?server_id=SERVER_UUID" \
-H "X-Network-ID: your-network-id" \
-H "X-Network-Secret: your-network-secret"
{
"server_id": "123e4567-e89b-12d3-a456-426614174000",
"message": "Server row deleted successfully"
}
| Parameter | Ort | Erforderlich | Beschreibung |
|---|
server_id | Query | Ja | UUID des zu löschenden Server-Datensatzes |
X-Network-ID | Header | Ja | Deine Netzwerk-ID |
X-Network-Secret | Header | Ja | Dein Netzwerk-Secret oder ein App-JWT für das Zielnetzwerk. Wenn der Controller mit JWT-Authentifizierung konfiguriert ist, werden beide Credential-Typen akzeptiert. |
X-SC-Component | Header | Nein | Optionaler Name der aufrufenden Komponente, der dem Request-Wide-Event des Controllers als Feld component angehängt wird. Führende und nachgestellte Leerzeichen werden entfernt. |
Server Model
| Property | Typ | Beschreibung |
|---|
serverId | String | Eindeutige Kennung |
groupName | String | Eltern-Gruppenname |
numericalId | long | Numerische ID in Gruppe (1, 2, 3…) |
state | ServerState | Aktueller Lifecycle-Status |
host | String | Server-Host-Maschine |
ip | String | IP-Adresse |
port | int | Server-Port |
maxPlayers | int | Spielerlimit |
playerCount | int | Aktuelle Online-Spieler |
properties | Map<String, String> | Eigene Metadaten |
ServerState
| Status | Beschreibung |
|---|
PREPARING | Template-Dateien werden kopiert |
STARTING | JVM-Prozess startet |
AVAILABLE | Bereit für Spieler |
INGAME | Hat aktive Spieler |
STOPPING | Shutdown läuft |
Umgebungsvariablen
Innerhalb eines laufenden Servers kannst du Server-Info ohne API abrufen:
String group = System.getenv("SIMPLECLOUD_GROUP");
String uniqueId = System.getenv("SIMPLECLOUD_UNIQUE_ID");
String numericalId = System.getenv("SIMPLECLOUD_NUMERICAL_ID");
String host = System.getenv("SIMPLECLOUD_HOST");
String port = System.getenv("SIMPLECLOUD_PORT");
String maxPlayers = System.getenv("SIMPLECLOUD_MAX_PLAYERS");
