Saltar al contenido principal

Usando la API de Unraid

La API de Unraid ofrece una interfaz GraphQL que le permite interactuar con su servidor Unraid. Esta guía cubre la autenticación, las consultas comunes y los patrones de uso.

Habilitación del sandbox de GraphQL​

Método WebGUI (recomendado)​

📖 Documentación en vivo

Vea el esquema completo de la API y la documentación:

Ver la documentación en vivo en Apollo GraphQL Studio →

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

Método WebGUI (recomendado)​

Usar la WebGUI es la forma más sencilla de habilitar el sandbox de GraphQL:

  1. Vaya a Configuración → Acceso de Administración → Opciones de Desarrollador

  2. Active el interruptor GraphQL Sandbox

  3. Acceda al entorno de pruebas 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 mutaciones requieren autenticación. Siempre incluya las credenciales apropiadas en sus solicitudes.

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

Gestión de claves API​

Navegue a Configuración → Acceso de Administración → Claves API en su Unraid WebGUI para:

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

Gestión de 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: Consulta detalles del sistema, incluida la información de CPU, memoria y sistema operativo; supervisa el estado y la salud del sistema; accede a la placa base y a la información del hardware.
  • Array management: Query array status and configuration; manage array operations (start/stop); monitor disk status and health; perform parity checks. For more information about array operations, see Array overview.
  • Gestión de Docker: Enumera y administra contenedores Docker; supervisa el estado de los contenedores; administra las redes de Docker.
  • Acceso remoto: Configura y administra la configuración de acceso remoto; gestiona la configuración de SSO; administra los orígenes permitidos.

Información del Sistema​

Información del Sistema​

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

Gestión de Arreglos​

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

Gestión Docker​

query {
    dockerContainers {
        id
        names
        state
        status
        autoStart
    }
}

Acceso Remoto​

La API incluye varios tipos principales. Los tipos base incluyen Node (interfaz para objetos con identificadores únicos; consulte Identificación de objetos), JSON (para datos JSON complejos), DateTime (para valores de marca temporal) y Long (para enteros de 64 bits). Los tipos de recurso incluyen Array (gestión de array y discos), Docker (gestión de contenedores y redes), Info (información del sistema), Config (configuración del servidor) y Connect (configuración de acceso remoto). Los roles disponibles son admin (acceso completo), connect (funciones de acceso remoto) y guest (acceso de lectura limitado).

Mejores prácticas​

Pro Consejos
  1. Utilice Apollo GraphQL Studio para ver y explorar el esquema completo de la API y la documentación
  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. Usa roles y permisos apropiados para tus claves API
  5. Mantenga sus claves API seguras y rótelas periódicamente

Listar Contenedores Docker​

Rate de Tasa

La API implementa la limitación de tasas para prevenir abusos. Asegúrese de que sus aplicaciones manejen adecuadamente las respuestas de limitación de tasas.

La API devuelve errores estándar de GraphQL en el siguiente formato:

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

Tipos de Recursos​

Learn Más
  • Vea el esquema completo de la API y la documentación usando Apollo GraphQL Studio
  • Docker: Gestión de contenedores y redes
  • Info: Información del sistema
  • Monitorea la salud de la API usando unraid-api status
  • Genera reportes usando unraid-api report para solucionar problemas

Para obtener más información sobre comandos específicos y opciones de configuración, consulte la documentación de CLI o ejecute unraid-api --help. Si encuentra problemas, visite los foros de Unraid para obtener ayuda de la comunidad.