Details zur Implementierung der ONTAP tools REST API
Änderungen vorschlagen
PDFs
REST etabliert zwar einen gemeinsamen Satz an Technologien und Best Practices, die genaue Implementierung jeder API kann jedoch je nach Designentscheidungen variieren. Es empfiehlt sich, sich mit dem Design der ONTAP tools for VMware vSphere 10 REST API vertraut zu machen, bevor diese verwendet wird.
Die REST-API umfasst verschiedene Ressourcenkategorien wie vCenters und Aggregate. Weitere Informationen enthält die "API-Referenz".
Zugriff auf die REST API
Auf die ONTAP tools for VMware vSphere 10 REST API kann über die IP-Adresse der ONTAP tools zusammen mit dem Port zugegriffen werden. Die vollständige URL besteht aus mehreren Teilen, darunter:
-
ONTAP tools IP-Adresse und Port
-
API Version
-
Ressourcenkategorie
-
Spezifische Ressource
Die IP-Adresse muss während der Ersteinrichtung konfiguriert werden, während der Port fest auf 8443 bleibt. Der erste Teil der URL ist für jede ONTAP tools for VMware vSphere 10 Instanz gleich; nur die Ressourcenkategorie und die spezifische Ressource unterscheiden sich zwischen den Endpunkten.
|
Die in den folgenden Beispielen angegebenen IP-Adressen und Portwerte dienen lediglich der Veranschaulichung. Diese Werte sind für Ihre Umgebung anzupassen. |
https://10.61.25.34:8443/virtualization/api/v1/auth/login
Diese URL kann verwendet werden, um mit der POST-Methode ein Zugriffstoken anzufordern.
https://10.61.25.34:8443/virtualization/api/v1/vcenters
Diese URL kann verwendet werden, um mit der GET-Methode eine Liste der definierten vCenter Serverinstanzen anzufordern.
HTTP-Details
Die ONTAP tools for VMware vSphere 10 REST API verwendet HTTP (Hypertext Transfer Protocol) und zugehörige Parameter, um auf die Ressourceninstanzen und Sammlungen zuzugreifen. Details der HTTP (Hypertext Transfer Protocol)-Implementierung sind nachfolgend dargestellt.
HTTP-Methoden
Die von der REST API unterstützten HTTP-Methoden bzw. Verben sind in der folgenden Tabelle aufgeführt.
| Verfahren | CRUD | Beschreibung |
|---|---|---|
GET |
Lesen |
Ruft Objekteigenschaften einer Ressourceninstanz oder -sammlung ab. Bei Verwendung mit einer Sammlung handelt es sich um eine Listenoperation. |
POST |
Erstellen |
Erstellt eine neue Ressourceninstanz basierend auf den Eingabeparametern. |
PUT |
Aktualisieren |
Aktualisiert eine gesamte Ressourceninstanz mit dem bereitgestellten JSON-Anfragetext. Schlüsselwerte, die nicht vom Benutzer geändert werden können, bleiben erhalten. |
PATCH |
Aktualisieren |
Fordert die Anwendung einer Reihe ausgewählter Änderungen in der Anfrage auf die Ressourceninstanz an. |
LÖSCHEN |
Löschen |
Löscht eine bestehende Ressourceninstanz. |
Anfrage- und Antwortheader
Die folgende Tabelle fasst die wichtigsten HTTP-Header zusammen, die mit der REST API verwendet werden.
| Kopfzeile | Typ | Nutzungshinweise |
|---|---|---|
Akzeptieren |
Anfrage |
Dies ist der Inhaltstyp, den die Clientanwendung akzeptieren kann. Gültige Werte sind '*/*` oder |
x-auth |
Anfrage |
Enthält ein Zugriffstoken, das den Benutzer identifiziert, der die Anfrage über die Client-Anwendung ausstellt. |
Content-Type |
Antwort |
Wird vom Server basierend auf dem |
HTTP-Statuscodes
Die von der REST API verwendeten HTTP-Statuscodes sind nachfolgend beschrieben.
| Code | Bedeutung | Beschreibung |
|---|---|---|
200 |
OK |
Zeigt Erfolg für Aufrufe an, die keine neue Ressourceninstanz erstellen. |
201 |
Erstellt |
Ein Objekt wurde erfolgreich mit einer eindeutigen Kennung für die Ressourceninstanz erstellt. |
202 |
Akzeptiert |
Die Anfrage wurde angenommen und ein Hintergrundjob zur Ausführung der Anfrage erstellt. |
204 |
Kein Inhalt |
Die Anfrage war erfolgreich, obwohl kein Inhalt zurückgegeben wurde. |
400 |
Ungültige Anforderung |
Die Eingabe der Anfrage wird nicht erkannt oder ist ungeeignet. |
401 |
Nicht autorisiert |
Der Benutzer ist nicht autorisiert und muss sich authentifizieren. |
403 |
Verboten |
Der Zugriff wurde aufgrund eines Autorisierungsfehlers verweigert. |
404 |
Nicht gefunden |
Die in der Anfrage referenzierte Ressource existiert nicht. |
409 |
Konflikt |
Der Versuch, ein Objekt zu erstellen, ist fehlgeschlagen, da das Objekt bereits existiert. |
500 |
Interner Fehler |
Auf dem Server ist ein allgemeiner interner Fehler aufgetreten. |
Authentifizierung
Die Authentifizierung eines Clients an der REST API erfolgt mittels eines Zugriffstokens. Zu den relevanten Merkmalen des Tokens und des Authentifizierungsprozesses gehören:
-
Der Client muss ein Token mit den Administratoranmeldeinformationen (Benutzername und Passwort) des ONTAP tools Manager anfordern.
-
Tokens sind im JSON Web Token (JWT)-Format formatiert.
-
Jeder Token läuft nach 60 Minuten ab.
-
API-Anfragen von einem Client müssen das Token im
x-authAnfrageheader enthalten.
Ein Beispiel für die Anforderung und Verwendung eines Zugriffstokens findet sich unter "Ihr erster REST-API-Aufruf".
Synchrone und asynchrone Anfragen
Die meisten REST API-Aufrufe werden schnell abgeschlossen und daher synchron ausgeführt. Das heißt, sie geben nach Abschluss der Anfrage einen Statuscode (wie 200) zurück. Anfragen, die länger dauern, werden asynchron mithilfe eines Hintergrundjobs ausgeführt.
Nach einem asynchron ausgeführten API-Aufruf gibt der Server den HTTP-Statuscode 202 zurück. Dies zeigt an, dass die Anfrage angenommen, aber noch nicht abgeschlossen wurde. Der Status des Hintergrundjobs kann abgefragt werden, um Erfolg oder Fehler zu ermitteln.
Die asynchrone Verarbeitung wird für verschiedene Arten von langlaufenden Operationen verwendet, darunter Datenspeicher- und vVol-Operationen. Weitere Informationen bietet die Kategorie „Jobmanager“ der REST API auf der Swagger-Seite.