Zum Hauptinhalt springen

Verwendung der Unraid API

The Unraid API provides a GraphQL interface that allows you to interact with your Unraid server. This guide covers authentication, common queries, and usage patterns.

Aktivieren der GraphQL-Sandbox​

WebGUI-Methode (empfohlen)​

📖 Live-Dokumentation

Zeigen Sie das vollständige API-Schema und die Dokumentation an:

Live-Dokumentation in Apollo GraphQL Studio anzeigen →

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

WebGUI-Methode (empfohlen)​

Using the WebGUI is the easiest way to enable the GraphQL sandbox:

  1. Navigieren Sie zu Einstellungen → Verwaltungszugriff → Entwickleroptionen

  2. Aktivieren Sie den Schalter GraphQL Sandbox

  3. Access the GraphQL playground by navigating to:

    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.

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

Verwalten von API-Schlüsseln​

Navigieren Sie in Ihrer Unraid-WebGUI 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.

Verwaltung von API-Schlüsseln​

The generated API key should be included in your GraphQL requests as a header.

{
    "x-api-key": "YOUR_API_KEY"
}

Verfügbare Schemata​

Die API bietet Zugang zu verschiedenen Aspekten Ihres Unraid-Servers:

  • Systeminformationen: Systemdetails einschließlich CPU-, Speicher- und OS-Informationen abfragen; den Systemstatus und die Systemintegrität überwachen; Zugriff auf Mainboard- und Hardwareinformationen.
  • Array management: Query array status and configuration; manage array operations (start/stop); monitor disk status and health; perform parity checks. For more information about array operations, see Array overview.
  • Docker-Verwaltung: Docker-Container auflisten und verwalten; Containerstatus überwachen; Docker-Netzwerke verwalten.
  • Remote access: Configure and manage remote access settings; handle SSO configuration; manage allowed origins.

Systeminformationen​

Systeminformationen​

query {
    info {
        os {
            platform
            distro
            release
            uptime
        }
        cpu {
            manufacturer
            brand
            cores
            threads
        }
    }
}

Array-Verwaltung​

query {
    array {
        state
        capacity {
            disks {
                free
                used
                total
            }
        }
        disks {
            name
            size
            status
            temp
        }
    }
}

Docker-Verwaltung​

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

Fernzugriff​

Die API umfasst mehrere Kern-Typen. Zu den Basistypen gehören Node (Interface für Objekte mit eindeutigen IDs; siehe Object Identification), JSON (für komplexe JSON-Daten), DateTime (für Zeitstempelwerte) und Long (für 64-Bit-Ganzzahlen). Zu den Ressourcentypen gehören Array (array- und Festplattenverwaltung), Docker (Container- und Netzwerkverwaltung), Info (Systeminformationen), Config (Serverkonfiguration) und Connect (Einstellungen für den Fernzugriff). Verfügbare Rollen sind admin (voller Zugriff), connect (Funktionen für den Fernzugriff) und guest (eingeschränkter Lesezugriff).

Best Practices​

Pro Tipps
  1. Verwenden Sie Apollo GraphQL Studio, um das vollständige API-Schema und die Dokumentation anzuzeigen und zu erkunden
  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

Docker-Container auflisten​

Rate Grenzen

Die API implementiert eine Ratenbegrenzung, um Missbrauch zu verhindern. Stellen Sie sicher, dass Ihre Anwendungen die Reaktionen auf die Ratenbegrenzung ordnungsgemäß handhaben.

The API returns standard GraphQL errors in the following format:

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

Ressourcentypen​

Learn Mehr
  • Zeigen Sie das vollständige API-Schema und die Dokumentation mit Apollo GraphQL Studio an
  • Docker: Container- und Netzwerkverwaltung
  • Info: Systeminformationen
  • Überwachen Sie die Gesundheit der API mit unraid-api status
  • Berichte mit unraid-api report zur Fehlerbehebung generieren

Weitere Informationen zu spezifischen Befehlen und Konfigurationsoptionen finden Sie in der CLI-Dokumentation oder indem Sie unraid-api --help ausführen. Wenn Probleme auftreten, besuchen Sie die Unraid-Foren für Community-Support.