Verwendung der Unraid API
Die Unraid-API bietet eine leistungsfähige GraphQL-Schnittstelle zur Verwaltung Ihres Servers. Diese Anleitung behandelt Authentifizierung, häufige Abfragen und bewährte Methoden.
Die Unraid-API bietet eine GraphQL-Schnittstelle, mit der Sie mit Ihrem Unraid-Server interagieren können. Diese Anleitung hilft Ihnen, die Erkundung und Nutzung der API zu beginnen.
🎮 Aktivieren des GraphQL-Sandkastenes
WebGUI-Methode (Empfohlen)
Die Nutzung des WebGUI ist der einfachste Weg, die GraphQL-Sandbox zu aktivieren.
-
Navigieren Sie zu Einstellungen → Verwaltungszugriff → Entwickleroptionen
-
Schalten Sie den GraphQL-Sandbox-Schalter ein
-
Zugriff auf den GraphQL-Spielplatz durch Navigieren zu:
http://YOUR_SERVER_IP/graphql
CLI-Methode
Alternativ können Sie den Entwicklermodus über die CLI aktivieren:
unraid-api developer --sandbox true
Oder den interaktiven Modus nutzen:
unraid-api developer
🔑 Authentifizierung
Die meisten Abfragen und Mutationen erfordern eine Authentifizierung. Fügen Sie immer die entsprechenden Anmeldedaten in Ihre Anfragen ein.
Sie können sich authentifizieren mit:
- API-Schlüssel - Für programmgesteuerten Zugriff
- Cookies - Automatisch, wenn beim WebGUI angemeldet
- SSO/OIDC - Wenn mit externen Anbietern konfiguriert
Verwaltung von API-Schlüsseln
- Web-GUI (Empfohlen)
- CLI-Methode
Navigieren Sie in Ihrer Unraid-Weboberfläche zu Einstellungen → Verwaltungszugriff → API-Schlüssel, um:
- bestehende API-Schlüssel anzuzeigen
- neue API-Schlüssel zu erstellen
- Berechtigungen und Rollen zu verwalten
- Schlüssel zu widerrufen oder neu zu generieren
Sie können auch die CLI verwenden, um einen API-Schlüssel zu erstellen:
unraid-api apikey --create
Folgen Sie den Eingabeaufforderungen, um einzustellen:
- Name
- Beschreibung
- Rollen
- Berechtigungen
Verwendung von API-Schlüsseln
Der generierte API-Schlüssel sollte als Header in Ihren GraphQL-Anfragen enthalten sein:
{
"x-api-key": "YOUR_API_KEY"
}
📊 Verfügbare Schemata
Die API bietet Zugang zu verschiedenen Aspekten Ihres Unraid-Servers:
Systeminformationen
- Systemdetails wie CPU-, Speicher- und Betriebssysteminformationen abfragen
- Systemstatus und -gesundheit überwachen
- Zugriff auf Basisplatten- und Hardwareinformationen
Array-Verwaltung
- Array-Status und -konfiguration abfragen
- Array-Operationen verwalten (Start/Stopp)
- Festplattenstatus und -gesundheit überwachen
- Paritätsprüfungen durchführen
Docker-Verwaltung
- Docker-Container auflisten und verwalten
- Containerstatus überwachen
- Docker-Netzwerke verwalten
Fernzugriff
- Fernzugriffseinstellungen konfigurieren und verwalten
- SSO-Konfiguration behandeln
- Erlaubte Ursprünge verwalten
💻 Beispielanfragen
Systemstatus überprüfen
query {
info {
os {
platform
distro
release
uptime
}
cpu {
manufacturer
brand
cores
threads
}
}
}
Array-Status überwachen
query {
array {
state
capacity {
disks {
free
used
total
}
}
disks {
name
size
status
temp
}
}
}
Docker-Container auflisten
query {
dockerContainers {
id
names
state
status
autoStart
}
}
🏗️ Schema-Typen
Die API umfasst mehrere Kern-Typen:
Basistypen
Node: Schnittstelle für Objekte mit eindeutigen IDs - siehe ObjekterkennungJSON: Für komplexe JSON-DatenDateTime: Für ZeitstempelwerteLong: Für 64-Bit Ganzzahlen
Ressourcentypen
Array: Array- und FestplattenverwaltungDocker: Container- und NetzwerkverwaltungInfo: SysteminformationenConfig: ServerkonfigurationConnect: Fernzugriffseinstellungen
Rollenbasierter Zugriff
Verfügbare Rollen:
admin: Voller Zugriffconnect: Fernzugriffsfunktionenguest: Eingeschränkter Lesezugriff
✨ Bewährte Verfahren
- Verwenden Sie den Apollo-Sandbox, um das Schema zu erkunden und Abfragen zu testen
- Beginnen Sie mit kleinen Abfragen und fügen Sie schrittweise Felder hinzu, wie benötigt
- Überwachen Sie die Abfragestruktur, um die Leistung aufrechtzuerhalten
- Verwenden Sie geeignete Rollen und Berechtigungen für Ihre API-Schlüssel
- Halten Sie Ihre API-Schlüssel sicher und erneuern Sie sie regelmäßig
⏱️ Ratenbegrenzung
Die API implementiert eine Ratenbegrenzung, um Missbrauch zu verhindern. Stellen Sie sicher, dass Ihre Anwendungen die Reaktionen auf die Ratenbegrenzung ordnungsgemäß handhaben.
🚨 Fehlerbehandlung
Die API gibt Standard-GraphQL-Fehler im folgenden Format zurück:
{
"errors": [
{
"message": "Error description",
"locations": [...],
"path": [...]
}
]
}
📚 Zusätzliche Ressourcen
- Verwenden Sie den Schema-Explorer von Apollo Sandbox, um alle verfügbaren Typen und Felder zu durchsuchen
- Prüfen Sie die Dokumentationsregisterkarte in der Apollo Sandbox für detaillierte Felderbeschreibungen
- Überwachen Sie die Gesundheit der API mit
unraid-api status - Berichte mit
unraid-api reportzur Fehlerbehebung generieren
Für weitere Informationen zu spezifischen Befehlen und Konfigurationsoptionen, ziehen Sie die CLI-Dokumentation zurate oder führen Sie unraid-api --help aus.