> 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/de/automation-api/verge-api-guide.md). # API-Leitfaden ## Überblick Die VergeOS-API ermöglicht es Entwicklern, programmgesteuert mit dem VergeOS-System zu interagieren. Sie bietet Zugriff auf Systemvorgänge wie das Erstellen virtueller Maschinen, das Verwalten von Ressourcen und die Interaktion mit Abrechnungs- und Katalog-Repositorys. Die API verwendet standardmäßige REST-ähnliche Konventionen und unterstützt mehrere Authentifizierungsmethoden. Dieser Leitfaden bietet einen Überblick über die VergeOS-API, Endpoint-Dokumentation, Beispielanfragen und Fehlerbehandlung. Dieses Dokument beschreibt die Verwendung der API. Detaillierte Informationen zur API finden Sie in der VergeOS-Oberfläche als Swagger-Dokumentationsseite, die dynamisch generiert wird und eine vollständige Liste der verfügbaren API-Tabellen und -Operationen anzeigt. ### Swagger-Oberfläche Um auf die Swagger-Dokumentation in der VergeOS-Oberfläche zuzugreifen: 1. **Melden Sie sich** mit gültigen Anmeldedaten am VergeOS-System an. 2. Wählen Sie **System** im oberen Menü aus. 3. Wählen Sie **API-Dokumentations**. 4. Die Swagger-Dokumentationsseite wird geöffnet. Diese Seite bietet detaillierte Beispiele für jede API-Operation, einschließlich der Möglichkeit, die API direkt zu testen. ![Beispiel für Swagger-Dokumentation](/files/2d3ef76522bd5618f12d152789e0a2dafe867fb6) 5. Wählen Sie eine einzelne Tabelle aus und wählen Sie eine der verfügbaren **GET/POST/DELETE/PUT** Optionen aus, um API-Aktionen anzuzeigen und zu testen. 6. Geben Sie die Parameter an und klicken Sie auf die **Schaltfläche „Ausführen“** um den API-Befehl auszuführen. Dadurch wird die Antwort zurückgegeben, einschließlich des Antworttexts, des Headers und eines curl-Beispiels. ## API-Grundlagen ### HTTP-Methoden Die VergeOS-API verwendet Standard-HTTP-Methoden wie GET, POST, PUT und DELETE zur Bearbeitung von Ressourcen. ### GET-Parameter * **fields**: Geben Sie an, welche Felder im Ergebnissatz zurückgegeben werden sollen. * **filter**: Filtern Sie den Ergebnissatz anhand bestimmter Kriterien. * **sort**: Sortieren Sie die Ergebnisse nach einem angegebenen Feld. * **limit**: Begrenzen Sie die Anzahl der zurückgegebenen Ergebnisse. ### Authentifizierung Alle API-Anfragen müssen über HTTPS erfolgen und erfordern eine Authentifizierung mit grundlegender Zugriffsauthentifizierung oder einem Sitzungstoken. ## Zusätzliche Hinweise * **Ratenbegrenzungen**: Die API unterstützt maximal 1000 Anfragen pro Stunde und API-Schlüssel. * **Datenformate**: Alle Antworten werden im JSON-Format zurückgegeben. * **Paginierung**: Endpunkte, die große Datenmengen zurückgeben, unterstützen die Paginierung mit `offset` und `limit` Abfrageparametern. *** ## Authentifizierung VergeOS unterstützt zwei Authentifizierungsmethoden: 1. **Basic-HTTP-Authentifizierung**\ Die API ist nur über SSL verfügbar. 2. **Tokenbasierte Authentifizierung**\ Entwickler müssen ein Token von der API anfordern, indem sie an den `/sys/tokens` Endpoint posten. Das Token wird anschließend in nachfolgenden API-Anfragen im `x-yottabyte-token` Header übergeben. ### Beispiel für eine Authentifizierungsanfrage Um ein Token zu erhalten: ```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' ``` Beispielantwort: ```json { "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9", "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9", "$row":1, "$key":"3a334563456378845634563b7b82d2efcadce9" } ``` Verwenden Sie das Token aus dem `"$key"` Feld in allen nachfolgenden Anfragen: ```bash x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9 ``` Um sich abzumelden, senden Sie eine DELETE-Anfrage an den `/sys/tokens/{token}` Endpoint. ### Beispiel für eine Abmeldeanfrage ```bash DELETE /sys/tokens/3a334563456378845634563b7b82d2efcadce9 ``` *** ### Beispiel für virtuelle Maschinen Der **VMs** Abschnitt der VergeOS-API ermöglicht es Benutzern, virtuelle Maschinen programmgesteuert zu verwalten. Er umfasst Endpunkte zum Auflisten, Erstellen, Ändern und Löschen von VMs. ### Liste der virtuellen Maschinen abrufen **Endpunkt**:\ `GET /v4/vms?fields=most` **Beschreibung**: Ruft eine Liste aller VMs im System mit Details wie CPU-Kernen, RAM, Maschinentyp und Konfigurationsdetails ab. **Beispielanfrage**: ```bash curl -X 'GET' \ 'https://your-verge-instance.com/api/v4/vms?fields=most' \ -H 'accept: application/json' \ -H 'x-yottabyte-token: ' ``` **Beispielantwort**: ```json [ { "$key": 1, "name": "CentOS 7 (Latest) 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 } ] ``` **Überblick über die zurückgegebenen Daten**: * **$key**: Die eindeutige Kennung für die VM. * **name**: Der Name der virtuellen Maschine. * **machine**: Maschinen-ID, die der VM zugeordnet ist. * **cpu\_cores**: Anzahl der der VM zugewiesenen CPU-Kerne. * **ram**: Zugewiesene RAM-Menge (in MB). * **os\_family**: Betriebssystemtyp. * **uuid**: Universell eindeutige Kennung (UUID) für die VM. * **created**: Der Zeitstempel der Erstellung. * **modified**: Der Zeitstempel der letzten Änderung. *** ### Eine neue virtuelle Maschine erstellen **Endpunkt**:\ `POST /v4/vms` **Beschreibung**: Erstellt eine neue virtuelle Maschine mit spezifischen Konfigurationsdetails wie CPU-Kerne, RAM, Maschinentyp, Bootreihenfolge usw. **Beispielanfrage**: ```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": "test vm" }' ``` **Beispielantwort**: ```json { "location": "/v4/vms/36", "dbpath": "vms/36", "$row": 36, "$key": "36" } ``` **Überblick über die zurückgegebenen Daten**: * **location**: Der Speicherort der neu erstellten VM-Ressource. * **dbpath**: Datenbankpfad der neuen VM. * **$row**: Zeilen-ID der VM. * **$key**: Eindeutiger Schlüssel für die VM. *** ### Beispiel für virtuelle Netzwerke (Vnets) Der **Vnets** Abschnitt der VergeOS-API ermöglicht es Benutzern, virtuelle Netzwerke (Vnets) programmgesteuert zu verwalten. Er umfasst Endpunkte zum Abrufen, Erstellen und Verwalten von Netzwerkressourcen, einschließlich interner und externer Netzwerke, und ermöglicht erweiterte Optionen wie Ratenbegrenzung. ### Vnet-Details abrufen **Endpunkt**:\ `GET /v4/vnets?fields=most` **Beschreibung**: Ruft eine Liste aller Vnets im System mit Details wie Netzwerktyp, MTU, DHCP-Einstellungen und DNS-Konfiguration ab. **Beispielanfrage**: ```bash curl -X 'GET' \ 'https://your-verge-instance.com/api/v4/vnets?fields=most' \ -H 'accept: application/json' \ -H 'x-yottabyte-token: ' ``` **Beispielantwort**: ```json [ { "$key": 6, "name": "Internal Test 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": "" } ] ``` **Überblick über die zurückgegebenen Daten**: * **$key**: Die eindeutige Kennung für das Vnet. * **name**: Name des virtuellen Netzwerks. * **advanced\_options**: Erweiterte Optionen, die an Dienste übergeben werden, die innerhalb des Netzwerks ausgeführt werden; in diesem Beispiel Netboot-Flags für dnsmasq * **type**: Netzwerktyp (z. B. "internal"). * **layer2\_type**: Der Typ des Layer-2-Netzwerks, z. B. VXLAN. * **network**: Netzwerk-CIDR-Block. * **mtu**: Größe der Maximum Transmission Unit (MTU). * **dhcp\_enabled**: Gibt an, ob DHCP für dieses Netzwerk aktiviert ist. * **dhcp\_start**: Start-IP-Adresse für den DHCP-Pool. * **dhcp\_stop**: End-IP-Adresse für den DHCP-Pool. * **rate\_limit**: Ratenbegrenzung für das Netzwerk (in mbytes/second). * **gateway**: Das Standard-Gateway für das Netzwerk. *** ### Ein internes Netzwerk mit Ratenbegrenzung erstellen **Endpunkt**:\ `POST /v4/vnets` **Beschreibung**: Erstellt ein neues internes virtuelles Netzwerk mit Ratenbegrenzung und DHCP-Einstellungen. **Beispielanfrage**: ```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":"workloads", "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" }' ``` **Beispielantwort**: ```json { "location": "/v4/vnets/8", "dbpath": "vnets/8", "$row": 8, "$key": "8" } ``` **Überblick über die zurückgegebenen Daten**: * **location**: Der Speicherort der neu erstellten Vnet-Ressource. * **dbpath**: Datenbankpfad des neuen Vnet. * **$row**: Zeilen-ID des Vnet. * **$key**: Eindeutiger Schlüssel für das Vnet. *** ## Ressourcen Nachfolgend ein Beispiel für eine URL, die verwendet wird, um eine Liste von Maschinen abzufragen. *Beispiel: * | | | | | | | | | | | | --------- | ------------ | - | ---------------- | - | ----------------------- | ---- | ------------------------ | - | --------------------------------------- | | https\:// | Benutzer | : | Passwort | @ | Server | /api | /v4/machines | ? | filter=\&fields=all\&sort=\&limit= | | | Benutzername | | Benutzerpasswort | | Server-Hostname oder IP | | Ressourcenposition (URI) | | Diese Optionen werden unten beschrieben | ### GET-Optionen #### Felder * **Geben Sie an, welche Felder im Ergebnissatz zurückgegeben werden sollen (kann auch eine Ansicht sein, falls eine für das Tabellenschema definiert ist)**. * **alle** gibt jedes Feld zurück. * **meiste** gibt die meisten Felder zurück, außer Argumentfeldern und Zeilen. * **Zusammenfassung** gibt Felder zurück, die in ihrem Schema als 'summary' markiert sind. * Beispiel: `fields=name,email,enabled,groups[all] as all_groups,collapse(groups[name]) as first_groups_name` Feldfunktionen: * **collapse** * **datetime** * **upper** * **lower** * **count** * **diskspace** * **display** * **hex** * **sha1** * **sum** * **avg** * **min** * **max** #### Filter * Filtern Sie Ergebnismengen nach angegebenen Kriterien. * Ähnlich wie [OData](https://msdn.microsoft.com/en-us/library/gg309461\(v=crm.7\).aspx#BKMK_filter). * Beispiel: `filter=enabled eq true and size gt 1048576`. * Beispiel: `filter=cputype eq 'qemu' or cputype eq 'kvm'`. | Operator | Beschreibung | | -------- | -------------------------------------------------------- | | *eq* | Gleich | | *ne* | Ungleich | | *gt* | Größer als | | *ge* | Größer als oder gleich | | *lt* | Kleiner als | | *le* | Kleiner als oder gleich | | *bw* | Beginnt mit | | *ew* | Endet mit | | *und* | Logisches UND | | *oder* | Logisches ODER | | *cs* | Enthält Zeichenfolge (Groß-/Kleinschreibung beachten) | | *ct* | Enthält Text (Groß-/Kleinschreibung wird nicht beachtet) | | *rx* | Regex-Abgleich | #### Sortieren * Ergebnisse nach dem angegebenen Feld sortieren. * Beispiel: `sort=+name`. * Beispiel: `sort=-id`. #### Begrenzen * **limit** (Ganzzahl) begrenzt den Ergebnissatz auf eine bestimmte Anzahl von Einträgen. Ein Wert von 0 bedeutet unbegrenzt. * Beispiel: `limit=1`. ### Allgemeine HTTP-Antwortcodes * **400 - Ungültige Anfrage**: Die Anfrage war ungültig. * **401 - Anmeldefehler / Anmeldung erforderlich**: Authentifizierung fehlgeschlagen oder ist erforderlich. * **403 - Zugriff verweigert**: Sie verfügen nicht über die erforderlichen Berechtigungen. * **404 - Ressource nicht gefunden**: Die angeforderte Zeile oder API existiert nicht. * **405 - Nicht zulässig**: Der Vorgang ist nicht erlaubt. * **409 - Zeile existiert bereits**: Die Ressource existiert bereits. * **422 - Validierung fehlgeschlagen / Ungültiger Parameter**: Die Validierung ist fehlgeschlagen. * **500 - Interner Serverfehler**: Ein unbehandelter Fehler ist aufgetreten. #### POST-spezifisch * **201 - Erstellt**: Eine neue Zeile/Ressource wurde erfolgreich erstellt. #### Websocket-spezifisch (für VNC/SPICE verwendet) * **101 - Protokollwechsel**: Das Protokoll wurde erfolgreich umgeschaltet. #### PUT/GET/DELETE * **200 - Erfolg**: Der Vorgang wurde erfolgreich abgeschlossen. *** ### Schema-Tabellendefinitionen #### Feldtypen * **bool** * **text** * **string** * **num** * **uint8** * **uint16** * **uint32** * **uint64** * **int8** * **int16** * **int32** * **int64** * **aktiviert** * **created** * **created\_ms** * **created\_us** * **modified** * **modified\_ms** * **modified\_us** * **Dateiname** * **Dateigröße** * **fileused** * **fileallocated** * **filemodified** * **json** * **Zeile** * **Zeilen** #### Schema-Eigentümer / übergeordnetes Feld * **Eigentümerfeld**: Wenn das Eigentümerfeld null ist, gelten die normalen Berechtigungen. Wenn das Eigentümerfeld einen Wert hat, werden die Berechtigungen durch eine Berechtigungsprüfung für den Eigentümer ersetzt. * **Übergeordnetes Feld**: Die Berechtigungsprüfung wird auf die Zeile selbst angewendet, und wenn die Berechtigungen fehlschlagen, werden die Berechtigungen auch für die übergeordnete Zeile geprüft. *** ### Vollständiges Tabellenschema Um das Schema einer Tabelle abzurufen, hängen Sie **$table** an die URI an: **/api/v4/machines/$table** (ersetzen Sie "machines" durch den Tabellennamen). Sie werden zur Eingabe Ihrer Anmeldedaten aufgefordert; dafür sind VergeOS-Administratoranmeldedaten erforderlich. Die Ausgabe erfolgt im JSON-Format. Firefox zeigt dies standardmäßig in einem lesbaren Format an, aber andere Browser müssen das JSON möglicherweise in ein externes Programm exportieren, um eine bessere Lesbarkeit zu erreichen. *** ### Beispiel-Fehler #### Beispiel-Fehler (HTTP-Code 422) ```json { "err": "Validierungsfehler im Feld: 'dhcp_start' - 'fails validation test'" } ``` VergeOS verwendet standardmäßige HTTP-Statuscodes, um das Ergebnis einer API-Anfrage anzugeben. * **400 Ungültige Anfrage**: Die Anfrage ist ungültig oder kann nicht verarbeitet werden. * **401 Nicht autorisiert**: Der API-Schlüssel fehlt oder ist ungültig. * **403 Verboten**: Dem API-Schlüssel fehlen die erforderlichen Berechtigungen. * **404 Nicht gefunden**: Die Ressource existiert nicht. * **500 Interner Serverfehler**: Ein Serverfehler ist aufgetreten. *** {% hint style="info" %} **Dokumentinformationen** * Zuletzt aktualisiert: 2024-11-14 * vergeOS-Version: 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/de/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.