API de Cloud Insights
- Requisitos para acceder a las API
- Documentación de API (Swagger)
- Tokens de acceso API
- Tipo de API
- Transversal de inventario
- Se amplía
- Datos de rendimiento
- Métricas de rendimiento de objetos
- Datos del historial de rendimiento
- Objetos con atributos de capacidad
- Uso de Buscar para buscar objetos
- Deshabilitar o revocar un token de API
- Rotar tokens de acceso a API caducados
La API de Cloud Insights permite a los clientes y proveedores independientes de software (ISV) de NetApp integrar Cloud Insights con otras aplicaciones, como CMDB u otros sistemas de emisión de boletos.
Tenga en cuenta que las API de Cloud Insights están disponibles en función de su edición actual:
Tipo de API | Básico | Estándar | Premium |
---|---|---|---|
Unidad de adquisición |
|||
Recopilación de datos |
|||
Alertas |
|||
Activos |
|||
Ingesta de datos |
|||
Registrar ingestión |
Además, su Cloud Insights "función de conjunto de funciones" Determinará a qué API puede acceder. Los roles de usuario e invitado tienen menos privilegios que el rol de administrador. Por ejemplo, si tiene la función de administrador en Monitor y Optimize, pero la función de usuario en Reporting, puede administrar todos los tipos de API excepto Data Warehouse.
Requisitos para acceder a las API
-
Se utiliza un modelo de token de acceso de API para conceder acceso.
-
La gestión de token de API la realizan los usuarios de Cloud Insights con la función de administrador.
Documentación de API (Swagger)
Para obtener la información más reciente sobre la API, inicie sesión en Cloud Insights y vaya a Admin > API access. Haga clic en el enlace Documentación de API.
La documentación de API es basada en Swagger, que proporciona una descripción breve e información de uso de la API, y permite probarlo en su entorno. Según la función de usuario y/o la edición Cloud Insights, los tipos de API disponibles para usted pueden variar.
Tokens de acceso API
Antes de utilizar la API de Cloud Insights, debe crear uno o más tokens de acceso de API. Los tokens de acceso se utilizan para los tipos de API especificados y pueden otorgar permisos de lectura y/o escritura. También puede establecer la caducidad de cada token de acceso. Todas las API de los tipos especificados son válidas para el token de acceso. Cada token es nulo de un nombre de usuario o contraseña.
Para crear un token de acceso:
-
Haga clic en Admin > API Access
-
Haga clic en +símbolo de acceso de API
-
Introduzca el nombre del token
-
Seleccione API Types
-
Especifique los permisos concedidos para este acceso a la API
-
Especifique caducidad de token
-
|
El token sólo estará disponible para copiar en el portapapeles y guardar durante el proceso de creación. Los tokens no se pueden recuperar una vez creados, por lo que se recomienda encarecidamente copiar el token y guardarlo en una ubicación segura. Se le pedirá que haga clic en el botón Copiar clave de acceso de API antes de cerrar la pantalla de creación de token. |
Puede desactivar, activar y revocar tokens. Se pueden activar los tokens desactivados.
Los tokens conceden acceso de uso general a las API desde la perspectiva del cliente; además, gestionan el acceso a las API en el ámbito de su propio inquilino. Los administradores del cliente pueden conceder y revocar estos tokens sin la intervención directa del personal de administración de Cloud Insights.
La aplicación recibe un token de acceso después de que un usuario autentica correctamente y autoriza el acceso, a continuación, pasa el token de acceso como credencial cuando llama a la API de destino. El token pasado informa a la API de que el portador del token ha sido autorizado para acceder a la API y realizar acciones específicas especificadas por el ámbito que se concedió durante la autorización.
El encabezado HTTP donde se pasa el token de acceso es X-CloudInsights-ApiKey:.
Por ejemplo, utilice lo siguiente para recuperar activos de almacenamientos:
curl https://<tenant_host_name>/rest/v1/assets/storages -H 'X-CloudInsights-ApiKey:<API_Access_Token>' Donde _<API_Access_Token>_ es el token que ha guardado durante la creación del acceso a la API.
Consulte las páginas de Swagger para ver ejemplos específicos de la API que desea utilizar.
Tipo de API
La API de Cloud Insights está basada en categorías y actualmente contiene los siguientes tipos:
-
El tipo DE ACTIVO contiene API de activo, consulta y búsqueda.
-
Activos: Enumera los objetos de nivel superior y recupera un objeto específico o una jerarquía de objetos.
-
Consulta: Recupere y gestione consultas Cloud Insights.
-
Importar: Importe anotaciones o aplicaciones y asígnelas a objetos
-
Búsqueda: Busque un objeto específico sin conocer el ID único del objeto o su nombre completo.
-
-
El tipo DE RECOPILACIÓN DE DATOS se utiliza para recuperar y administrar recopiladores de datos.
-
El tipo DE INGESTA DE DATOS se utiliza para recuperar y gestionar los datos de ingestión y las métricas personalizadas, como los agentes de Telegraf
-
LA INGESTA DE REGISTROS se utiliza para recuperar y gestionar los datos de registro
Es posible que haya disponibles más tipos y/o API a lo largo del tiempo. Puede encontrar la información de API más reciente en el "Documentación de API Swagger".
Tenga en cuenta que los tipos de API a los que tiene acceso un usuario también dependen de "Rol de usuario" Se incluyen en cada conjunto de funciones de Cloud Insights (Supervisión, seguridad de carga de trabajo, generación de informes).
Transversal de inventario
En esta sección se describe cómo recorrer una jerarquía de objetos Cloud Insights.
Objetos de nivel superior
Los objetos individuales se identifican en las solicitudes mediante una dirección URL única (llamada "auto" en JSON) y requieren conocimiento del tipo de objeto y del Id. Interno Para algunos de los objetos del nivel superior (hosts, almacenamientos, etc.), la API DE REST ofrece acceso a la recogida completa.
El formato general de una URL de API es:
https://<tenant>/rest/v1/<type>/<object> Por ejemplo, para recuperar todos los almacenamientos de un inquilino llamado _mysite.c01.cloudinsights.netapp.com_, la URL de la solicitud es:
https://mysite.c01.cloudinsights.netapp.com/rest/v1/assets/storages
Niños y objetos relacionados
Los objetos de nivel superior, como almacenamiento, se pueden utilizar para desplazarse a otros elementos secundarios y objetos relacionados. Por ejemplo, para recuperar todos los discos para un almacenamiento específico, concatene la dirección URL de “self” de almacenamiento con “/disks”, por ejemplo:
https://<tenant>/rest/v1/assets/storages/4537/disks
Se amplía
Muchos comandos de API admiten el parámetro Expand, que proporciona detalles adicionales sobre el objeto o las direcciones URL de los objetos relacionados.
El único parámetro de expansión común es expands. La respuesta contiene una lista de todas las expansi- do específicas disponibles para el objeto.
Por ejemplo, cuando solicite lo siguiente:
https://<tenant>/rest/v1/assets/storages/2782?expand=_expands La API devuelve todas las expande disponibles para el objeto de la siguiente manera:
Cada expansión contiene datos, una URL o ambos. El parámetro expand admite varios atributos anidados, por ejemplo:
https://<tenant>/rest/v1/assets/storages/2782?expand=performance,storageResources.storage La ampliación le permite incorporar una gran cantidad de datos relacionados en una única respuesta. NetApp recomienda no solicitar demasiada información a la vez; esto puede provocar una degradación del rendimiento.
Para desalentarlo, las solicitudes de cobranzas de nivel superior no se pueden expandir. Por ejemplo, no puede solicitar la expansión de los datos de todos los objetos de almacenamiento al mismo tiempo. Los clientes deben recuperar la lista de objetos y, a continuación, elegir objetos específicos para expandirse.
Datos de rendimiento
Los datos de rendimiento se recopilan en muchos dispositivos como muestras independientes. Cada hora (valor predeterminado), Cloud Insights agrega y resume muestras de rendimiento.
La API permite el acceso tanto a las muestras como a los datos resumidos. Para un objeto con datos de rendimiento, hay disponible un resumen de rendimiento como Expand=Performance. Las series de tiempo del historial de rendimiento están disponibles mediante el Expand=performance.history anidado.
Algunos ejemplos de objetos de datos de rendimiento son:
-
Rendimiento de almacenamiento
-
StoragePoolPerformance
-
Rendimiento del puerto
-
Rendimiento de disco
Una métrica de rendimiento tiene una descripción y un tipo y contiene una colección de resúmenes de rendimiento. Por ejemplo, latencia, tráfico y velocidad.
Un resumen de rendimiento contiene una descripción, unidad, hora de inicio de la muestra, hora de finalización de la muestra y una recopilación de valores resumidos (actual, mín., máx., promedio, etc.) calculados a partir de un único contador de rendimiento en un intervalo de tiempo (1 hora, 24 horas, 3 días, etc.).
El diccionario de datos de rendimiento resultante tiene las siguientes claves:
-
"Auto" es la URL única del objeto
-
“history” (historial) es la lista de pares de valores de marca de tiempo y de mapa de contadores
-
Cualquier otra clave de diccionario (“diskThroughput”, etc.) es el nombre de una métrica de rendimiento.
Cada tipo de objeto de datos de rendimiento tiene un conjunto único de métricas de rendimiento. Por ejemplo, el objeto de rendimiento de máquina virtual admite “diskThroughput” como métrica de rendimiento. Cada métrica de rendimiento admitida es de una cierta “performanceCategory” presentada en el diccionario de métricas. Cloud Insights admite varios tipos de métrica de rendimiento enumerados más adelante en este documento. Cada diccionario de métrica de rendimiento también tendrá el campo “descripción” que es una descripción legible por el usuario de esta métrica de rendimiento y un conjunto de entradas de contador de resumen de rendimiento.
El contador de resumen de rendimiento es el resumen de contadores de rendimiento. Presenta valores agregados típicos como min, max y avg para un contador y también el último valor observado, intervalo de tiempo para datos resumidos, tipo de unidad para contador y umbrales para datos. Sólo los umbrales son opcionales; el resto de atributos son obligatorios.
Hay resúmenes de rendimiento disponibles para estos tipos de contadores:
-
Lectura – Resumen para operaciones de lectura
-
Write: Resumen para operaciones de escritura
-
Total: Resumen de todas las operaciones. Puede ser mayor que la simple suma de lectura y escritura; puede incluir otras operaciones.
-
Total Max: Resumen para todas las operaciones. Este es el valor total máximo del intervalo de tiempo especificado.
Métricas de rendimiento de objetos
La API puede mostrar métricas detalladas de los objetos de su entorno, por ejemplo:
-
Métricas de rendimiento de almacenamiento como IOPS (número de solicitudes de entrada/salida por segundo), latencia o rendimiento.
-
Cambie las métricas de rendimiento, como la utilización del tráfico, los datos de BB Credit Zero o los errores de puerto.
Consulte "Documentación de API Swagger" para obtener información sobre las métricas de cada tipo de objeto.
Datos del historial de rendimiento
Los datos del historial se presentan en los datos de rendimiento como una lista de parejas de mapas de Marca de tiempo y de contadores.
El nombre de los contadores de historial se basa en el nombre del objeto de métrica de rendimiento. Por ejemplo, el objeto de rendimiento de máquina virtual admite “diskThroughput”, de modo que el mapa de historia contendrá claves denominadas “diskThroughput.read”, “diskThroughput.write” y “diskThroughput.total”.
|
La Marca de hora está en formato de hora UNIX. |
Lo siguiente es un ejemplo de JSON de datos de rendimiento para un disco:
Objetos con atributos de capacidad
Los objetos con atributos de capacidad utilizan tipos de datos básicos y la capacidadItem para la representación.
CapacidadItem
CapacityItem es una única unidad lógica de capacidad. Tiene “valor” y “umbral alto” en unidades definidas por su objeto principal. También admite un mapa de desglose opcional que explica cómo se construye el valor de capacidad. Por ejemplo, la capacidad total de un pool de almacenamiento de 100 TB sería una capacidadItem con un valor de 100. El desglose puede mostrar 60 TB asignados para “datos” y 40 TB para “instantáneas”.
- Nota
-
El “umbral alto” representa umbrales definidos por el sistema para las métricas correspondientes, que un cliente puede utilizar para generar alertas o señales visuales sobre valores que están fuera de rangos configurados aceptables.
A continuación, se muestra la capacidad de los pools de almacenamiento con varios contadores de capacidad:
Uso de Buscar para buscar objetos
La API de búsqueda es un punto de entrada sencillo al sistema. El único parámetro de entrada a la API es una cadena de forma libre y el JSON resultante contiene una lista clasificada de resultados. Los tipos son los diferentes tipos de activos del inventario, como los almacenamientos, hosts, almacenes de datos, etc. Cada tipo contiene una lista de objetos del tipo que coinciden con los criterios de búsqueda.
Cloud Insights es una solución ampliable (abierta) que permite integraciones con sistemas de orquestación, gestión comercial, control de cambios y emisión de tickets de terceros, e integraciones personalizadas de CMDB.
La API RESTful de Cloud Insight es un punto principal de integración que permite un movimiento de datos sencillo y efectivo. Además, permite a los usuarios obtener un acceso sencillo a sus datos.
Deshabilitar o revocar un token de API
Para desactivar temporalmente un token de API, en la página de lista de tokens de API, haga clic en el menú "tres puntos" de la API y seleccione Disable. Puede volver a activar el token en cualquier momento utilizando el mismo menú y seleccionando Enable.
Para eliminar permanentemente un token de API, en el menú, seleccione "revocar". No puede volver a habilitar un token revocado; debe crear un nuevo token.
Rotar tokens de acceso a API caducados
Los tokens de acceso a la API tienen una fecha de caducidad. Cuando caduca un token de acceso a la API, los usuarios deben generar un nuevo token (de tipo Data ingestión con permisos de lectura/escritura) y reconfigurar Telegraf para utilizar el token recién generado en lugar del token caducado. Los siguientes pasos detallan cómo hacer esto.
Kubernetes
Tenga en cuenta que estos comandos utilizan el espacio de nombres predeterminado "netapp-Monitoring". Si ha definido su propio espacio de nombres, sustituya este espacio de nombres en estos y todos los comandos y archivos subsiguientes.
Nota: Si tiene instalado el último operador de supervisión de Kubernetes de NetApp y utiliza un token de acceso a la API que sea renovable, los tokens que caducan se reemplazarán automáticamente por tokens de acceso a la API nuevos o actualizados. No es necesario realizar los pasos manuales que se indican a continuación.
-
Edite el operador de NetApp Kubernetes Monitoring.
kubectl -n netapp-monitoring edit agent agent-monitoring-netapp * Modifique el valor _spec.output-sink.api-key_, reemplazando el token de API antiguo con el nuevo token de API.
spec: … output-sink: - api-key:<NEW_API_TOKEN>
RHEL/CentOS y Debian/Ubuntu
-
Edite los archivos de configuración de Telegraf y sustituya todas las instancias del token de API antiguo por el nuevo token de API.
sudo sed -i.bkup ‘s/<OLD_API_TOKEN>/<NEW_API_TOKEN>/g’ /etc/telegraf/telegraf.d/*.conf * Reinicie Telegraf.
sudo systemctl restart telegraf
Windows
-
Para cada archivo de configuración de Telegraf de C:\Archivos de programa\telegraf\telegraf.d, reemplace todas las instancias del token de API antiguo con el nuevo token de API.
cp <plugin>.conf <plugin>.conf.bkup (Get-Content <plugin>.conf).Replace(‘<OLD_API_TOKEN>’, ‘<NEW_API_TOKEN>’) | Set-Content <plugin>.conf
-
Reinicie Telegraf.
Stop-Service telegraf Start-Service telegraf