Zum Inhalt

GET /banlist

Endpunkt: GET /v1/pdapi/banlist

Auth: Bearer-Token

Berechtigung: REST.Banlist.Read

Zweck

Liest Bann-Eintraege aus der Bannliste. Bannbezogene Daten werden in Banlist.json gespeichert, nicht in Config.json.

Pfadparameter

Keine.

Query-Parameter

  • active: true, false oder 1, um nach dem Aktivstatus zu filtern.
  • entryType: Nach Bann-Eintragstyp filtern.
  • userId: Filter by user ID.
  • ip or userIP: Filter by IP address.
  • issuerType, issuerName, issuerIP: Nach Aussteller-Metadaten filtern.
  • reason: Nach dem Begründungstext filtern.
  • q: Allgemeine Textsuche.

Request-Body

Kein Request-Body.

Antwortschema

Schema der 200-Antwort

Feld Typ Beschreibung
Banlist object Sperrlistendaten nach Anwendung der Abfragefilter.

Schema des Banlist-Objekts:

Feld Typ Beschreibung
Version integer Dateiformatversion der Sperrliste.
BannedMessage string Nachricht, die gesperrten Spielern angezeigt wird.
UserEntries object[] Benutzersperren, die den angegebenen Filtern entsprechen.
IPEntries object[] IP-Sperren, die den angegebenen Filtern entsprechen.

Schema eines UserEntries[]-Eintrags:

Feld Typ Beschreibung
UserId string Gesperrte Benutzer-ID.
Active boolean Gibt an, ob die Sperre derzeit aktiv ist.
BannedBy object Ausstellerdaten der Sperraktion.
UnbannedBy object Ausstellerdaten der Entsperraktion, falls vorhanden.

Schema eines IPEntries[]-Eintrags:

Feld Typ Beschreibung
IP string Gesperrte IP-Adresse.
Active boolean Gibt an, ob die Sperre derzeit aktiv ist.
BannedBy object Ausstellerdaten der Sperraktion.
UnbannedBy object Ausstellerdaten der Entsperraktion, falls vorhanden.

Schema des Ausstellerobjekts:

Feld Typ Beschreibung
Type string Ausstellertyp, etwa rest, player oder system.
NameValue string Name, Benutzer-ID, Token oder ersatzweise Typ des Ausstellers.
IP string Metadaten zur IP-Adresse des Ausstellers.
Reason string Für die Aktion gespeicherter Grund.
Timestamp object UTC-Zeitstempelkomponenten der Aktion.

Schema des Zeitstempelobjekts:

Feld Typ Beschreibung
UTC integer Unix-Zeitstempel in Sekunden.
Year integer UTC-Jahr.
Month integer UTC-Monat.
Day integer UTC-Tag des Monats.
Hour integer UTC-Stunde.
Min integer UTC-Minute.
Sec integer UTC-Sekunde.
Msec integer Millisekundenkomponente.

Fehlerantworten

Fehlerantworten verwenden dieses Format:

{
    "Error": {
        "Code": "ERROR_CODE",
        "Message": "Für Menschen lesbare Nachricht",
        "Details": {}
    }
}
HTTP Fehlercode Wann es passiert
401 INVALID_TOKEN Der Authorization-Header fehlt, ist fehlerhaft oder passt zu keinem konfigurierten Bearer-Token.
403 MISSING_PERMISSION Das Token ist gültig, enthält aber nicht die Berechtigung für diesen Endpunkt.

Beispiele

Alle Sperreinträge auflisten

GET /v1/pdapi/banlist

Aktive Einträge eines Steam-Benutzers finden

GET /v1/pdapi/banlist?active=true&userId=steam_76561198012345678

Einträge nach IP durchsuchen

GET /v1/pdapi/banlist?ip=203.0.113.42

Szenarien

  • Prüfen, ob ein Spieler oder eine IP derzeit gesperrt ist.
  • Vor einer Entsperrung nach Grund oder Aussteller suchen.
  • Ein Moderations-Dashboard erstellen, das Banlist.json über die API liest.