Detalles de implementación de la API de REST de ONTAP tools
Sugerir cambios
PDF
Aunque REST establece un conjunto común de tecnologías y buenas prácticas, la implementación concreta de cada API puede variar en función de las decisiones de diseño. Deberías familiarizarte con cómo está diseñada la API de REST de ONTAP tools for VMware vSphere 10 antes de usarla.
La API de REST incluye varias categorías de recursos, como vCenters y Aggregates. Consulta la "Referencia sobre API" para obtener más información.
Cómo acceder a la API de REST
Puedes acceder a las ONTAP tools for VMware vSphere 10 API de REST a través de la dirección IP de las ONTAP tools junto con el puerto. La URL completa consta de varias partes, entre las que se incluyen:
-
Dirección IP y puerto de ONTAP tools
-
Versión de API
-
Categoría de recursos
-
${post_edited_translations.segment}
Debes configurar la dirección IP durante la configuración inicial, mientras que el puerto se mantiene fijo en 8443. La primera parte de la URL es la misma para cada instancia de ONTAP tools for VMware vSphere 10; solo la categoría de recurso y el recurso específico cambian entre los distintos endpoints.
|
Los valores de la dirección IP y del puerto que aparecen en los ejemplos siguientes son meramente ilustrativos. Debes modificar estos valores para adaptarlos a tu entorno. |
https://10.61.25.34:8443/virtualization/api/v1/auth/login
Esta URL se puede utilizar para solicitar un token de acceso mediante el método POST.
https://10.61.25.34:8443/virtualization/api/v1/vcenters
Esta URL se puede usar para solicitar una lista de las instancias definidas del servidor vCenter usando el método GET.
Detalles de HTTP
La API de REST de ONTAP tools for VMware vSphere 10 utiliza HTTP y los parámetros correspondientes para actuar sobre las instancias y colecciones de recursos. A continuación se detallan los aspectos de la implementación de HTTP.
Métodos HTTP
En la tabla siguiente se muestran los métodos o verbos HTTP compatibles con la API de REST.
| Método | CRUD | Descripción |
|---|---|---|
GET |
Leer |
Recupera las propiedades de un objeto para una instancia de recurso o una colección. Se considera una operación de lista cuando se utiliza con una colección. |
POST |
Crear |
Crea una nueva instancia de recurso basándose en los parámetros de entrada. |
${post_edited_translations.segment} |
Actualización |
Actualiza toda una instancia de recurso con el cuerpo de la solicitud JSON proporcionado. Se conservan los valores de las claves que no se pueden modificar por el usuario. |
PATCH |
Actualización |
Solicita que se apliquen a la instancia del recurso un conjunto de cambios seleccionados en la solicitud. |
ELIMINAR |
Borrar |
Elimina una instancia de recurso existente. |
Encabezados de solicitud y respuesta
La siguiente tabla resume los encabezados HTTP más importantes que se utilizan con la API de REST.
| Encabezado | Tipo | Notas de uso |
|---|---|---|
Aceptar |
Solicitud |
Este es el tipo de contenido que puede aceptar la aplicación cliente. Entre los valores válidos se incluyen '/' o |
x-auth |
Solicitud |
Contiene un token de acceso que identifica al usuario que realiza la solicitud a través de la aplicación cliente. |
Tipo de contenido |
Respuesta |
Lo devuelve el servidor según el encabezado de solicitud |
Códigos de estado HTTP
A continuación se describen los códigos de estado HTTP que utiliza la API de REST.
| Código | Significado | Descripción |
|---|---|---|
200 |
OK |
Indica éxito para las llamadas que no crean una nueva instancia de recurso. |
201 |
Creado |
Se ha creado correctamente un objeto con un identificador único para la instancia del recurso. |
202 |
Aceptado |
La solicitud ha sido aceptada y se ha creado una tarea en segundo plano para ejecutarla. |
204 |
Sin contenido |
La solicitud se realizó correctamente, aunque no se devolvió ningún contenido. |
400 |
Solicitud incorrecta |
La solicitud introducida no se reconoce o es inapropiada. |
401 |
No autorizado |
El usuario no está autorizado y debe autenticarse. |
403 |
Prohibido |
El acceso está denegado debido a un error de autorización. |
404 |
No encontrado |
El recurso al que se hace referencia en la solicitud no existe. |
409 |
Conflicto |
Se ha producido un intento de crear un objeto, pero el objeto ya existe. |
500 |
Error interno |
Se ha producido un error interno general en el servidor. |
Autenticación
La autenticación de un cliente en la API de REST se realiza usando un token de acceso. Las características relevantes del token y del proceso de autenticación incluyen:
-
El cliente debe solicitar un token utilizando las credenciales de administrador de ONTAP tools Manager (nombre de usuario y contraseña).
-
Los tokens tienen el formato de un JSON Web Token (JWT).
-
Cada token caduca al cabo de 60 minutos.
-
Las solicitudes a la API desde un cliente deben incluir el token en el encabezado de la solicitud
x-auth.
Consulta "Tu primera llamada a la API de REST" para ver un ejemplo de cómo solicitar y utilizar un token de acceso.
Solicitudes síncronas y asíncronas
La mayoría de las llamadas a la API de REST se completan rápidamente y, por lo tanto, se ejecutan de forma sincrónica. Es decir, devuelven un código de estado (como 200) después de que se haya completado la solicitud. Las solicitudes que tardan más en completarse se ejecutan de forma asincrónica usando una tarea en segundo plano.
Tras realizar una llamada a la API que se ejecuta de forma asíncrona, el servidor devuelve un código de estado HTTP 202. Esto indica que la solicitud ha sido aceptada pero aún no se ha completado. Puedes consultar el trabajo en segundo plano para determinar su estado, incluyendo si se ha completado con éxito o ha fallado.
El procesamiento asíncrono se utiliza para varios tipos de operaciones de larga duración, incluidas las operaciones con el almacén de datos y las de vVol. Consulta la categoría job manager de la API de REST en la página de Swagger para más información.