Zum Hauptinhalt springen

Verwendung der Unraid API

Quick Start

Die Unraid API bietet eine leistungsstarke GraphQL-Schnittstelle zur Verwaltung Ihres Servers. Dieser Leitfaden behandelt Authentifizierung, gängige Abfragen und bewährte Verfahren.

Die Unraid API bietet eine GraphQL-Schnittstelle, mit der Sie mit Ihrem Unraid-Server interagieren können. Dieser Leitfaden hilft Ihnen beim Einstieg in die Erkundung und Nutzung der API.

🎮 Aktivieren des GraphQL-Sandkastenes​

WebGUI-Methode (Empfohlen)​

Preferred Methode

Die Nutzung des WebGUI ist der einfachste Weg, die GraphQL-Sandbox zu aktivieren.

  1. Navigieren Sie zu Einstellungen → Verwaltungszugriff → Entwickleroptionen

  2. Schalten Sie den GraphQL-Sandbox-Schalter ein

  3. 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​

Required für die meisten Operationen

Die meisten Abfragen und Mutationen erfordern eine Authentifizierung. Fügen Sie in Ihren Anfragen immer geeignete Anmeldedaten hinzu.

Sie können sich authentifizieren mit:

  1. API-Schlüssel - Für programmgesteuerten Zugriff
  2. Cookies - Automatisch, wenn beim WebGUI angemeldet
  3. SSO/OIDC - Wenn mit externen Anbietern konfiguriert

Verwaltung von API-Schlüsseln​

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

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 Objekterkennung
  • JSON: Für komplexe JSON-Daten
  • DateTime: Für Zeitstempelwerte
  • Long: Für 64-Bit Ganzzahlen

Ressourcentypen​

  • Array: Array- und Festplattenverwaltung
  • Docker: Container- und Netzwerkverwaltung
  • Info: Systeminformationen
  • Config: Serverkonfiguration
  • Connect: Fernzugriffseinstellungen

Rollenbasierter Zugriff​

Verfügbare Rollen:

  • admin: Voller Zugriff
  • connect: Fernzugriffsfunktionen
  • guest: Eingeschränkter Lesezugriff

✨ Bewährte Verfahren​

Pro Tipps
  1. Verwenden Sie den Apollo-Sandbox, um das Schema zu erkunden und Abfragen zu testen
  2. Beginnen Sie mit kleinen Abfragen und fügen Sie schrittweise Felder hinzu, wie benötigt
  3. Überwachen Sie die Abfragestruktur, um die Leistung aufrechtzuerhalten
  4. Verwenden Sie geeignete Rollen und Berechtigungen für Ihre API-Schlüssel
  5. Halten Sie Ihre API-Schlüssel sicher und erneuern Sie sie regelmäßig

⏱️ Ratenbegrenzung​

Rate Grenzen

Die API implementiert eine Ratenbegrenzung, um Missbrauch zu verhindern. Stellen Sie sicher, dass Ihre Anwendungen die Antwort auf Ratenbegrenzungen angemessen behandeln.

🚨 Fehlerbehandlung​

Die API gibt Standard-GraphQL-Fehler im folgenden Format zurück:

{
  "errors": [
    {
      "message": "Error description",
      "locations": [...],
      "path": [...]
    }
  ]
}

📚 Zusätzliche Ressourcen​

Learn Mehr
  • 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 report zur 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.