Détails d'implémentation de l'API REST des ONTAP tools
Suggérer des modifications
PDF
Bien que REST définisse un ensemble commun de technologies et de bonnes pratiques, l'implémentation précise de chaque API peut varier selon les choix de conception. Vous devez bien comprendre comment l'API REST des ONTAP tools for VMware vSphere 10 est conçue avant de l'utiliser.
L'API REST comprend plusieurs catégories de ressources, telles que vCenters et les agrégats. Consultez la "Référence API" pour plus d'informations.
Comment accéder à l'API REST
Vous pouvez accéder à l'API REST des ONTAP tools for VMware vSphere 10 via l'adresse IP des ONTAP tools ainsi que le port. L'URL complète comporte plusieurs parties, notamment :
-
Adresse IP et port des outils ONTAP
-
version API
-
Catégorie de ressources
-
${post_edited_translations.segment}
Vous devez configurer l'adresse IP lors de la configuration initiale, tandis que le port reste fixe à 8443. La première partie de l'URL est identique pour chaque instance d'ONTAP tools for VMware vSphere 10 ; seules la catégorie de ressource et la ressource spécifique changent entre les points de terminaison.
|
Les adresses IP et les ports indiqués dans les exemples ci-dessous sont fournis à titre indicatif uniquement. Vous devez modifier ces valeurs pour votre environnement. |
https://10.61.25.34:8443/virtualization/api/v1/auth/login
Cette URL peut être utilisée pour demander un jeton d'accès à l'aide de la méthode POST.
https://10.61.25.34:8443/virtualization/api/v1/vcenters
Cette URL peut être utilisée pour demander une liste des instances de serveur vCenter définies à l'aide de la méthode GET.
Détails HTTP
Les ONTAP tools for VMware vSphere 10 REST API utilisent HTTP et les paramètres associés pour agir sur les instances et collections de ressources. Les détails de l’implémentation HTTP sont présentés ci-dessous.
Méthodes HTTP
Les méthodes ou verbes HTTP pris en charge par l'API REST sont présentés dans le tableau ci-dessous.
| Méthode | CRUD | Description |
|---|---|---|
GET |
Lire |
Récupère les propriétés d'un objet pour une instance de ressource ou une collection. Il s'agit d'une opération de liste lorsqu'elle est utilisée avec une collection. |
POST |
Créer |
Crée une nouvelle instance de ressource en fonction des paramètres d'entrée. |
PUT |
Mise à jour |
Met à jour l'intégralité d'une instance de ressource avec le corps de la requête JSON fourni. Les valeurs clés non modifiables par l'utilisateur sont conservées. |
CORRECTIF |
Mise à jour |
Demande qu’un ensemble de modifications sélectionnées dans la requête soit appliqué à l’instance de ressource. |
SUPPRIMER |
Supprimer |
Supprime une instance de ressource existante. |
En-têtes de requête et de réponse
Le tableau suivant récapitule les en-têtes HTTP les plus importants utilisés avec l'API REST.
| En-tête | Type | Notes d'utilisation |
|---|---|---|
Accepter |
Demande |
Il s'agit du type de contenu que l'application cliente peut accepter. Les valeurs valides incluent '*/*` ou |
x-auth |
Demande |
Contient un jeton d'accès identifiant l'utilisateur émettant la requête via l'application cliente. |
Type de contenu |
Réponse |
Renvoyé par le serveur en fonction de l' `Accept`en-tête de la requête. |
codes d'état HTTP
Les codes d'état HTTP utilisés par l'API REST sont décrits ci-dessous.
| Code | Signification | Description |
|---|---|---|
200 |
OK |
Indique la réussite des appels qui ne créent pas de nouvelle instance de ressource. |
201 |
Créé |
Un objet a été créé avec succès avec un identifiant unique pour l'instance de ressource. |
202 |
Accepté |
La demande a été acceptée et une tâche en arrière-plan a été créée pour exécuter la demande. |
204 |
Aucun contenu |
La requête a réussi, bien qu'aucun contenu n'ait été renvoyé. |
400 |
Mauvaise demande |
La saisie de la requête n'est pas reconnue ou est inappropriée. |
401 |
Non autorisé |
L'utilisateur n'est pas autorisé et doit s'authentifier. |
403 |
Interdit |
L'accès est refusé en raison d'une erreur d'autorisation. |
404 |
Introuvable |
La ressource mentionnée dans la requête n'existe pas. |
409 |
Conflit |
La tentative de création d'un objet a échoué car l'objet existe déjà. |
500 |
Erreur interne |
Une erreur interne générale s'est produite sur le serveur. |
Authentification
L'authentification d'un client auprès de l'API REST s'effectue à l'aide d'un jeton d'accès. Les caractéristiques pertinentes du jeton et du processus d'authentification sont les suivantes :
-
Le client doit demander un jeton en utilisant les identifiants d'administrateur ONTAP tools Manager (nom d'utilisateur et mot de passe).
-
Les jetons sont formatés en tant que JSON Web Token (JWT).
-
Chaque jeton expire après 60 minutes.
-
Les requêtes API provenant d'un client doivent inclure le jeton dans l' `x-auth`en-tête de la requête.
Reportez-vous à "Votre premier appel à l'API REST" pour un exemple de demande et d'utilisation d'un jeton d'accès.
Requêtes synchrones et asynchrones
La plupart des appels d'API REST s'exécutent rapidement et sont donc synchrones. Autrement dit, ils renvoient un code d'état (par exemple 200) après qu'une requête a été terminée. Les requêtes qui prennent plus de temps à s'exécuter fonctionnent de manière asynchrone à l'aide d'une tâche en arrière-plan.
Après l'envoi d'un appel API qui s'exécute de manière asynchrone, le serveur renvoie un code d'état HTTP 202. Cela indique que la requête a été acceptée mais n'est pas encore terminée. Vous pouvez interroger la tâche en arrière-plan pour déterminer son état, y compris le succès ou l'échec.
Le traitement asynchrone est utilisé pour plusieurs types d'opérations de longue durée, y compris les opérations sur les datastores et vVol. Pour plus d'informations, consultez la catégorie du gestionnaire de tâches de l'API REST sur la page Swagger.