Usando la API de Unraid
La API de Unraid proporciona una potente interfaz GraphQL para gestionar su servidor. Esta guía cubre la autenticación, consultas comunes y las mejores prácticas.
La API de Unraid proporciona una interfaz GraphQL que le permite interactuar con su servidor Unraid. Esta guía le ayudará a comenzar a explorar y usar la API.
🎮 Habilitación del Sandbox de GraphQL
Método GUI Web (Recomendado)
Usar la GUI Web es la forma más fácil de habilitar el sandbox de GraphQL.
-
Navegue a Configuración → Acceso de Administración → Opciones de Desarrollador
-
Habilite el interruptor Sandbox de GraphQL
-
Acceda al playground de GraphQL navegando a:
http://YOUR_SERVER_IP/graphql
Método CLI
Alternativamente, puede habilitar el modo desarrollador usando la CLI:
unraid-api developer --sandbox true
O use el modo interactivo:
unraid-api developer
🔑 Autenticación
La mayoría de las consultas y operaciones requieren autenticación. Siempre incluya las credenciales apropiadas en sus solicitudes.
Puede autenticarse usando:
- Claves API - Para acceso programático
- Cookies - Automáticamente al iniciar sesión en la WebGUI
- SSO/OIDC - Cuando se configura con proveedores externos
Gestión de Claves API
- Interfaz Gráfica de Usuario Web (Recomendado)
- Método CLI
Navegue a Configuración → Acceso de Administración → Claves API en su interfaz web Unraid para:
- Ver claves API existentes
- Crear nuevas claves API
- Gestionar permisos y roles
- Revocar o regenerar claves
También puede usar la CLI para crear una clave API:
unraid-api apikey --create
Siga las indicaciones para establecer:
- Nombre
- Descripción
- Roles
- Permisos
Usando Claves API
La clave API generada debe incluirse en sus solicitudes GraphQL como un encabezado:
{
"x-api-key": "YOUR_API_KEY"
}
📊 Esquemas Disponibles
La API proporciona acceso a varios aspectos de su servidor Unraid:
Información del Sistema
- Consultar detalles del sistema incluyendo CPU, memoria e información del SO
- Monitorear el estado y salud del sistema
- Acceder a información de placa base y hardware
Gestión de Arreglos
- Consultar estado y configuración del arreglo
- Gestionar operaciones del arreglo (iniciar/detener)
- Monitorear estado y salud del disco
- Realizar comprobaciones de paridad
Gestión Docker
- Listar y gestionar contenedores Docker
- Monitorear el estado del contenedor
- Gestionar redes Docker
Acceso Remoto
- Configurar y gestionar configuraciones de acceso remoto
- Manejar configuración SSO
- Gestionar orígenes permitidos
💻 Consultas de Ejemplo
Verificar Estado del Sistema
query {
info {
os {
platform
distro
release
uptime
}
cpu {
manufacturer
brand
cores
threads
}
}
}
Monitorear Estado del Arreglo
query {
array {
state
capacity {
disks {
free
used
total
}
}
disks {
name
size
status
temp
}
}
}
Listar Contenedores Docker
query {
dockerContainers {
id
names
state
status
autoStart
}
}
🏗️ Tipos de Esquema
La API incluye varios tipos fundamentales:
Tipos Base
Node
: Interfaz para objetos con IDs únicos - por favor, vea Identificación de ObjetoJSON
: Para datos JSON complejosDateTime
: Para valores de marca de tiempoLong
: Para enteros de 64 bits
Tipos de Recursos
Array
: Gestión de arreglos y discosDocker
: Gestión de contenedores y redesInfo
: Información del sistemaConfig
: Configuración de servidorConnect
: Configuración de acceso remoto
Acceso Basado en Roles
Roles disponibles:
admin
: Acceso completoconnect
: Características de acceso remotoguest
: Acceso de solo lectura limitado
✨ Mejores Prácticas
- Use the Apollo Sandbox to explore the schema and test queries
- Empieza con consultas pequeñas y gradualmente agrega campos según sea necesario
- Monitoree la complejidad de su consulta para mantener el rendimiento
- Use roles y permisos apropiados para sus claves API
- Mantenga sus claves API seguras y rótelas periódicamente
⏱️ Limitación de Tasa
La API implementa la limitación de tasa para prevenir abusos. Asegúrese de que sus aplicaciones gestionen adecuadamente las respuestas de límite de tasa.
🚨 Manejo de Errores
La API devuelve errores estándar de GraphQL en el siguiente formato:
{
"errors": [
{
"message": "Error description",
"locations": [...],
"path": [...]
}
]
}
📚 Recursos Adicionales
- Use the Apollo Sandbox's schema explorer to browse all available types and fields
- Check the documentation tab in Apollo Sandbox for detailed field descriptions
- Monitor the API's health using
unraid-api status
- Generate reports using
unraid-api report
for troubleshooting
For more information about specific commands and configuration options, refer to the CLI documentation or run unraid-api --help
.