> 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/de/modul-8-entwicklung-and-devops/01-api-cli.md). # REST-API- und CLI-Tools Jede Operation, die Sie in der VergeOS-Oberfläche ausführen, wird direkt einer REST-API-Anfrage zugeordnet. Dies **API-first-Design** bedeutet, dass alles, worauf Sie im Dashboard klicken können – das Erstellen von VMs, das Konfigurieren von Netzwerken, das Verwalten von Mandanten – über HTTP-Endpunkte automatisiert werden kann. Dieser Abschnitt behandelt die drei primären Schnittstellen für den programmgesteuerten Zugriff: die **REST-API** selbst, das **yb-api-Hilfsskript** für die Automatisierung auf dem System selbst und die **vrg-CLI** für die Fernverwaltung. ## Übersicht über die REST-API Die VergeOS-API folgt den üblichen REST-Konventionen mit JSON-Nutzlasten und unterstützt den vollständigen Lebenszyklus jeder Ressource auf der Plattform. ### HTTP-Methoden | Methode | Zweck | Beispiel | | ---------- | ------------------------------------------- | ----------------------------- | | **GET** | Ressourcen abrufen | `GET /api/v4/vms?fields=most` | | **POST** | Ressourcen erstellen oder Aktionen auslösen | `POST /api/v4/vms` | | **PUT** | Vorhandene Ressourcen aktualisieren | `PUT /api/v4/vms/36` | | **DELETE** | Ressourcen entfernen | `DELETE /api/v4/vms/36` | ### Abfrageparameter Jede GET-Anfrage unterstützt OData-ähnliche Filterung und Feldauswahl: * **`Felder`** — Geben Sie an, welche Felder zurückgegeben werden sollen (z. B. `fields=name,$key,ram` oder `fields=most` für alle gängigen Felder) * **`filter`** — OData-ähnliche Filterausdrücke (z. B. `filter=is_snapshot eq false`) * **`sort`** — Ergebnisse nach Feld sortieren (z. B. `sort=name`) * **`limit`** / **`offset`** — Paginierungssteuerung für große Ergebnislisten ### Datenformate Alle API-Antworten werden im **JSON-Format** zurückgegeben. Die Request-Bodies für POST- und PUT-Operationen müssen ebenfalls JSON mit dem `Content-Type: application/json` Header sein. ### Ratenbegrenzungen Die API unterstützt maximal **1.000 Anfragen pro Stunde** pro API-Schlüssel. Für Automatisierung mit hohem Volumen sollten Sie nach Möglichkeit Batch-Operationen verwenden und eine Wiederholungslogik mit exponentiellem Backoff implementieren. ## Authentifizierung VergeOS unterstützt zwei Authentifizierungsmethoden – Basic-HTTP-Authentifizierung und tokenbasierte Authentifizierung – jeweils für unterschiedliche Anwendungsfälle geeignet. Langzeitgültige API-Schlüssel sind eine Variante der Token-Methode und werden als Bearer-Token statt als Sitzungstoken übergeben: ### 1. Basic-HTTP-Authentifizierung Die einfachste Methode – übergeben Sie die Anmeldedaten direkt mit jeder Anfrage. Der gesamte API-Verkehr erfordert HTTPS. ```bash curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \ --basic --user "admin:password" \ -H "Accept: application/json" ``` ### 2. Tokenbasierte Authentifizierung (Sitzungstoken) Fordern Sie ein Sitzungstoken an, indem Sie Anmeldedaten per POST an `/sys/tokens`senden. Verwenden Sie das zurückgegebene Token in nachfolgenden Anfragen über den `x-yottabyte-token` Header: ```bash # Schritt 1: Ein Token abrufen curl --basic \ --data-ascii '{"login": "admin", "password": "secret"}' \ --request "POST" \ --header "Content-Type: application/json" \ "https://vergeos.example.com/api/sys/tokens" # Die Antwort enthält den Token-Schlüssel: # {"location":"/sys/tokens/3a334...","$key":"3a334..."} # Schritt 2: Das Token in nachfolgenden Anfragen verwenden curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \ -H "x-yottabyte-token: 3a334..." \ -H "Accept: application/json" # Schritt 3: Bei Bedarf abmelden curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..." ``` #### Bearer-Token-Variante: Langzeitgültige API-Schlüssel Für die Produktionsautomatisierung erstellen Sie persistente API-Schlüssel über **System → Users → \[User] → API Keys**. Diese Schlüssel sind eine Bearer-Token-Variante der Token-Authentifizierung – sie funktionieren als Bearer-Tokens und bleiben bis zum Ablauf oder zur Löschung gültig: ```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" ``` API-Schlüssel unterstützen **IP-Zulassungs-/Sperrlisten** für die Sicherheit und konfigurierbare **Ablaufdaten**. Speichern Sie sie in Umgebungsvariablen statt sie fest zu codieren: ```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" %} API-Schlüssel werden nur einmal bei der Erstellung angezeigt. Wenn sie verloren gehen, müssen Sie den Schlüssel löschen und einen neuen erstellen. {% endhint %} ## API Explorer (Swagger) VergeOS enthält eine integrierte **Swagger-Dokumentationsseite** die dynamisch aus dem laufenden System generiert wird und jede verfügbare Tabelle und Operation anzeigt. **So greifen Sie darauf zu:** 1. Melden Sie sich in der VergeOS-Oberfläche an 2. Navigieren Sie zu **System → API-Dokumentation** 3. Durchsuchen Sie verfügbare Endpunkte, sehen Sie Schemata an und testen Sie API-Aufrufe direkt Mit der Swagger-Oberfläche können Sie API-Aufrufe im Browser ausführen und den resultierenden `curl` Befehl, Antwortkörper und Header anzeigen – dadurch ist sie ein hervorragendes Werkzeug zum Prototyping von Automatisierungsskripten. ## Wichtige API-Endpunkte Die API organisiert Ressourcen in Tabellen. Hier sind die am häufigsten verwendeten Endpunkte: | Endpunkt | Zweck | | ----------------------------- | ---------------------------------------- | | `/api/v4/vms` | CRUD-Operationen für virtuelle Maschinen | | `/api/v4/vm_actions` | VM-Energieoperationen, Klonen, Snapshot | | `/api/v4/machine_drives` | VM-Speicherlaufwerke anhängen/verwalten | | `/api/v4/machine_nics` | VM-Netzwerkschnittstellen konfigurieren | | `/api/v4/machine_devices` | GPU-/PCI-Geräte-Passthrough | | `/api/v4/machine_status/{id}` | Laufzeit-Energiezustand und Status | | `/api/v4/vnets` | Verwaltung virtueller Netzwerke | | `/api/v4/vnet_rules` | Firewall- und NAT-Regeln | | `/api/v4/tenants` | Mandantenverwaltung (VDC) | | `/api/v4/nodes` | Informationen zum physischen Knoten | | `/api/v4/clusters` | Cluster-Konfiguration | | `/api/sys/tokens` | Verwaltung von Sitzungstokens | ### Schema-Introspektion Hängen Sie `/$table` an einen beliebigen Endpunkt an, um dessen vollständiges Datenbankschema abzurufen, einschließlich aller verfügbaren Felder und Typen: ```bash # Das VM-Tabellenschema abrufen curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \ -H "Authorization: Bearer ${VERGEOS_API_KEY}" ``` ## API-Übersicht zum VM-Lebenszyklus Der häufigste Automatisierungs-Workflow ist die Bereitstellung einer vollständigen VM über die API. Dieser vierstufige Prozess spiegelt wider, was die Oberfläche im Hintergrund tut: ```mermaid graph LR A["1. VM erstellen"] --> B["2. Laufwerk hinzufügen"] B --> C["3. NIC hinzufügen"] C --> D["4. Einschalten"] style A fill:#e8f5e9,stroke:#2e7d32 style B fill:#e3f2fd,stroke:#1565c0 style C fill:#fff3e0,stroke:#ef6c00 style D fill:#fce4ec,stroke:#c62828 ``` ### Schritt 1: Die VM erstellen ```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": "Produktions-Webserver", "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 }' # Antwort: {"location":"/v4/vms/42","$key":"42"} ``` ### Schritt 2: Ein Speicherlaufwerk hinzufügen ```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" }' ``` ### Schritt 3: Eine Netzwerkschnittstelle hinzufügen ```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" }' ``` ### Schritt 4: Einschalten ```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" }' ``` ### Weitere Aktionen Sobald die VM existiert, können Sie erweiterte Operationen über denselben `vm_actions` Endpunkt auslösen: ```bash # Eine VM klonen curl -X POST ".../api/v4/vm_actions" \ -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}' # Einen Snapshot erstellen curl -X POST ".../api/v4/vm_actions" \ -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}' # Graceful herunterfahren curl -X POST ".../api/v4/vm_actions" \ -d '{"vm": 42, "action": "poweroff"}' ``` ## yb-api-Hilfsskript Das `yb-api` ist ein integrierter Kommandozeilen-Wrapper, der auf jedem VergeOS-Knoten per SSH verfügbar ist. Er vereinfacht API-Aufrufe, indem er Authentifizierung, Header, URL-Erstellung, Abfragecodierung und Upload-Verarbeitung für Sie übernimmt. ### Grundsyntax ```bash yb-api --get|--post|--put|--delete [Optionen] /v4/ ``` ### Häufige Optionen | Schalter | Zweck | | ---------------- | ---------------------------------------------- | | `--get` | Ressourcen abrufen | | `--post='JSON'` | Eine Ressource mit JSON-Nutzlast erstellen | | `--put='JSON'` | Eine Ressource mit JSON-Nutzlast aktualisieren | | `--delete` | Eine Ressource löschen | | `--server=IP` | Auf ein bestimmtes VergeOS-System zielen | | `--user=NAME` | Als bestimmter Benutzer authentifizieren | | `--fields='...'` | Zu übergebende Felder auswählen | | `--filter='...'` | OData-Filterausdruck | ### Anwendungsbeispiele ```bash # Alle VMs auflisten (ohne Snapshots) mit Status 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 # Detaillierte VM-Informationen einschließlich Laufwerken und NICs abrufen yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1 # Eine neue VM erstellen 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 # Eine VM umbenennen yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1 # Eine VM einschalten yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions # Tabellenschema für VMs abrufen yb-api --get '/v4/vms/$table' ``` {% hint style="success" %} Das `yb-api` ist ideal für schnelle Ad-hoc-Abfragen und Skripting direkt auf VergeOS-Knoten. Für die Fernautomatisierung von Arbeitsstationen aus verwenden Sie die vrg-CLI oder die Python-/PowerShell-SDKs. {% endhint %} ## vrg-CLI Das **vrg** Befehlszeilentool bietet eine voll ausgestattete Schnittstelle für die Fernverwaltung von VergeOS, in Python erstellt, mit über **200 Befehlen** für VMs, Netzwerke, Speicher, Mandanten und Systemadministration. ### Installation Die vrg-CLI wird über mehrere Kanäle verteilt — wählen Sie den, der zu Ihrer Umgebung passt. Keiner davon ist an ein Betriebssystem gebunden; pipx ist der empfohlene Weg auf jedem unterstützten OS. ```bash # pipx (empfohlen — isolierte Python-Umgebung, alle OSes) pipx install vrg # pip (alle OSes) pip install vrg # uv (alle OSes) uv tool install vrg # Homebrew (alle OSes, auf denen Homebrew läuft) brew install verge-io/tap/vrg ``` Eine eigenständige Binärdatei (kein Python erforderlich) wird ebenfalls veröffentlicht für **Linux x86\_64**, **macOS ARM64**, und **Windows x86\_64** — nützlich für Windows-Hosts ohne Python-Toolchain. ### Wichtige Funktionen ### VM-Verwaltung Virtuelle Maschinen mit einfachen Befehlen erstellen, auflisten, starten, stoppen, Snapshots erstellen, klonen und löschen. ### Netzwerkoperationen Virtuelle Netzwerke, Firewall-Regeln, DHCP-Einstellungen und VPN-Konfigurationen verwalten. ### Speicherverwaltung NAS-Volumes, CIFS-/NFS-Freigaben verwalten und vSAN-Tiers überwachen. ### Mandantenverwaltung Mandanten bereitstellen, Ressourcen zuweisen und Multi-Tenant-Umgebungen verwalten. Die vrg-CLI umschließt dieselbe oben dokumentierte REST-API und bietet Tab-Vervollständigung, formatierten Output und eine ergonomischere Oberfläche für den täglichen Betrieb von Ihrem Arbeitsplatz aus. ## API-Fehlerbehandlung Wenn API-Aufrufe fehlschlagen, gibt VergeOS standardmäßige HTTP-Statuscodes mit beschreibenden JSON-Fehlerkörpern zurück: | Statuscode | Bedeutung | Häufige Ursache | | ---------- | ------------------------ | ------------------------------------------------------ | | **401** | Nicht autorisiert | Ungültige Anmeldedaten oder abgelaufenes Token | | **403** | Verboten | Unzureichende Berechtigungen für die Operation | | **404** | Nicht gefunden | Ressource existiert nicht oder ungültiger Endpunkt | | **409** | Konflikt | Konflikt im Ressourcenstatus (z. B. VM läuft bereits) | | **422** | Validierungsfehler | Ungültige Parameter oder fehlende erforderliche Felder | | **429** | Ratenbegrenzung erreicht | Limit von 1.000 Anfragen/Stunde überschritten | | **500** | Serverfehler | Interner Fehler — Systemprotokolle prüfen | {% hint style="info" %} **Kommen Sie von VMware oder Nutanix?** VergeOS stellt eine einzige versionierte `/api/v4/` Oberfläche für jede Operation bereit — die Oberfläche selbst ist nur ein Client dieser API. Der integrierte Swagger-Explorer wird dynamisch aus dem Live-Schema des laufenden Systems generiert, sodass die Dokumentation immer mit dem übereinstimmt, was die API aktuell akzeptiert. {% endhint %} ## Bewährte Methoden für die API-Automatisierung 1. **Verwenden Sie API-Schlüssel** für die Produktionsautomatisierung statt Sitzungstoken — sie laufen bei Inaktivität nicht ab 2. **Wenden Sie IP-Einschränkungen an** für API-Schlüssel an, um zu begrenzen, wo sie verwendet werden können 3. **Bestimmte Felder auswählen** (`fields=name,$key,ram`) statt `fields=most` um die Nutzlastgröße zu reduzieren 4. **Paginierung implementieren** mit `limit` und `offset` für große Ergebnislisten 5. **Asynchrone Operationen behandeln** — Aktionen wie Klonen und Snapshot werden sofort zurückgegeben; abfragen `machine_status` bis zum Abschluss 6. **Anmeldedaten in Umgebungsvariablen speichern** — Tokens niemals fest in Skripten hinterlegen 7. **Schema-Introspektion verwenden** (`/$table`), um verfügbare Felder vor dem Schreiben von Automatisierungen zu ermitteln ## Wie geht es weiter Jetzt, da Sie die rohe API verstanden haben, behandeln die folgenden Seiten höherstufige Werkzeuge, die diese API in sprachnative Schnittstellen einbetten: * **Python SDK (pyvergeos)** — Pythonischer, typannotierter Wrapper mit Ressourcenmanagern und OData-Filter-Builder * **PowerShell-Modul (PSVergeOS)** — über 200 Cmdlets mit Pipeline-Unterstützung für Windows-native Automatisierung --- # 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/de/modul-8-entwicklung-and-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.