Passer au contenu principal

Utilisation de l'API Unraid

Quick Commencer

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é)

Preferred Méthode

Utiliser l'interface WebGUI est le moyen le plus simple pour activer le bac à sable GraphQL.

  1. Accédez à ParamètresAccès à la gestionOptions pour développeur

  2. Activez le bouton bascule Bac à sable GraphQL

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

Required pour la plupart des opérations

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 :

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

Gestion des Clés API

Accédez à ParamètresAccès à la gestionClé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

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 Objets
  • JSON: Pour les données JSON complexes
  • DateTime: Pour les valeurs de timestamp
  • Long: Pour les entiers 64 bits

Types de Ressource

  • Array: Gestion des arrays et des disques
  • Docker: Gestion des conteneurs et des réseaux
  • Info: Informations système
  • Config: Configuration du serveur
  • Connect: Paramètres d'accès à distance

Accès Basé sur les Rôles

Rôles disponibles :

  • admin: Accès complet
  • connect: Fonctionnalités d'accès à distance
  • guest: Accès en lecture limité

✨ Bonnes Pratiques

Pro Conseils
  1. Utilisez le bac à sable Apollo pour explorer le schéma et tester les requêtes
  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

⏱️ Limitation des Taux

Rate Limites

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

Learn Plus
  • 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.