API-Anleitung

Eine umfassende Anleitung zur Nutzung der VergeOS-API, einschließlich Authentifizierung, HTTP-Methoden, Endpunktkonventionen, Filtern, Sortieren, Fehlerbehandlung und Beispielanfragen für VMs und virtuelle Netzwerke.

Ü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:

Melden Sie sich mit gültigen Anmeldedaten am VergeOS-System an.
Wählen Sie System im oberen Menü aus.
Wählen Sie API-Dokumentations.
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
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.
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:

Basic-HTTP-Authentifizierung Die API ist nur über SSL verfügbar.
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:

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:

{
   "location":"\\/sys\\/tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "dbpath":"tokens\\/3a334563456378845634563b7b82d2efcadce9",
   "$row":1,
   "$key":"3a334563456378845634563b7b82d2efcadce9"
}

Verwenden Sie das Token aus dem "$key" Feld in allen nachfolgenden Anfragen:

x-yottabyte-token: 3a334563456378845634563b7b82d2efcadce9

Um sich abzumelden, senden Sie eine DELETE-Anfrage an den /sys/tokens/{token} Endpoint.

Beispiel für eine Abmeldeanfrage

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:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vms?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Beispielantwort:

[
  {
    "$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:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vms' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-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:

{
  "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:

curl -X 'GET' \
  'https://your-verge-instance.com/api/v4/vnets?fields=most' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-token>'

Beispielantwort:

[
  {
    "$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:

curl -X 'POST' \
  'https://your-verge-instance.com/api/v4/vnets' \
  -H 'accept: application/json' \
  -H 'x-yottabyte-token: <your-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:

{
  "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://user1:xxxxxx@server1.verge.io/api/v4/machines?fields=all

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.
Beispiel: filter=enabled eq true and size gt 1048576.
Beispiel: filter=cputype eq 'qemu' or cputype eq 'kvm'.

Operator

Beschreibung

Gleich

Ungleich

Größer als

Größer als oder gleich

Kleiner als

Kleiner als oder gleich

Beginnt mit

Endet mit

und

Logisches UND

oder

Logisches ODER

Enthält Zeichenfolge (Groß-/Kleinschreibung beachten)

Enthält Text (Groß-/Kleinschreibung wird nicht beachtet)

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)

{
  "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.

Dokumentinformationen

Zuletzt aktualisiert: 2024-11-14
vergeOS-Version: 4.12.6

VorherigeAutomatisierung & API

NächsteAPI-Hilfsskript

Zuletzt aktualisiert vor 3 Monaten

War das hilfreich?