API für Gruppen

Gruppe erstellen

Eine Gruppe verwendet für jeden erstellten Server dieselbe Software, dieselben Ressourcen und dasselbe Skalierungsverhalten. Die Beispiele verwenden den unter Installation erstellten gemeinsamen CloudApi-Client und gehören in die Methoden deines Plugins. Dieses Beispiel erstellt eine Paper-Lobby-Gruppe und ihren Blueprint. SimpleCloud hält eine Lobby in Betrieb und kann die Gruppe auf bis zu drei Server skalieren. Dabei werden 20 verfügbare Spielerplätze vorgehalten.

CreateGroupRequest request = CreateGroupRequest.builder()
    .name("lobby")
    .type(GroupServerType.SERVER)
    .minMemory(1024)
    .maxMemory(2048)
    .maxPlayers(100)
    .createBlueprint(CreateBlueprintRequest.builder()
        .configurator("paper")
        .serverSoftware("paper")
        .minecraftVersion("1.21.11")
        .build())
    .scaling(ScalingConfig.builder()
        .scalingMode(ScalingMode.SLOTS)
        .minServers(1)
        .maxServers(3)
        .availableSlots(20)
        .build())
    .build();

api.group().createGroup(request)
    .thenAccept(group -> System.out.println(
        "Gruppe " + group.getName() + " mit ID " + group.getServerGroupId() + " erstellt"
    ));

Der Gruppenname wird auch für den neuen Blueprint verwendet. Um stattdessen einen vorhandenen Blueprint zu verwenden, ersetze createBlueprint(...) durch:

.source(SourceConfig.builder()
    .type(SourceType.BLUEPRINT)
    .blueprint("blueprint-uuid")
    .build())

Lege nicht gleichzeitig createBlueprint und einen vorhandenen Blueprint oder eine Image-Quelle fest.

Felder von CreateGroupRequest

string

erforderlich

Verwende bis zu 100 ASCII-Buchstaben, Ziffern, Unterstriche oder Bindestriche ([A-Za-z0-9_-]). Gruppennamen sind innerhalb des Netzwerks eindeutig.Beim Abgleich wird die Groß- und Kleinschreibung nicht berücksichtigt, sodass Lobby und lobby dieselbe Gruppe bezeichnen. Beim Erstellen oder Umbenennen auf eine reine Variante der Groß- und Kleinschreibung gibt die API 409 Conflict zurück.Eine Gruppe und ein persistenter Server dürfen denselben Namen haben.

GroupServerType

SERVER für Gameserver oder PROXY für Proxys. Der Standardwert ist SERVER.

integer | null

Minimaler Arbeitsspeicher in MB.

integer | null

Maximaler Arbeitsspeicher in MB.

integer

Spielerlimit pro Server. Der Standardwert ist 50.

boolean

Legt fest, ob die Gruppe Server erstellen darf. Der Standardwert ist true.

integer | null

Priorität der Gruppe.

DeploymentConfig | null

Einstellungen zur Auswahl des Hosts.

ScalingConfig | null

Minimale und maximale Serveranzahl sowie Skalierungsverhalten.

SourceConfig | null

Vorhandener Blueprint oder vorhandenes Container-Image, den beziehungsweise das die Gruppe verwendet.

CreateBlueprintRequest | null

Blueprint, der gemeinsam mit der Gruppe erstellt wird.

WorkflowsConfig | null

Lebenszyklus- und manuelle Workflows.

Map<String, Object> | null

Benutzerdefinierte Gruppeneigenschaften.

List<String> | null

Tags zum Organisieren und Filtern von Gruppen.

Gruppen suchen

Suche eine Gruppe anhand ihres Namens oder ihrer ID:

api.group().getGroupByName("lobby")
    .thenAccept(group -> System.out.println(group.getServerGroupId()));

api.group().getGroupById("group-uuid")
    .thenAccept(group -> System.out.println(group.getName()));

Das zurückgegebene Future schlägt fehl, wenn die Gruppe nicht vorhanden ist. Bei der Suche nach Namen wird die Groß- und Kleinschreibung nicht berücksichtigt. Verwende GroupQuery, um die Gruppenliste nach Typ, Tag oder Ergebnislimit zu filtern:

GroupQuery query = GroupQuery.create()
    .filterByType(GroupServerType.SERVER)
    .filterByTag("production")
    .limit(25);

api.group().getAllGroups(query)
    .thenAccept(groups -> groups.forEach(group ->
        System.out.println(group.getName())
    ));

Rufe getAllGroups() ohne Abfrage auf, um alle Gruppen zurückzugeben.

Gruppe aktualisieren

UpdateGroupRequest ändert nur die von dir festgelegten Felder:

UpdateGroupRequest update = UpdateGroupRequest.builder()
    .maxPlayers(120)
    .build();

api.group().updateGroup("group-uuid", update)
    .thenAccept(group -> System.out.println("Gruppe " + group.getName() + " aktualisiert"));

Du kannst name, type, minMemory, maxMemory, maxPlayers, active, priority, deployment, scaling, source, workflows, properties und tags aktualisieren. Gib beim Aktualisieren eines verschachtelten Objekts wie ScalingConfig alle Werte an, die es enthalten soll. Verwende die folgenden Methoden für Eigenschaften, wenn du nur einzelne Eigenschaften zusammenführen möchtest.

Gruppeneigenschaften verwalten

Gruppeneigenschaften speichern benutzerdefinierte Daten für deine Plugins. Aktualisierungen werden mit der vorhandenen Map zusammengeführt.

Map<String, Object> properties = Map.of(
    "gameMode", "ADVENTURE",
    "region", "eu-west"
);

api.group().updateGroupProperties("group-uuid", properties)
    .thenAccept(updated -> System.out.println("Eigenschaften: " + updated));

api.group().deleteGroupProperty("group-uuid", "region")
    .thenAccept(remaining -> System.out.println("Eigenschaften: " + remaining));

Verwende deleteGroupProperties, um mehrere Schlüssel gleichzeitig zu entfernen. Jede Eigenschaftsmethode gibt die daraus resultierende Map zurück.

Weiteren Server starten

Fordere einen zusätzlichen Server an, wenn eine bestimmte Aktion deiner Anwendung eine weitere Instanz benötigt:

api.group().getGroupByName("lobby")
    .thenCompose(api.group()::requestServerStart)
    .thenRun(() -> System.out.println("Serverstart angefordert"));

Dadurch wird eine einzelne Startanforderung in die Warteschlange gestellt, ohne die Skalierungskonfiguration der Gruppe zu ändern. Verwende die Servers API oder Server-Events, wenn dein Plugin auf den neuen Server warten muss.

Startwarteschlange prüfen

Die Warteschlange zeigt ausstehende und fehlgeschlagene manuelle Startanforderungen:

api.group().getServerStartQueue()
    .thenAccept(queue -> {
        GroupStartQueueEntry lobby = queue.findByServerGroupName("lobby");
        if (lobby == null) {
            return;
        }

        lobby.getStarts().stream()
            .filter(start -> start.getStatus() == GroupStartQueueItemStatus.FAILED)
            .forEach(start -> System.err.println(start.getFailureReason()));
    });

findByServerGroupId und findByServerGroupName geben null zurück, wenn die Warteschlange keinen Eintrag für die Gruppe enthält. Entferne ausstehende Startanforderungen für eine Gruppe mit:

api.group().clearServerStartQueue("group-uuid");

Bereits erstellte Server werden dadurch nicht gestoppt.

Felder der Startwarteschlange

GroupStartQueue enthält Gesamtwerte über alle Gruppen und eine Liste von GroupStartQueueEntry-Objekten.

integer

erforderlich

Anzahl der Gruppeneinträge.

integer

erforderlich

Anzahl der ausstehenden Starts.

integer

erforderlich

Anzahl der fehlgeschlagenen Starts.

integer

erforderlich

Gesamtanzahl der Startanforderungen.

List<GroupStartQueueEntry>

erforderlich

Nach Servergruppe gruppierte Warteschlangeneinträge.

Jeder GroupStartQueueEntry stellt die ID und den Namen der Gruppe, die Anzahl ihrer Starts sowie eine Liste starts bereit. Ein GroupStartQueueItem enthält seine ID, den Erstellungszeitpunkt, den Status und den Grund eines Fehlschlags. Der Status ist PENDING, FAILED oder UNKNOWN.

Gruppe löschen

api.group().deleteGroup("group-uuid");

Deaktiviere die Gruppe zuerst, damit sie gestoppte Instanzen nicht ersetzen kann. Stoppe ihre Server, warte, bis sie beendet wurden, und lösche anschließend die Gruppe.

Referenz zum Gruppenmodell

Die folgenden Felder sind über die Getter von Group verfügbar.

string

erforderlich

Eindeutige Gruppen-ID.

string

erforderlich

Gruppenname.

GroupServerType

erforderlich

SERVER, PROXY oder UNKNOWN_SERVER.

integer | null

Minimaler Arbeitsspeicher in MB.

integer | null

Maximaler Arbeitsspeicher in MB.

integer | null

Spielerlimit pro Server.

boolean | null

Legt fest, ob die Gruppe Server erstellen darf.

integer | null

Priorität der Gruppe.

DeploymentConfig | null

Konfiguration zur Auswahl des Hosts.

ScalingConfig | null

Skalierungskonfiguration.

SourceConfig | null

Blueprint- oder Container-Image-Quelle.

WorkflowsConfig | null

Lebenszyklus- und manuelle Workflows.

Map<String, Object> | null

Benutzerdefinierte Gruppeneigenschaften.

List<String> | null

Tags der Gruppe.

string

erforderlich

Erstellungszeitpunkt im ISO-8601-Format.

string

erforderlich

Zeitpunkt der letzten Aktualisierung im ISO-8601-Format.

Felder von ScalingConfig

integer

erforderlich

Mindestanzahl der vorzuhaltenden Server.

integer

erforderlich

Maximale Anzahl der Server, die die Gruppe erstellen darf.

ScalingMode | null

SLOTS entspricht dem Dashboard-Modus Slots und hält freie Kapazität vor. PLAYERS entspricht dem Dashboard-Modus Servers und startet Server anhand der Spielerauslastung.

integer

erforderlich

Anzahl der im Modus SLOTS vorzuhaltenden freien Spielerplätze.

number

erforderlich

Schwellenwert der Spielerauslastung zwischen 0 und 1.

ScaleDownConfig | null

Einstellungen zum Herunterskalieren.

SLOTS kann Server starten und stoppen. PLAYERS startet Server nur; zusätzliche Instanzen werden nicht automatisch gestoppt.

Gruppenservertypen

Wert	Beschreibung
`SERVER`	Gameserver wie Paper oder Spigot
`PROXY`	Proxyserver wie Velocity oder BungeeCord
`UNKNOWN_SERVER`	Von der API zurückgegebener unbekannter Servertyp

Getting Started

Cloud API

Guides

Gruppe erstellen

Gruppen suchen

Gruppe aktualisieren

Gruppeneigenschaften verwalten

Weiteren Server starten

Startwarteschlange prüfen

Gruppe löschen

Referenz zum Gruppenmodell

Gruppenservertypen

​Gruppe erstellen

​Gruppen suchen

​Gruppe aktualisieren

​Gruppeneigenschaften verwalten

​Weiteren Server starten

​Startwarteschlange prüfen

​Gruppe löschen

​Referenz zum Gruppenmodell

​Gruppenservertypen

Gruppe erstellen

Gruppen suchen

Gruppe aktualisieren

Gruppeneigenschaften verwalten

Weiteren Server starten

Startwarteschlange prüfen

Gruppe löschen

Referenz zum Gruppenmodell

Gruppenservertypen