> 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/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md).

# SDK Python VergeOS (pyvergeos)

## Vue d'ensemble

pyvergeos est un SDK Python pour gérer l'infrastructure VergeOS via l'API REST. Il fournit une interface Pythonique, annotée avec des types, pour automatiser le cycle de vie des VM, le réseau, le stockage, les opérations multi-locataires et les flux de reprise après sinistre, ce qui le rend idéal pour les scripts d'automatisation, le développement d'outils et les intégrations.

## Fonctionnalités clés

* **Gestion des VM**: Création, configuration, contrôle d'alimentation, clonage et instantanés
* **Réseautage avancé**: Réseaux virtuels, règles de pare-feu, DHCP, DNS, VPN IPSec et WireGuard
* **NAS et stockage**: Gestion des volumes, partages CIFS/NFS et synchronisation
* **Multi-location**: Provisionnement des locataires avec isolation des ressources
* **Reprise après sinistre**: Instantanés cloud, synchronisation des sites et flux de récupération
* **Filtrage**: Prise en charge du filtrage OData avec une API de génération de filtres fluide
* **Annotations de type**: Indications de type complètes pour l'autocomplétion de l'IDE et l'analyse statique
* **Multiplateforme**: Prise en charge de Windows, macOS et Linux

## Prérequis

* Python 3.9 ou version ultérieure
* VergeOS 26.0 ou version ultérieure

## Installation

### Depuis PyPI (recommandé)

```bash
pip install pyvergeos
```

### Avec uv

```bash
uv add pyvergeos
```

### Depuis les sources

```bash
git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .
```

## Authentification

Le SDK prend en charge plusieurs méthodes d'authentification :

### Nom d'utilisateur/mot de passe

```python
from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Pour les certificats auto-signés
)
```

{% hint style="info" %}
**Vérification du certificat SSL**

Définissez `verify_ssl=False` uniquement pour les environnements avec des certificats auto-signés. Pour les environnements de production avec des certificats valides, omettez ce paramètre ou définissez-le sur `True`.
{% endhint %}

### Jeton d'API

```python
client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)
```

### Variables d'environnement

```bash
export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
```

```python
client = VergeClient.from_env()
```

{% hint style="success" %}
**Recommandé pour la production**

L'utilisation de variables d'environnement permet de garder les identifiants hors de votre code source et facilite l'utilisation d'identifiants différents selon les environnements.
{% endhint %}

### Gestionnaire de contexte

```python
with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
```

{% hint style="success" %}
**Nettoyage automatique**

L'utilisation du gestionnaire de contexte (`with` instruction) garantit que la connexion est correctement fermée, même si une exception se produit.
{% endhint %}

## Ressources disponibles

Le SDK donne accès aux ressources VergeOS suivantes :

| Catégorie                            | Ressources                                                                 |
| ------------------------------------ | -------------------------------------------------------------------------- |
| Machines virtuelles                  | VM, disques, NIC, instantanés                                              |
| Réseautage                           | Réseaux, règles, DNS, DHCP, alias, hôtes                                   |
| VPN                                  | Connexions IPSec, interfaces et pairs WireGuard                            |
| NAS/Stockage                         | Services, volumes, partages CIFS/NFS, synchronisations de volumes          |
| Locataires                           | Gestion des locataires, instantanés, stockage, blocs réseau                |
| Utilisateurs et groupes              | Utilisateurs, groupes, permissions, clés API                               |
| Système                              | Clusters, nœuds, niveaux de stockage, certificats                          |
| Surveillance                         | Alertes, journaux, tâches                                                  |
| Sauvegarde et reprise après sinistre | Profils d'instantanés, instantanés cloud, sites, synchronisations de sites |

## Exemples d'utilisation

### Gestion des machines virtuelles

```python
from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Lister toutes les VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram} Mo de RAM, {vm.cpu_cores} cœurs")

# Obtenir une VM spécifique
vm = client.vms.get(name="web-server")

# Créer une VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Opérations d'alimentation
vm.power_on()
vm.power_off()
vm.reset()

# Instantanés
vm.snapshot(retention=86400, quiesce=True)

# Cloner une VM
clone = vm.clone(name="test-clone")

# Ajouter des disques et des NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()
```

### Création et gestion des réseaux

```python
# Créer un réseau virtuel
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

# Ajouter des règles de pare-feu
network.rules.create(
    name="Allow SSH",
    action="accept",
    protocol="tcp",
    dest_port=22
)
```

### Filtrage des ressources

Le SDK prend en charge plusieurs approches de filtrage :

{% tabs %}
{% tab title="Arguments nommés" %}

```python
# Simple et lisible pour les filtres de base
vms = client.vms.list(status="running", name="prod-*")
```

{% endtab %}

{% tab title="Chaîne de filtre OData" %}

```python
# Syntaxe complète de filtre OData pour les requêtes complexes
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")
```

{% endtab %}

{% tab title="Générateur de filtres" %}

```python
# API fluide pour construire des filtres par programmation
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))
```

{% endtab %}
{% endtabs %}

### Attente des tâches

De nombreuses opérations dans VergeOS s'exécutent de manière asynchrone. Utilisez le gestionnaire de tâches pour attendre la fin :

```python
result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)
```

{% hint style="info" %}
**Opérations asynchrones**

Les opérations comme les instantanés, les clones et les migrations renvoient immédiatement un identifiant de tâche. Utilisez `client.tasks.wait()` pour bloquer jusqu'à ce que l'opération soit terminée.
{% endhint %}

## Gestion des erreurs

Le SDK fournit des types d'exceptions spécifiques pour différents cas d'erreur :

```python
from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("VM introuvable")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tâche {e.task_id} a expiré")
```

{% hint style="info" %}
**Types d'exceptions disponibles**
{% endhint %}

| Exception             | Description                                                            |
| --------------------- | ---------------------------------------------------------------------- |
| `VergeError`          | Exception de base pour toutes les erreurs du SDK                       |
| `AuthenticationError` | Identifiants invalides ou jeton expiré                                 |
| `NotFoundError`       | La ressource demandée n'existe pas                                     |
| `ConflictError`       | Conflit d'état de la ressource (par ex., VM déjà en cours d'exécution) |
| `ValidationError`     | Valeurs de paramètre invalides                                         |
| `TaskTimeoutError`    | La tâche n'a pas été terminée dans le délai imparti                    |
| `TaskError`           | La tâche a échoué pendant l'exécution                                  |

## Cas d'utilisation courants

* **Automatisation de l'infrastructure**: Provisionner des VM, des réseaux et du stockage par programmation
* **Intégration CI/CD**: Créer et détruire des environnements de test dans les pipelines
* **Surveillance et reporting**: Interroger l'état des ressources et générer des rapports d'inventaire
* **Automatisation des sauvegardes**: Planifier et gérer les instantanés et les sauvegardes cloud
* **Provisionnement multi-locataire**: Automatiser la création des locataires et l'allocation des ressources

## Documentation et ressources

Pour une documentation complète, y compris toutes les méthodes disponibles et des exemples d'utilisation détaillés, visitez le dépôt officiel :

* [Dépôt GitHub](https://github.com/verge-io/pyvergeos)
* [Package PyPI](https://pypi.org/project/pyvergeos/)

## Support

Si vous rencontrez des problèmes ou avez des demandes de fonctionnalités, veuillez ouvrir un ticket sur le dépôt GitHub :

<https://github.com/verge-io/pyvergeos/issues>

## Ressources supplémentaires

* [Documentation Python](https://docs.python.org/3/)
* [Documentation de l'API VergeOS](/knowledge-base/fr/automation-api/verge-api-guide.md)
* [Module PowerShell PSVergeOS](/automate-protect-and-extend/fr/integrations-et-api/powershell-module.md) - alternative PowerShell
* [Fournisseur Terraform](/automate-protect-and-extend/fr/integrations-et-api/terraform-provider.md) - Infrastructure as code


---

# 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/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md?ask=<question>&goal=<endgoal>
```

`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.