> 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/learn-the-platform/fr/module-8-developpeur-et-devops/01-api-cli.md). # API REST et outils CLI Chaque opération que vous effectuez dans l’interface VergeOS correspond directement à un appel à l’API REST. Cette **Conception axée sur l’API** signifie que tout ce sur quoi vous pouvez cliquer dans le tableau de bord — créer des VM, configurer des réseaux, gérer des locataires — peut être automatisé via des points de terminaison HTTP. Cette section couvre les trois interfaces principales pour l’accès programmatique : la **API REST** elle-même, le **script utilitaire yb-api** pour l’automatisation sur la machine, et le **CLI vrg** pour la gestion à distance. ## Vue d’ensemble de l’API REST L’API VergeOS suit les conventions REST standard avec des charges utiles JSON, prenant en charge l’intégralité du cycle de vie de chaque ressource de la plateforme. ### Méthodes HTTP | Méthode | Rôle | Exemple | | ---------- | ---------------------------------------------- | ----------------------------- | | **GET** | Récupérer des ressources | `GET /api/v4/vms?fields=most` | | **POST** | Créer des ressources ou déclencher des actions | `POST /api/v4/vms` | | **PUT** | Mettre à jour des ressources existantes | `PUT /api/v4/vms/36` | | **DELETE** | Supprimer des ressources | `DELETE /api/v4/vms/36` | ### Paramètres de requête Chaque requête GET prend en charge le filtrage de style OData et la sélection de champs : * **`champs`** — Spécifiez les champs à renvoyer (par ex., `fields=name,$key,ram` ou `fields=most` pour tous les champs courants) * **`filter`** — Expressions de filtre de style OData (par ex., `filter=is_snapshot eq false`) * **`sort`** — Triez les résultats par champ (par ex., `sort=name`) * **`limit`** / **`offset`** — Contrôles de pagination pour les ensembles de résultats volumineux ### Formats de données Toutes les réponses de l’API sont renvoyées au **format JSON**. Les corps des requêtes pour les opérations POST et PUT doivent également être en JSON avec l’ `en-tête Content-Type: application/json` . ### Limites de débit L’API prend en charge un maximum de **1 000 requêtes par heure** par clé API. Pour les automatisations à fort volume, regroupez les opérations lorsque c’est possible et implémentez une logique de réessai avec backoff exponentiel. ## Authentification VergeOS prend en charge deux méthodes d’authentification — l’authentification HTTP Basic et l’authentification par jeton — chacune adaptée à différents cas d’utilisation. Les clés API à longue durée de vie sont une variante de la méthode par jeton, présentées comme un jeton Bearer plutôt que comme un jeton de session : ### 1. Authentification HTTP Basic La méthode la plus simple — transmettez les identifiants directement avec chaque requête. Tout le trafic API nécessite HTTPS. ```bash curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\ --basic --user "admin:password" \\ -H "Accept: application/json" ``` ### 2. Authentification par jeton (jetons de session) Demandez un jeton de session en envoyant par POST les identifiants à `/sys/tokens`. Utilisez le jeton renvoyé dans les requêtes suivantes via l’ `x-yottabyte-token` en-tête : ```bash # Étape 1 : Obtenir un jeton curl --basic \\ --data-ascii '{"login": "admin", "password": "secret"}' \\ --request "POST" \\ --header "Content-Type: application/json" \\ "https://vergeos.example.com/api/sys/tokens" # La réponse inclut la clé du jeton : # {"location":"/sys/tokens/3a334...","$key":"3a334..."} # Étape 2 : Utiliser le jeton dans les requêtes suivantes curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\ -H "x-yottabyte-token: 3a334..." \\ -H "Accept: application/json" # Étape 3 : Se déconnecter une fois terminé curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..." ``` #### Variante du jeton Bearer : clés API à longue durée de vie Pour l’automatisation en production, créez des clés API persistantes via **Système → Utilisateurs → \[Utilisateur] → Clés API**. Ces clés sont une variante Bearer de l’authentification par jeton — elles fonctionnent comme des jetons Bearer et restent valides jusqu’à expiration ou suppression : ```bash curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \\ -H "Authorization: Bearer your-api-key-string" \\ -H "Content-Type: application/json" ``` Les clés API prennent en charge **des listes d’autorisation/interdiction d’IP** pour la sécurité et des **dates d’expiration**. Stockez-les dans des variables d’environnement plutôt que de les coder en dur : ```bash export VERGEOS_API_KEY="your-api-key-string" curl -X GET "https://vergeos.example.com/api/v4/system" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` {% hint style="warning" %} Les clés API ne sont affichées qu’une seule fois lors de la création. Si vous les perdez, vous devez supprimer la clé et en créer une nouvelle. {% endhint %} ## Explorateur d’API (Swagger) VergeOS inclut une **page de documentation Swagger** intégrée, générée dynamiquement à partir du système en cours d’exécution, affichant chaque table et opération disponible. **Pour y accéder :** 1. Connectez-vous à l’interface VergeOS 2. Accédez à **Système → Documentation de l’API** 3. Parcourez les points de terminaison disponibles, consultez les schémas et testez directement les appels API L’interface Swagger vous permet d’exécuter des appels API dans le navigateur et de voir la `curl` commande générée, le corps de la réponse et les en-têtes — ce qui en fait un excellent outil pour prototyper des scripts d’automatisation. ## Principaux points de terminaison de l’API L’API organise les ressources en tables. Voici les points de terminaison les plus utilisés : | Point de terminaison | Rôle | | ----------------------------- | ------------------------------------------------------- | | `/api/v4/vms` | Opérations CRUD des machines virtuelles | | `/api/v4/vm_actions` | Opérations d’alimentation de la VM, clonage, instantané | | `/api/v4/machine_drives` | Attacher/gérer les disques de stockage de la VM | | `/api/v4/machine_nics` | Configurer les interfaces réseau de la VM | | `/api/v4/machine_devices` | Passage de périphériques GPU/PCI | | `/api/v4/machine_status/{id}` | État d’alimentation et statut à l’exécution | | `/api/v4/vnets` | Gestion du réseau virtuel | | `/api/v4/vnet_rules` | Règles de pare-feu et de NAT | | `/api/v4/tenants` | Gestion des locataires (VDC) | | `/api/v4/nodes` | Informations sur les nœuds physiques | | `/api/v4/clusters` | Configuration du cluster | | `/api/sys/tokens` | Gestion des jetons de session | ### Introspection du schéma Ajoutez `/$table` à n’importe quel point de terminaison pour récupérer son schéma complet de base de données, y compris tous les champs et types disponibles : ```bash # Obtenir le schéma de la table des VM curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## Guide pas à pas de l’API du cycle de vie des VM Le flux d’automatisation le plus courant consiste à provisionner une VM complète via l’API. Ce processus en quatre étapes reproduit ce que fait l’interface utilisateur en coulisses : ```mermaid graph LR A["1. Créer la VM"] --> B["2. Ajouter un disque"] B --> C["3. Ajouter une NIC"] C --> D["4. Mettre sous tension"] style A fill:#e8f5e9,stroke:#2e7d32 style B fill:#e3f2fd,stroke:#1565c0 style C fill:#fff3e0,stroke:#ef6c00 style D fill:#fce4ec,stroke:#c62828 ``` ### Étape 1 : Créer la VM ```bash curl -X POST "https://vergeos.example.com/api/v4/vms" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\ -H "Content-Type: application/json" \\ -d '{ "name": "web-server-01", "description": "Serveur web de production", "machine_type": "pc-q35-9.0", "cpu_cores": 4, "cpu_type": "Cascadelake-Server", "ram": 8192, "os_family": "linux", "boot_order": "cd", "uefi": true, "allow_hotplug": true }' # Réponse : {"location":"/v4/vms/42","$key":"42"} ``` ### Étape 2 : Ajouter un disque de stockage ```bash curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\ -H "Content-Type: application/json" \\ -d '{ "machine": 42, "name": "boot-disk", "media": "disk", "interface": "virtio-scsi", "disksize": 107374182400, "preferred_tier": "1" }' ``` ### Étape 3 : Ajouter une interface réseau ```bash curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\ -H "Content-Type: application/json" \\ -d '{ "machine": 42, "vnet": 6, "interface": "virtio" }' ``` ### Étape 4 : Mettre sous tension ```bash curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \\ -H "Authorization: Bearer ${VERGEOS_API_KEY}" \\ -H "Content-Type: application/json" \\ -d '{ "vm": 42, "action": "poweron" }' ``` ### Actions supplémentaires Une fois la VM créée, vous pouvez déclencher des opérations avancées via le même `vm_actions` point de terminaison : ```bash # Cloner une VM curl -X POST ".../api/v4/vm_actions" \\ -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}' # Prendre un instantané curl -X POST ".../api/v4/vm_actions" \\ -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}' # Arrêter proprement curl -X POST ".../api/v4/vm_actions" \\ -d '{"vm": 42, "action": "poweroff"}' ``` ## Script utilitaire yb-api Le `yb-api` script est un wrapper en ligne de commande intégré disponible sur chaque nœud VergeOS via SSH. Il simplifie les appels API en gérant l’authentification, les en-têtes, la construction des URL, l’encodage des requêtes et le traitement des envois pour vous. ### Syntaxe de base ```bash yb-api --get|--post|--put|--delete [options] /v4/ ``` ### Options courantes | Option | Rôle | | ---------------- | ------------------------------------------------------ | | `--get` | Récupérer des ressources | | `--post='JSON'` | Créer une ressource avec une charge utile JSON | | `--put='JSON'` | Mettre à jour une ressource avec une charge utile JSON | | `--delete` | Supprimer une ressource | | `--server=IP` | Cibler un système VergeOS spécifique | | `--user=NAME` | S’authentifier en tant qu’utilisateur spécifique | | `--fields='...'` | Sélectionner les champs à renvoyer | | `--filter='...'` | Expression de filtre OData | ### Exemples d’utilisation ```bash # Lister toutes les VM (à l’exception des instantanés) avec leur statut yb-api --get --user=admin --server=10.0.0.100 \\ --fields='name,$key,ram,machine#status#status as machine_status' \\ --filter='is_snapshot eq false' /v4/vms # Obtenir des informations détaillées sur la VM, y compris les disques et les NIC yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1 # Créer une nouvelle VM yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux", "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms # Renommer une VM yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1 # Mettre une VM sous tension yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions # Obtenir le schéma de table des VM yb-api --get '/v4/vms/$table' ``` {% hint style="success" %} Le `yb-api` script est idéal pour des requêtes ponctuelles rapides et du scripting directement sur les nœuds VergeOS. Pour l’automatisation à distance depuis des postes de travail, utilisez le CLI vrg ou les SDK Python/PowerShell. {% endhint %} ## CLI vrg Le **vrg** outil en ligne de commande fournit une interface de gestion à distance complète pour VergeOS, développée en Python avec plus de **200 commandes** couvrant les VM, les réseaux, le stockage, les locataires et l’administration système. ### Installation Le CLI vrg est distribué via plusieurs canaux — choisissez celui qui convient à votre environnement. Aucun n’est limité par le système d’exploitation ; pipx est la voie recommandée sur tous les OS pris en charge. ```bash # pipx (recommandé — environnement Python isolé, tous les OS) pipx install vrg # pip (tous les OS) pip install vrg # uv (tous les OS) uv tool install vrg # Homebrew (tous les OS qui exécutent Homebrew) brew install verge-io/tap/vrg ``` Un binaire autonome (sans Python requis) est également publié pour **Linux x86\_64**, **macOS ARM64**, et **Windows x86\_64** — utile pour les hôtes Windows sans chaîne d’outils Python. ### Principales fonctionnalités ### Gestion des VM Créez, listez, démarrez, arrêtez, prenez des instantanés, clonez et supprimez des machines virtuelles avec des commandes simples. ### Opérations réseau Gérez les réseaux virtuels, les règles de pare-feu, les paramètres DHCP et les configurations VPN. ### Contrôle du stockage Administrez les volumes NAS, les partages CIFS/NFS et surveillez les niveaux vSAN. ### Gestion des locataires Provisionnez des locataires, allouez des ressources et gérez des environnements multi-locataires. Le CLI vrg encapsule la même API REST documentée ci-dessus, offrant l’autocomplétion, une sortie formatée et une interface plus ergonomique pour les opérations quotidiennes depuis votre poste de travail. ## Gestion des erreurs de l’API Lorsque les appels API échouent, VergeOS renvoie des codes d’état HTTP standard avec des corps d’erreur JSON descriptifs : | Code d’état | Signification | Cause fréquente | | ----------- | -------------------- | ---------------------------------------------------------------------- | | **401** | Non autorisé | Identifiants invalides ou jeton expiré | | **403** | Interdit | Permissions insuffisantes pour l’opération | | **404** | Introuvable | La ressource n’existe pas ou le point de terminaison est invalide | | **409** | Conflit | Conflit d’état de la ressource (par ex., VM déjà en cours d’exécution) | | **422** | Erreur de validation | Paramètres invalides ou champs requis manquants | | **429** | Limitation de débit | Limite de 1 000 requêtes/heure dépassée | | **500** | Erreur du serveur | Erreur interne — consultez les journaux système | {% hint style="info" %} **Vous venez de VMware ou de Nutanix ?** VergeOS expose une unique `/api/v4/` surface versionnée pour chaque opération — l’interface utilisateur elle-même n’est qu’un client de cette API. L’explorateur Swagger intégré est généré dynamiquement à partir du schéma en direct du système en cours d’exécution, de sorte que la documentation correspond toujours à ce que l’API accepte actuellement. {% endhint %} ## Bonnes pratiques pour l’automatisation via l’API 1. **Utilisez des clés API** pour l’automatisation en production au lieu des jetons de session — ils n’expirent pas en cas d’inactivité 2. **Appliquez des restrictions IP** sur les clés API pour limiter où elles peuvent être utilisées 3. **Sélectionnez des champs spécifiques** (`fields=name,$key,ram`) plutôt que `fields=most` pour réduire la taille de la charge utile 4. **Mettez en place la pagination** avec `limit` et `offset` pour les ensembles de résultats volumineux 5. **Gérez les opérations asynchrones** — des actions comme le clonage et l’instantané renvoient immédiatement ; interrogez `machine_status` pour l’achèvement 6. **Stockez les identifiants dans des variables d’environnement** — n’intégrez jamais les jetons en dur dans les scripts 7. **Utilisez l’introspection du schéma** (`/$table`) pour découvrir les champs disponibles avant d’écrire l’automatisation ## Et ensuite Maintenant que vous comprenez l’API brute, les pages suivantes couvrent des outils de plus haut niveau qui encapsulent cette API dans des interfaces natives au langage : * **SDK Python (pyvergeos)** — wrapper Pythonique, avec annotations de type, gestionnaires de ressources et générateur de filtres OData * **Module PowerShell (PSVergeOS)** — plus de 200 cmdlets avec prise en charge du pipeline pour l’automatisation native sous Windows --- # 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/learn-the-platform/fr/module-8-developpeur-et-devops/01-api-cli.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.