> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/fr/automation-api/verge-api-guide.md). # Guide API ## 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 : 1. **Connexion** au système VergeOS avec des identifiants valides. 2. Sélectionnez **Système** dans le menu supérieur. 3. Sélectionnez **Documentation API**. 4. 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](/files/493f8da1277fbe1a6f025a230edca81a57a74b58) 5. 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. 6. 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 : 1. **Authentification HTTP de base**\ L'API n'est disponible que via SSL. 2. **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 : ```bash 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 : ```json { "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9", "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9", "$row":1, "$key":"3a334563456378845634563b7b82d2efcadce9" } ``` Utilisez le jeton du `"$key"` champ dans toutes les requêtes suivantes : ```bash 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 ```bash 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**: ```bash curl -X 'GET' \\ 'https://your-verge-instance.com/api/v4/vms?fields=most' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' ``` **Exemple de réponse**: ```json [ { "$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**: ```bash curl -X 'POST' \\ 'https://your-verge-instance.com/api/v4/vms' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-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**: ```json { "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**: ```bash curl -X 'GET' \\ 'https://your-verge-instance.com/api/v4/vnets?fields=most' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-token: ' ``` **Exemple de réponse**: ```json [ { "$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**: ```bash curl -X 'POST' \\ 'https://your-verge-instance.com/api/v4/vnets' \\ -H 'accept: application/json' \\ -H 'x-yottabyte-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**: ```json { "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\:// | 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](https://msdn.microsoft.com/en-us/library/gg309461\(v=crm.7\).aspx#BKMK_filter). * Exemple : `filter=enabled eq true and size gt 1048576`. * Exemple : `filter=cputype eq 'qemu' or cputype eq 'kvm'`. | Opérateur | Description | | --------- | ----------------------------------------- | | *eq* | Égal | | *ne* | Différent | | *gt* | Supérieur à | | *ge* | Supérieur ou égal | | *lt* | Inférieur à | | *le* | Inférieur ou égal | | *bw* | Commence par | | *ew* | Se termine par | | *et* | ET logique | | *ou* | OU logique | | *cs* | Contient la chaîne (sensible à la casse) | | *ct* | Contient le texte (insensible à la casse) | | *rx* | 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) ```json { "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. *** {% hint style="info" %} **Informations sur le document** * Dernière mise à jour : 2024-11-14 * Version de vergeOS : 4.12.6 {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/knowledge-base/fr/automation-api/verge-api-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.