Utilisation de l'API Unraid
L'API Unraid offre une interface GraphQL puissante pour gérer votre serveur. Ce guide couvre l'authentification, les requêtes courantes et les meilleures pratiques.
L'API Unraid offre une interface GraphQL qui vous permet d'interagir avec votre serveur Unraid. Ce guide vous aidera à démarrer avec l'exploration et l'utilisation de l'API.
🎮 Activation du bac à sable GraphQL
Méthode par l'interface Web (Recommandé)
Utiliser l'interface WebGUI est le moyen le plus simple pour activer le bac à sable GraphQL.
-
Accédez à Paramètres → Accès à la gestion → Options pour développeur
-
Activez le bouton bascule Bac à sable GraphQL
-
Accédez au terrain de jeu 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. Incluez toujours des identifiants appropriés dans vos demandes.
Vous pouvez vous authentifier en utilisant :
- Clés API - Pour un accès programmatique
- Cookies - Automatique lors de la connexion à l'interface WebGUI
- SSO/OIDC - Lorsqu'il est configuré avec des fournisseurs externes
Gestion des Clés API
- Interface Web (Recommandé)
- Méthode CLI
Accédez à Paramètres → Accès à la gestion → Clés API dans votre interface web 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
Vous pouvez également utiliser le CLI pour créer une clé API :
unraid-api apikey --create
Suivez les invites pour définir :
- Nom
- Description
- Rôles
- Permissions
Utilisation 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 système y compris le CPU, la mémoire, et les informations sur le système d'exploitation
- Surveillez le statut et la santé du système
- Accédez aux informations de la carte mère et du matériel
Gestion des Arrays
- Interrogez le statut et la configuration de l'array
- Gérez les opérations d'array (démarrer/arrêter)
- Surveillez le statut et la santé des disques
- Effectuez des vérifications de parité
Gestion des Docker
- Listez et gérez les conteneurs Docker
- Surveillez le statut des conteneurs
- Gérez les réseaux Docker
Accès Distant
- 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
Vérifiez le Statut du Système
query {
info {
os {
platform
distro
release
uptime
}
cpu {
manufacturer
brand
cores
threads
}
}
}
Surveillez le Statut de l'Array
query {
array {
state
capacity {
disks {
free
used
total
}
}
disks {
name
size
status
temp
}
}
}
Liste des Conteneurs Docker
query {
dockerContainers {
id
names
state
status
autoStart
}
}
🏗️ Types de Schéma
L'API comprend plusieurs types de base :
Types de Base
Node
: Interface pour les objets avec des identifiants uniques - veuillez consulter Identification des ObjetsJSON
: Pour les données JSON complexesDateTime
: Pour les valeurs de timestampLong
: Pour les entiers 64 bits
Types de Ressource
Array
: Gestion des arrays et des disquesDocker
: Gestion des conteneurs et des réseauxInfo
: Informations systèmeConfig
: Configuration du serveurConnect
: Paramètres d'accès à distance
Accès Basé sur les Rôles
Rôles disponibles :
admin
: Accès completconnect
: Fonctionnalités d'accès à distanceguest
: Accès en lecture limité
✨ Bonnes Pratiques
- Utilisez le bac à sable Apollo pour explorer le schéma et tester les requêtes
- Commencez avec de petites requêtes et ajoutez progressivement des champs selon les besoins
- Surveillez la complexité de vos requêtes pour maintenir la performance
- Utilisez les rôles et permissions appropriés pour vos clés API
- Gardez vos clés API sécurisées et tournez-les périodiquement
⏱️ Limitation des Taux
L'API applique une limitation de débit pour éviter les abus. Assurez-vous que vos applications gèrent les réponses de limitation de débit de manière appropriée.
🚨 Gestion des Erreurs
L'API renvoie des erreurs GraphQL standard dans le format suivant :
{
"errors": [
{
"message": "Error description",
"locations": [...],
"path": [...]
}
]
}
📚 Ressources Supplémentaires
- Utilisez l'explorateur de schéma d'Apollo Sandbox pour parcourir tous les types et champs disponibles
- Consultez l'onglet documentation dans Apollo Sandbox pour des descriptions de champs détaillées
- 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
.