Passer au contenu principal

Utilisation de l'API Unraid

L'API Unraid fournit une interface GraphQL qui vous permet d'interagir avec votre serveur Unraid. Ce guide couvre l'authentification, les requêtes courantes et les modèles d'utilisation.

Activation du bac à sable GraphQL​

Méthode WebGUI (recommandée)​

📖 Documentation en direct

Consultez le schéma et la documentation complets de l'API :

Voir la documentation en direct dans Apollo GraphQL Studio →

Apollo GraphQL Studio fournit une vue complète de toutes les requêtes, mutations, types et champs disponibles, avec une documentation complète. Utilisez-le pour explorer la structure du schéma et comprendre les opérations disponibles.

Méthode WebGUI (recommandée)​

Utiliser le WebGUI est le moyen le plus simple d'activer le bac à sable GraphQL :

  1. Accédez à Paramètres → Accès à la gestion → Options pour les développeurs

  2. Activez le commutateur GraphQL Sandbox

  3. Accédez au playground GraphQL en naviguant vers :

    http://YOUR_SERVER_IP/graphql

Méthode CLI​

Alternativement, vous pouvez activer le mode développeur en utilisant le CLI :

unraid-api developer --sandbox true

Ou utilisez le mode interactif :

unraid-api developer

Authentification​

La plupart des requêtes et mutations nécessitent une authentification. N'oubliez pas d'inclure les identifiants appropriés dans vos requêtes.

  1. Clés API - Pour un accès programmatique
  2. Cookies - Automatique lors de la connexion au WebGUI
  3. SSO/OIDC - Lorsqu'il est configuré avec des fournisseurs externes

Gestion des clés API​

Accédez à Paramètres → Accès à la gestion → Clés API dans votre WebGUI Unraid pour :

  • Voir les clés API existantes.
  • Créer de nouvelles clés API.
  • Gérer les permissions et rôles.
  • Révoquer ou régénérer des clés.

Gestion des Clés API​

La clé API générée doit être incluse dans vos requêtes GraphQL en tant qu'en-tête.

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

Schémas disponibles​

L'API offre un accès à divers aspects de votre serveur Unraid :

  • Informations système : interrogez les détails du système, notamment le processeur, la mémoire et les informations sur le système d'exploitation ; surveillez l'état et la santé du système ; accédez aux informations de la carte mère et du matériel.
  • Gestion de l'Array : interrogez l'état et la configuration de l'array ; gérez les opérations de l'array (démarrer/arrêter) ; surveillez l'état et la santé des disques ; effectuez des parity checks. Pour plus d'informations sur les opérations de l'array, consultez Présentation de l'Array.
  • Gestion de Docker : listez et gérez les conteneurs Docker ; surveillez l'état des conteneurs ; gérez les réseaux Docker.
  • Accès à distance : configurez et gérez les paramètres d'accès à distance ; gérez la configuration SSO ; gérez les origines autorisées.

Exemples de requêtes​

Informations système​

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

Gestion des Arrays​

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

Gestion des Docker​

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

Accès Distant​

L'API inclut plusieurs types principaux. Les types de base comprennent Node (interface pour les objets avec des identifiants uniques ; voir Identification des objets), JSON (pour les données JSON complexes), DateTime (pour les valeurs d'horodatage) et Long (pour les entiers 64 bits). Les types de ressources comprennent Array (gestion de l'array et des disques), Docker (gestion des conteneurs et des réseaux), Info (informations système), Config (configuration du serveur) et Connect (paramètres d'accès à distance). Les rôles disponibles sont admin (accès complet), connect (fonctionnalités d'accès à distance) et guest (accès en lecture limitée).

Meilleures pratiques​

Pro Conseils
  1. Utilisez Apollo GraphQL Studio pour afficher et explorer le schéma et la documentation complets de l'API
  2. Commencez avec de petites requêtes et ajoutez progressivement des champs selon les besoins
  3. Surveillez la complexité de vos requêtes pour maintenir la performance
  4. Utilisez les rôles et permissions appropriés pour vos clés API
  5. Gardez vos clés API sécurisées et tournez-les périodiquement

Gestion des erreurs et limitation du débit​

Rate Limites

L'API applique une limitation du taux pour prévenir les abus. Assurez-vous que vos applications gèrent correctement les réponses liées à la limitation du taux.

L'API renvoie des erreurs GraphQL standard dans le format suivant :

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

Ressources supplémentaires​

Learn Plus
  • Consultez le schéma et la documentation complets de l'API à l'aide de Apollo GraphQL Studio
  • Docker: Gestion des conteneurs et des réseaux
  • Info: Informations système
  • Surveillez la santé de l'API en utilisant unraid-api status
  • Générez des rapports en utilisant unraid-api report pour le dépannage

Pour plus d'informations sur des commandes spécifiques et les options de configuration, consultez la documentation CLI ou exécutez unraid-api --help. Si vous rencontrez des problèmes, visitez les forums Unraid pour obtenir de l'aide de la communauté.