Guide de l’API

Guide complet pour utiliser l’API VergeOS, couvrant l’authentification, les méthodes HTTP, les conventions de points de terminaison, le filtrage, le tri, la gestion des erreurs et des exemples de requêtes pour les VM et les réseaux virtuels.

Vue d’ensemble

L'API VergeOS permet aux développeurs d'interagir avec le système VergeOS par programmation. Elle donne accès à des opérations système telles que la création de machines virtuelles, la gestion des ressources et l'interaction avec les dépôts de facturation et de catalogue. L'API utilise des conventions standard de type REST et prend en charge plusieurs méthodes d'authentification. Ce guide présente un aperçu de l'API VergeOS, la documentation des points de terminaison, des exemples de requêtes et la gestion des erreurs.

Ce document décrit l'utilisation de l'API. Des informations détaillées sur l'API sont disponibles dans l'interface VergeOS sous forme d'une page de documentation Swagger, générée dynamiquement et affichant une liste complète des tables et opérations API disponibles.

Interface Swagger

Pour accéder à la documentation Swagger dans l'interface VergeOS :

Connexion au système VergeOS avec des identifiants valides.
Sélectionnez Système dans le menu supérieur.
Sélectionnez Documentation API.
La page de documentation Swagger s'ouvrira. Cette page fournit des exemples détaillés pour chaque opération de l'API, y compris la possibilité de tester l'API directement.
Exemple de documentation Swagger
Sélectionnez une table individuelle et choisissez l'une des GET/POST/DELETE/PUT options disponibles pour afficher et tester les actions de l'API.
Spécifiez les paramètres et cliquez sur le bouton Exécuter pour exécuter la commande API. Cela renverra la réponse, qui inclut le corps de la réponse, l'en-tête et un exemple curl.

Notions de base de l'API

Méthodes HTTP

L'API VergeOS utilise des méthodes HTTP standard comme GET, POST, PUT et DELETE pour manipuler les ressources.

Paramètres GET

champs: Indique quels champs renvoyer dans l'ensemble de résultats.
filtre: Filtre l'ensemble de résultats selon certains critères.
tri: Trie les résultats selon un champ spécifié.
limite: Limite le nombre de résultats renvoyés.

Authentification

Toutes les requêtes API doivent être effectuées via HTTPS et nécessitent une authentification à l'aide d'une authentification d'accès de base ou d'un jeton de session.

Notes supplémentaires

Limites de débit: L'API prend en charge un maximum de 1000 requêtes par heure et par clé d'API.
Formats de données: Toutes les réponses sont renvoyées au format JSON.
Pagination: Les points de terminaison qui renvoient de grands ensembles de données prennent en charge la pagination à l'aide de offset et limite paramètres de requête.

Authentification

VergeOS prend en charge deux méthodes d'authentification :

Authentification HTTP de base L'API n'est disponible que via SSL.
Authentification par jeton Les développeurs doivent demander un jeton à l'API en envoyant une requête POST au /sys/tokens point de terminaison. Le jeton est ensuite transmis dans les requêtes API suivantes dans l' x-yottabyte-token en-tête.

Exemple de requête d'authentification

Pour obtenir un jeton :

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'

Exemple de réponse :

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

Utilisez le jeton du "$key" champ dans toutes les requêtes suivantes :

x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9

Pour vous déconnecter, envoyez une requête DELETE au /sys/tokens/{token} point de terminaison.

Exemple de requête de déconnexion

DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9

Exemple de machines virtuelles

Le Machines virtuelles de l'API VergeOS permet aux utilisateurs de gérer les machines virtuelles par programmation. Elle inclut des points de terminaison pour lister, créer, modifier et supprimer des VM.

Récupérer une liste de machines virtuelles

Point de terminaison: GET /v4/vms?fields=most

Description: Récupère une liste de toutes les VM du système avec des détails tels que les cœurs CPU, la RAM, le type de machine et les détails de configuration.

Exemple de requête:

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

Exemple de réponse:

[
  {
    "$key": 1,
    "name": "CentOS 7 (Dernière version) 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
  }
]

Vue d'ensemble des données renvoyées:

$key: L'identifiant unique de la VM.
name: Le nom de la machine virtuelle.
machine: ID de machine associé à la VM.
cpu_cores: Nombre de cœurs CPU alloués à la VM.
ram: Quantité de RAM allouée (en MB).
os_family: Type de système d'exploitation.
uuid: Identifiant unique universel (UUID) de la VM.
created: Horodatage de création.
modified: Horodatage de dernière modification.

Créer une nouvelle machine virtuelle

Point de terminaison: POST /v4/vms

Description: Crée une nouvelle machine virtuelle avec des détails de configuration spécifiques, tels que les cœurs CPU, la RAM, le type de machine, l'ordre de démarrage, etc.

Exemple de requête:

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": "VM de test"
  }'

Exemple de réponse:

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

Vue d'ensemble des données renvoyées:

location: L'emplacement de la ressource VM nouvellement créée.
dbpath: Chemin de base de données de la nouvelle VM.
$row: ID de ligne de la VM.
$key: Clé unique de la VM.

Exemple de réseaux virtuels (Vnets)

Le Réseaux virtuels de l'API VergeOS permet aux utilisateurs de gérer les réseaux virtuels (Vnets) par programmation. Elle inclut des points de terminaison pour récupérer, créer et gérer les ressources réseau, y compris les réseaux internes et externes, et permet des options avancées comme la limitation de débit.

Récupérer les détails du Vnet

Point de terminaison: GET /v4/vnets?fields=most

Description: Récupère une liste de tous les Vnets du système avec des détails tels que le type de réseau, le MTU, les paramètres DHCP et la configuration DNS.

Exemple de requête:

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

Exemple de réponse:

[
  {
    "$key": 6,
    "name": "Test interne 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": ""
  }
]

Vue d'ensemble des données renvoyées:

$key: L'identifiant unique du Vnet.
name: Nom du réseau virtuel.
advanced_options: Options avancées à transmettre aux services exécutés dans le réseau ; dans cet exemple, options netboot pour dnsmasq
type: Type de réseau (par ex. « internal »).
layer2_type: Type de réseau de couche 2, comme VXLAN.
network: Bloc CIDR du réseau.
mtu: Taille maximale d'unité de transmission (MTU).
dhcp_enabled: Indique si DHCP est activé pour ce réseau.
dhcp_start: Adresse IP de début du pool DHCP.
dhcp_stop: Adresse IP de fin du pool DHCP.
rate_limit: Limite de débit pour le réseau (en mbytes/seconde).
gateway: La passerelle par défaut du réseau.

Créer un réseau interne avec limitation de débit

Point de terminaison: POST /v4/vnets

Description: Crée un nouveau réseau virtuel interne avec limitation de débit et paramètres DHCP.

Exemple de requête:

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":"charges de travail",
    "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"
  }'

Exemple de réponse:

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

Vue d'ensemble des données renvoyées:

location: L'emplacement de la ressource Vnet nouvellement créée.
dbpath: Chemin de base de données du nouveau Vnet.
$row: ID de ligne du Vnet.
$key: Clé unique du Vnet.

Ressources

Vous trouverez ci-dessous un exemple d'URL utilisé pour interroger une liste de machines.

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

https://

utilisateur

mot de passe

serveur

/api

/v4/machines

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

Nom d'utilisateur

Mot de passe de l'utilisateur

Nom d'hôte ou adresse IP du serveur

Emplacement de la ressource (URI)

Ces options sont décrites ci-dessous

Options GET

Champs

Spécifiez quels champs renvoyer dans l'ensemble de résultats (peut également être une vue s'il en existe une définie pour le schéma de la table).
tous renvoie tous les champs.
la plupart renvoie la plupart des champs sauf les champs d'argument et les lignes.
résumé renvoie les champs marqués comme 'summary' dans leur schéma.
Exemple : fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name

Fonctions de champ :

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

Filtre

Filtre les ensembles de résultats selon des critères spécifiés.
Similaire à OData.
Exemple : filter=enabled eq true and size gt 1048576.
Exemple : filter=cputype eq 'qemu' or cputype eq 'kvm'.

Opérateur

Description

Égal

Différent

Supérieur à

Supérieur ou égal

Inférieur à

Inférieur ou égal

Commence par

Se termine par

ET logique

OU logique

Contient la chaîne (sensible à la casse)

Contient le texte (insensible à la casse)

Correspondance regex

Tri

Trie les résultats selon le champ spécifié.
Exemple : sort=+name.
Exemple : sort=-id.

Limite

limite (entier) limite l'ensemble de résultats à un nombre spécifié d'entrées. Une valeur de 0 signifie illimité.
Exemple : limit=1.

Codes de réponse HTTP génériques

400 - Requête incorrecte: La requête n'était pas valide.
401 - Échec de connexion / connexion requise: L'authentification a échoué ou est requise.
403 - Permission refusée: Vous ne disposez pas des autorisations requises.
404 - Ressource introuvable: La ligne ou l'API demandée n'existe pas.
405 - Non autorisé: L'opération n'est pas autorisée.
409 - La ligne existe déjà: La ressource existe déjà.
422 - Échec de la validation / paramètre invalide: La validation a échoué.
500 - Erreur interne du serveur: Une erreur non gérée s'est produite.

Spécifique à POST

201 - Créé: Une nouvelle ligne/ressource a été créée avec succès.

Spécifique au WebSocket (utilisé pour VNC/SPICE)

101 - Changement de protocole: Le protocole a été changé avec succès.

PUT/GET/DELETE

200 - Succès: L'opération s'est terminée avec succès.

Définitions des tables du schéma

Types de champs

booléen
texte
chaîne
nombre
uint8
uint16
uint32
uint64
int8
int16
int32
int64
enabled
created
créé_ms
créé_us
modified
modifié_ms
modifié_us
nom du fichier
taille du fichier
fichier utilisé
fichier alloué
fichier modifié
json
ligne
lignes

Propriétaire du schéma / Champ parent

Champ propriétaire: Si le champ propriétaire est nul, les permissions normales s'appliquent. Si le champ propriétaire a une valeur, les permissions sont remplacées par une vérification des permissions sur le propriétaire.
Champ parent: La vérification des permissions est appliquée à la ligne elle-même, et si les permissions échouent, les permissions sont également vérifiées sur la ligne parente.

Schéma complet de la table

Pour récupérer le schéma d'une table, ajoutez $table à l'URI :

/api/v4/machines/$table (remplacez "machines" par le nom de la table).

Vous serez invité à saisir vos identifiants ; cela nécessite des identifiants d'administrateur VergeOS. La sortie sera au format JSON. Firefox l'affiche par défaut dans un format lisible, mais d'autres navigateurs peuvent nécessiter d'exporter le JSON vers un programme externe pour une meilleure lisibilité.

Exemples d'erreurs

Exemple d'erreur (code HTTP 422)

{
  "err": "Erreur de validation sur le champ : 'dhcp_start' - 'échec du test de validation'"
}

VergeOS utilise les codes d'état HTTP standard pour indiquer le résultat d'une requête API.

400 Mauvaise requête: La requête est invalide ou ne peut pas être traitée.
401 Non autorisé: La clé API est absente ou invalide.
403 Interdit: La clé API n'a pas les permissions requises.
404 Introuvable: La ressource n'existe pas.
500 Erreur interne du serveur: Une erreur serveur s'est produite.

Informations sur le document

Dernière mise à jour : 2024-11-14
Version de vergeOS : 4.12.6

PrécédentAutomatisation et API

SuivantScript d’assistance API

Mis à jour il y a 3 mois

Ce contenu vous a-t-il été utile ?