Saltar al contenido principal

Usando la API de Unraid

Quick Iniciar

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)

Preferred Método

Usar la GUI Web es la forma más fácil de habilitar el sandbox de GraphQL.

  1. Navegue a ConfiguraciónAcceso de AdministraciónOpciones de Desarrollador

  2. Habilite el interruptor Sandbox de GraphQL

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

Required para la mayoría de las operaciones

La mayoría de las consultas y operaciones requieren autenticación. Siempre incluya las credenciales apropiadas en sus solicitudes.

Puede autenticarse usando:

  1. Claves API - Para acceso programático
  2. Cookies - Automáticamente al iniciar sesión en la WebGUI
  3. SSO/OIDC - Cuando se configura con proveedores externos

Gestión de Claves API

Navegue a ConfiguraciónAcceso de AdministraciónClaves API en su interfaz web Unraid para:

  • Ver claves API existentes
  • Crear nuevas claves API
  • Gestionar permisos y roles
  • Revocar o regenerar claves

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 Objeto
  • JSON: Para datos JSON complejos
  • DateTime: Para valores de marca de tiempo
  • Long: Para enteros de 64 bits

Tipos de Recursos

  • Array: Gestión de arreglos y discos
  • Docker: Gestión de contenedores y redes
  • Info: Información del sistema
  • Config: Configuración de servidor
  • Connect: Configuración de acceso remoto

Acceso Basado en Roles

Roles disponibles:

  • admin: Acceso completo
  • connect: Características de acceso remoto
  • guest: Acceso de solo lectura limitado

✨ Mejores Prácticas

Pro Consejos
  1. Use the Apollo Sandbox to explore the schema and test queries
  2. Empieza con consultas pequeñas y gradualmente agrega campos según sea necesario
  3. Monitoree la complejidad de su consulta para mantener el rendimiento
  4. Use roles y permisos apropiados para sus claves API
  5. Mantenga sus claves API seguras y rótelas periódicamente

⏱️ Limitación de Tasa

Rate Límites

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

Learn Más
  • 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.