Guía de la API

Una guía completa para usar la API de VergeOS, que cubre autenticación, métodos HTTP, convenciones de endpoints, filtrado, ordenación, manejo de errores y ejemplos de solicitudes para VMs y redes virtuales.

Resumen

La API de VergeOS permite a los desarrolladores interactuar con el sistema VergeOS de forma programática. Proporciona acceso a operaciones del sistema como crear máquinas virtuales, administrar recursos e interactuar con los repositorios de facturación y catálogo. La API utiliza convenciones estándar similares a REST y admite múltiples métodos de autenticación. Esta guía ofrece una descripción general de la API de VergeOS, documentación de endpoints, solicitudes de ejemplo y manejo de errores.

Este documento describe el uso de la API. La información detallada de la API puede encontrarse dentro de la interfaz de usuario de VergeOS como una página de documentación Swagger, que se genera dinámicamente y muestra un listado completo de las tablas y operaciones de la API disponibles.

Interfaz Swagger

Para acceder a la documentación Swagger en la interfaz de usuario de VergeOS:

Inicie sesión en el sistema VergeOS con credenciales válidas.
Seleccione Sistema desde el menú superior.
Seleccione Documentación de la API.
Se abrirá la página de documentación Swagger. Esta página proporciona ejemplos detallados para cada operación de la API, incluida la posibilidad de probar la API directamente.
Ejemplo de documentación Swagger
Seleccione una tabla individual y elija una de las GET/POST/DELETE/PUT opciones disponibles para ver y probar acciones de la API.
Especifique los parámetros y haga clic en el Botón Ejecutar para ejecutar el comando de la API. Esto devolverá la respuesta, que incluye el cuerpo de la respuesta, el encabezado y un ejemplo curl.

Conceptos básicos de la API

Métodos HTTP

La API de VergeOS utiliza métodos HTTP estándar como GET, POST, PUT y DELETE para la manipulación de recursos.

Parámetros GET

fields: Especifica qué campos devolver en el conjunto de resultados.
filter: Filtra el conjunto de resultados según ciertos criterios.
sort: Ordena los resultados por un campo especificado.
limit: Limita el número de resultados devueltos.

Autenticación

Todas las solicitudes de la API deben realizarse a través de HTTPS y requieren autenticación mediante autenticación básica de acceso o un token de sesión.

Notas adicionales

Límites de velocidad: La API admite un máximo de 1000 solicitudes por hora por clave de API.
Formatos de datos: Todas las respuestas se devuelven en formato JSON.
Paginación: Los endpoints que devuelven grandes conjuntos de datos admiten paginación mediante offset y limit parámetros de consulta.

Autenticación

VergeOS admite dos métodos de autenticación:

Autenticación HTTP básica La API solo está disponible a través de SSL.
Autenticación basada en token Los desarrolladores deben solicitar un token a la API enviando una solicitud POST al /sys/tokens endpoint. Luego, el token se pasa en solicitudes posteriores de la API en el encabezado x-yottabyte-token .

Ejemplo de solicitud de autenticación

Para obtener un token:

curl --header "X-JSON-Non-Compact: 1" --basic --data-ascii '{"login": "USERNAME", "password": "PASSWORD"}' --insecure --request "POST" --header 'Content-Type: application/json' 'https://your-verge-instance.com/api/sys/tokens'

Ejemplo de respuesta:

{
   "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "$row":1,
   "$key":"3a334563456378845634563b7b82d2efcadce9"
}

Utilice el token del "$key" campo en todas las solicitudes posteriores:

x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9

Para cerrar sesión, envíe una solicitud DELETE al /sys/tokens/{token} endpoint.

Ejemplo de solicitud de cierre de sesión

DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9

Ejemplo de máquinas virtuales

El VMs La sección de la API de VergeOS permite a los usuarios administrar máquinas virtuales de forma programática. Incluye endpoints para listar, crear, modificar y eliminar VMs.

Obtener una lista de máquinas virtuales

Punto final: GET /v4/vms?fields=most

Descripción: Recupera una lista de todas las VMs del sistema con detalles como núcleos de CPU, RAM, tipo de máquina y detalles de configuración.

Ejemplo de solicitud:

curl -X 'GET' \\
  'https://your-verge-instance.com/api/v4/vms?fields=most' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>'

Ejemplo de respuesta:

[
  {
    "$key": 1,
    "name": "CentOS 7 (Latest) 1.0-7",
    "machine": 7,
    "cpu_cores": 2,
    "cpu_type": "Cascadelake-Server",
    "ram": 2048,
    "os_family": "linux",
    "is_snapshot": true,
    "boot_order": "cd",
    "rtc_base": "utc",
    "console": "vnc",
    "uefi": false,
    "secure_boot": false,
    "serial_port": true,
    "uuid": "d3914756-4ec5-9dfe-5c45-b28af2fd3d73",
    "created": 1724435418,
    "modified": 1724435418
  }
]

Descripción general de los datos devueltos:

$key: El identificador único de la VM.
name: El nombre de la máquina virtual.
machine: ID de máquina asociado con la VM.
cpu_cores: Número de núcleos de CPU asignados a la VM.
ram: Cantidad de RAM asignada (en MB).
os_family: Tipo de sistema operativo.
uuid: Identificador único universal (UUID) de la VM.
created: La marca de tiempo de creación.
modified: La marca de tiempo de la última modificación.

Crear una nueva máquina virtual

Punto final: POST /v4/vms

Descripción: Crea una nueva máquina virtual con detalles de configuración específicos, como núcleos de CPU, RAM, tipo de máquina, orden de arranque, etc.

Ejemplo de solicitud:

curl -X 'POST' \\
  'https://your-verge-instance.com/api/v4/vms' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name": "rest",
    "description": "test",
    "machine_type": "pc-q35-9.0",
    "allow_hotplug": true,
    "cpu_cores": 1,
    "cpu_type": "Broadwell",
    "ram": 1024,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": false,
    "note": "test vm"
  }'

Ejemplo de respuesta:

{
  "location": "/v4/vms/36",
  "dbpath": "vms/36",
  "$row": 36,
  "$key": "36"
}

Descripción general de los datos devueltos:

location: La ubicación del recurso VM recién creado.
dbpath: Ruta de base de datos de la nueva VM.
$row: ID de fila de la VM.
$key: Clave única para la VM.

Ejemplo de redes virtuales (Vnets)

El Vnets La sección de la API de VergeOS permite a los usuarios administrar redes virtuales (Vnets) de forma programática. Incluye endpoints para recuperar, crear y administrar recursos de red, incluidas redes internas y externas, y permite opciones avanzadas como el limitación de velocidad.

Recuperar detalles de Vnet

Punto final: GET /v4/vnets?fields=most

Descripción: Recupera una lista de todas las Vnets del sistema con detalles como tipo de red, MTU, configuración DHCP y configuración DNS.

Ejemplo de solicitud:

curl -X 'GET' \\
  'https://your-verge-instance.com/api/v4/vnets?fields=most' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>'

Ejemplo de respuesta:

[
  {
    "$key": 6,
    "name": "Internal Test 1",
    "advanced_options": {
      "dnsmasq": [
        "--dhcp-boot=netboot.xyz.kpxe,,192.168.10.20",
        "--dhcp-match=set:efi-x86,option:client-arch,6",
        "--dhcp-boot=tag:efi-x86,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,7",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20",
        "--dhcp-match=set:efi-x86_64,option:client-arch,9",
        "--dhcp-boot=tag:efi-x86_64,netboot.xyz.efi,,192.168.10.20"
      ]
    },
    "type": "internal",
    "layer2_type": "vxlan",
    "network": "192.168.100.0/24",
    "mtu": 9000,
    "dhcp_enabled": true,
    "dhcp_start": "192.168.100.100",
    "dhcp_stop": "192.168.100.200",
    "rate_limit": 0,
    "rate_limit_type": "mbytes/second",
    "gateway": ""
  }
]

Descripción general de los datos devueltos:

$key: El identificador único de la Vnet.
name: Nombre de la red virtual.
advanced_options: Opciones avanzadas que se pasarán a los servicios que se ejecutan dentro de la red; en este ejemplo, banderas de arranque de red para dnsmasq
type: Tipo de red (p. ej., "internal").
layer2_type: El tipo de red de Capa 2, como VXLAN.
network: Bloque CIDR de la red.
mtu: Tamaño de la Unidad Máxima de Transmisión (MTU).
dhcp_enabled: Indica si DHCP está habilitado para esta red.
dhcp_start: Dirección IP inicial para el grupo DHCP.
dhcp_stop: Dirección IP final para el grupo DHCP.
rate_limit: Límite de velocidad para la red (en mbytes/second).
gateway: La puerta de enlace predeterminada para la red.

Crear una red interna con limitación de velocidad

Punto final: POST /v4/vnets

Descripción: Crea una nueva red virtual interna con limitación de velocidad y configuración DHCP.

Ejemplo de solicitud:

curl -X 'POST' \\
  'https://your-verge-instance.com/api/v4/vnets' \\
  -H 'accept: application/json' \\
  -H 'x-yottabyte-token: <your-token>' \\
  -H 'Content-Type: application/json' \\
  -d '{
    "name":"int1",
    "description":"workloads",
    "type":"internal",
    "mtu":"9000",
    "network":"192.168.80.0/24",
    "gateway":"192.168.80.1",
    "dnslist":"1.1.1.1",
    "dhcp_enabled": true,
    "rate_limit": 100,
    "rate_limit_burst": 500,
    "dhcp_start":"192.168.80.100",
    "dhcp_stop":"192.168.80.200"
  }'

Ejemplo de respuesta:

{
  "location": "/v4/vnets/8",
  "dbpath": "vnets/8",
  "$row": 8,
  "$key": "8"
}

Descripción general de los datos devueltos:

location: La ubicación del recurso Vnet recién creado.
dbpath: Ruta de base de datos de la nueva Vnet.
$row: ID de fila de la Vnet.
$key: Clave única para la Vnet.

Recursos

A continuación se muestra un ejemplo de URL utilizada para consultar una lista de máquinas.

Ejemplo: https://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all

https://

usuario

contraseña

servidor

/api

/v4/machines

filter=&fields=all&sort=&limit=

Nombre de usuario

Contraseña del usuario

Nombre de host o IP del servidor

Ubicación del recurso (URI)

Estas opciones se describen a continuación

Opciones GET

Campos

Especifica qué campos devolver en el conjunto de resultados (también puede ser una vista si hay una definida para el esquema de la tabla).
all devuelve todos los campos.
most devuelve la mayoría de los campos excepto los campos de argumentos y las filas.
summary devuelve los campos marcados como 'summary' en su esquema.
Ejemplo: fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name

Funciones de campos:

collapse
datetime
upper
lower
count
diskspace
display
hex
sha1
sum
avg
min
max

Filtrar

Filtra los conjuntos de resultados según criterios especificados.
Similar a OData.
Ejemplo: filter=enabled eq true and size gt 1048576.
Ejemplo: filter=cputype eq 'qemu' or cputype eq 'kvm'.

Operador

Descripción

Igual

No igual

Mayor que

Mayor o igual que

Menor que

Menor o igual que

Empieza con

Termina con

Y lógico

O lógico

Contiene la cadena (sensible a mayúsculas)

Contiene texto (no sensible a mayúsculas)

Coincidencia con expresión regular

Ordenar

Ordena los resultados por el campo especificado.
Ejemplo: sort=+name.
Ejemplo: sort=-id.

Límite

limit (entero) limita el conjunto de resultados a un número especificado de entradas. Un valor de 0 significa ilimitado.
Ejemplo: limit=1.

Códigos de respuesta HTTP genéricos

400 - Solicitud incorrecta: La solicitud no era válida.
401 - Inicio de sesión fallido / Inicio de sesión requerido: La autenticación falló o es requerida.
403 - Permiso denegado: No tiene los permisos requeridos.
404 - Recurso no encontrado: La fila o API solicitada no existe.
405 - No permitido: La operación no está permitida.
409 - La fila existe: El recurso ya existe.
422 - Validación fallida / Parámetro inválido: La validación falló.
500 - Error interno del servidor: Ocurrió un error no controlado.

Específico de POST

201 - Creado: Se creó correctamente una nueva fila/recurso.

Específico de WebSocket (usado para VNC/SPICE)

101 - Cambio de protocolo: El protocolo se cambió correctamente.

PUT/GET/DELETE

200 - Éxito: La operación se completó con éxito.

Definiciones de tablas del esquema

Tipos de campo

bool
texto
cadena
num
uint8
uint16
uint32
uint64
int8
int16
int32
int64
habilitado
created
creado_ms
creado_us
modified
modificado_ms
modificado_us
nombre_de_archivo
tamaño_de_archivo
archivo_usado
archivo_asignado
archivo_modificado
json
fila
filas

Propietario del esquema / campo padre

Campo propietario: Si el campo propietario es nulo, se aplican los permisos normales. Si el campo propietario tiene un valor, los permisos se reemplazan por una comprobación de permisos al propietario.
Campo padre: La comprobación de permisos se aplica a la propia fila y, si los permisos fallan, también se verifican los permisos en la fila padre.

Esquema completo de la tabla

Para recuperar el esquema de una tabla, añada $table a la URI:

/api/v4/machines/$table (reemplaza "machines" con el nombre de la tabla).

Se te pedirá que introduzcas tus credenciales; esto requiere credenciales de administrador de VergeOS. La salida estará en formato JSON. Firefox lo muestra en un formato legible de forma predeterminada, pero otros navegadores pueden requerir exportar el JSON a un programa externo para una mejor legibilidad.

Errores de ejemplo

Error de ejemplo (código HTTP 422)

{
  "err": "Error de validación en el campo: 'dhcp_start' - 'no supera la prueba de validación'"
}

VergeOS utiliza códigos de estado HTTP estándar para indicar el resultado de una solicitud de API.

400 Solicitud incorrecta: La solicitud no es válida o no puede procesarse.
401 No autorizado: La clave de API falta o no es válida.
403 Prohibido: La clave de API no tiene los permisos requeridos.
404 No encontrado: El recurso no existe.
500 Error interno del servidor: Se produjo un error del servidor.

Información del documento

Última actualización: 2024-11-14
Versión de vergeOS: 4.12.6

AnteriorAutomatización y API

SiguienteScript auxiliar de la API

Última actualización hace 3 meses

¿Te fue útil?