Documentation
Descubre el modo de configuración cero
No encontrado

    La API de ServicePilot

    El REST API ServicePilot le permite interactuar con la interfaz de ServicePilot sin necesidad de conocimientos técnicos especiales. El REST API ServicePilot le permite:

    • Añadir recursos/vistas/elementos gráficos
    • Enviar datos
    • Realización de consultas SQL
    • Eliminar recursos

    Las aplicaciones y agentes externos pueden interactuar con los datos de ServicePilot a través de la API REST.

    API de aprovisionamiento

    La API de aprovisionamiento de ServicePilot le permite añadir rápidamente vistas, recursos y elementos gráficos a la monitorización de ServicePilot, de forma masiva según sea necesario.

    La API de aprovisionamiento de ServicePilot puede añadir uno o más recursos basados en el mismo package por solicitud, ya que cada solicitud consiste en una URL que especifica el tipo de package y un cuerpo "POST" con los recursos asociados a incluir.

    Para añadir recursos con la API REST, se necesita una solicitud web con una clave de API que tiene los derechos Escribir.

    Ejemplo: aprovisionar recursos mediante una petición cURL

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Prepare un archivo CSV llamado "data-prov.csv" que contenga las definiciones de los recursos a añadir.

      name,ip_address_fqdn
Ping-1,10.0.0.1
Ping-2,10.0.0.2
Ping-3,10.0.0.3

      Nota: sólo deben especificarse los campos necesarios para cada recurso. Consulte la página AJUSTES > Provisioning > Packages > Preguntas de la interfaz web de ServicePilot de cada package para conocer los campos requeridos.

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-000000000000

curl -X POST "https://data.servicepilot.com/api/provisioning/network-ping" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-prov.csv

    Ejemplo: añadir una jerarquía de vistas mediante una petición PowerShell

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Prepare un archivo CSV llamado "view-prov.csv" que contenga las definiciones de las vistas a añadir.

      name,view,autoarrange
Sites,MAIN,none
Site-1,Sites,linear
Site-2,Sites,linear

      Nota: sólo deben especificarse los campos name y view para cada vista.

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI PowerShell

      # Uncomment line below if HTTPS with TLS>=1.2 only
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]'Tls12'

# Select an API key with write access
$APIKEY="10000000-0000-0000-0000-000000000000"

Invoke-WebRequest -UseBasicParsing -Uri "https://data.servicepilot.com/api/provisioning/view" -Method "POST" -Headers @{ 'x-api-key'=$APIKEY } -ContentType "text/csv" -InFile view-prov.csv

    Definiciones de la API de aprovisionamiento de ServicePilot

    Consulte la página AJUSTES > Provisioning > Packages > API de la interfaz web de ServicePilot para ver todas las definiciones de packages, incluidos todos los campos opcionales.
    1. Utilizando una cuenta con privilegios de administradores, acceda a ServicePilot
    2. Abrir AJUSTES > Provisioning
    3. Acceder al elemento Packages
    4. Ir a API
    5. Siga los pasos del apartado API de aprovisionamiento

    APIs de envío de datos

    Existen una serie de API que se pueden utilizar para insertar datos en ServicePilot:

    1. API de envío de datos de ServicePilot - Inserta datos en los recursos supervisados de forma masiva.
    2. API antigua de envío de datos de ServicePilot - Inserta datos en un objeto cada vez.
    3. Añadir un recurso log-syslog-receptor - Capturar datos Syslog en la colección syslog de ServicePilot. Se pueden añadir filtros de captura y un script a ServicePilot para limitar los Syslogs recibidos.
    4. Añadir un recurso log-trap-receiver - Capturar Traps SNMP en la colección de traps de ServicePilot. Se pueden añadir filtros de captura y un script a ServicePilot para limitar y categorizar los Traps recibidos.

    Es preferible utilizar la nueva API de envío de datos a menos que sólo se envíen datos a un objeto de ServicePilot.

    API de envío de datos

    ServicePilot Enviar datos API puede insertar datos de indicadores, registros y vistas en uno o más recursos, independientemente del tipo de package, en la misma solicitud, ya que cada solicitud consta de una URL que especifica la API y un POST body con los recursos asociados y los datos a inyectar.

    Ejemplo: Insertar los datos de los indicadores en los recursos

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Prepare un archivo CSV llamado "data-send.csv" que contenga los recursos y los datos de los indicadores asociados que se van a insertar.

      type,object,i1
data,Ping-1,333
data,Ping-2,555
data,Ping-3,777

      Nota: sólo es necesario especificar un mínimo de tipo, objeto, i1, donde i1 es el número de indicador monitor. Consulte la página AJUSTES > Provisioning > Packages > Indicadores en la interfaz web de ServicePilot para cada package para ver la lista de indicadores.

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-WRITE0000001

curl -X POST "https://data.servicepilot.com/api/send" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-send.csv

    Para ver los datos enviados por la API y almacenados en ServicePilot, conéctese a la interfaz web de ServicePilot. Abra MONITOR > Vista > Nombre del recurso y vea los valores que aparecen en la columna "último".

    Ejemplo: Insertar datos de logs en los recursos

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Prepare un archivo CSV llamado "data-send.csv" que contenga los recursos y los datos de logs asociados que se van a insertar.

      type,resname,object,log
log,myresource,myobject1,objectlog message1 col1;objectlog message1 col2
log,myresource,myobject1,objectlog message2 col1;objectlog message2 col2
log,myresource,myobject2,objectlog message1

      Nota: Sólo es necesario especificar un mínimo de tipo, objeto, registro. Consulte la página AJUSTES > Provisioning > Packages > Indicadores de la interfaz web de ServicePilot de cada package para ver la lista de User Log columns definition por clase. También se especifica el separador de columnas de registro.

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-WRITE0000001

curl -X POST "https://data.servicepilot.com/api/send" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-send.csv

    Para ver los datos enviados por la API y almacenados en ServicePilot, conéctese a la interfaz web de ServicePilot. Abra HERRAMIENTAS > Explorador de datos > objectlog > class - default y seleccione Display documents para ver los valores recibidos.

    Ejemplo: Crear una subvista dentro de una vista de recursos y enviar los datos del indicador y los datos de registro a un nuevo objeto

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Prepare un archivo CSV llamado data-send.csv que contenga los recursos y los datos asociados que se van a insertar.

      type,resname,object,class,view,parentview,ip,host,object_1,object_2,object_3,object_4,object_5,log,i1,i2
createview,myresource,,view_class,view1,myresource
data,myresource,myobject1,object_class,view1,,1.2.3.4,hostname,object constant1,,,,,,333.33,string
log,myresource,myobject1,,,,,,,,,,,objectlog message

      Nota: Si una vista no existe, puede crearse dentro de un recurso existente especificando el nombre del recurso, la clase de vista, el nombre de la vista y el nombre de la vista padre. Si un objeto no existe, puede crearse dentro de un recurso existente especificando el nombre del recurso, el nombre del objeto, la clase del objeto y el nombre de la vista. El número de indicadores del objeto monitor y el formato del registro del objeto dependen de la clase del objeto al que se envían los datos. Consulte la página AJUSTES > Configuración > Avanzado > Packages > Indicadores de la interfaz web de ServicePilot de cada package para ver la lista de indicadores.

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI

      REM Select an API key with WRITE access
set APIKEY=10000000-0000-0000-0000-WRITE0000001

curl -X POST "https://data.servicepilot.com/api/send" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-send.csv

    Definiciones de la API Send Data de ServicePilot

    Consulte la página Configuración > Avanzado > Packages > API de la interfaz web de ServicePilot para ver todas las definiciones de packages, incluidos todos los campos opcionales.
    1. Utilizando una cuenta con privilegios de administradores, acceda a ServicePilot
    2. Abrir AJUSTES > Provisioning
    3. Acceder al elemento Packages
    4. Ir a API
    5. Siga los pasos del apartado API para el envío de datos

    Antigua API de envío de datos

    La Antigua API de envío de datos de ServicePilot puede insertar datos de indicadores en un objeto, añadir un registro de objetos o crear una vista. Esta API debe utilizarse con moderación cuando sólo se van a enviar datos a un objeto, ya que no está optimizada para la importación masiva de datos.

    Ejemplo: Insertar datos del indicador en un objeto

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Envíe datos a ServicePilot mediante una solicitud de API GET. Tenga en cuenta que los parámetros de consulta de la URL deben estar codificados en la URL (+ o %20 para espacio, %2B para +, etc)

      curl https://data.servicepilot.com/d?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&v=view1&c=class&o=compdate&i1=2024-05-22+13:57:00%2B01:00
      Clave del parámetro de consulta Valor del parámetro de consulta Notas
      apikey Llave API ServicePilot de capacidad de escritura Requerido
      resname Nombre de recurso Requerido
      o Nombre de objeto Requerido
      c Nombre de clase del objeto Requerido si el objeto aún no existe
      v Nombre de la vista del objeto Requerido si el objeto aún no existe
      p Nombre de la vista padre del objeto Sólo se requiere si el objeto no existe y la vista del objeto no existe pero el padre de la vista del objeto debe existir. Se creará una vista intermedia genérica.
      ip Dirección IP de los datos de origen del objeto Especificar para una mejor categorización de los datos
      h Nombre de host de los datos de origen del objeto Especifique para una mejor categorización de los datos una licencia de host
      o1 ... o5 Valor de la constante del objeto de 1 a 5 Opcional
      i1 ... i# Datos indicadores del objeto Datos numéricos o de cadena para los indicadores del monitor del objeto dependiendo de la clase de objeto
      n yes En lugar de los datos del indicador, establezca este parámetro en yes para indicar un estado de no respuesta para el objeto

      Nota: Sólo es necesario especificar un mínimo de objeto e i1, donde i1 es el número de indicador monitor, si el objeto ya existe. Consulte la página AJUSTES > Provisioning > Packages > Indicadores en la interfaz web de ServicePilot para cada package para ver la lista de indicadores.

    Ejemplo: Insertar datos de registro en un objeto

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Envíe datos a ServicePilot mediante una solicitud de API GET. Tenga en cuenta que los parámetros de consulta de la URL deben estar codificados en la URL (+ o %20 para espacio, %2B para +, etc)

      curl https://data.servicepilot.com/l?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&v=view1&c=class&o=compdate&l=log+text%09log+text2
      Clave del parámetro de consulta Valor del parámetro de consulta Notas
      apikey Llave API de capacidad de escritura de ServicePilot Requerido
      resname Nombre de recurso Requerido
      o Nombre de objeto Requerido
      c Nombre de clase del objeto Requerido si el objeto aún no existe
      v Nombre de la vista del objeto Requerido si el objeto aún no existe
      p Nombre de la vista padre del objeto Sólo se requiere si el objeto no existe y la vista del objeto no existe pero el padre de la vista del objeto debe existir. Se creará una vista intermedia genérica.
      ip Dirección IP de los datos de origen del objeto Especificar para una mejor categorización de los datos
      h Nombre de host de los datos de origen del objeto Especifique para una mejor categorización de los datos una licencia de host
      o1 ... o5 Valor de la constante del objeto de 1 a 5 Opcional
      l Datos de registro Los datos de registro del objeto formateados

      Nota: Sólo es necesario especificar un mínimo de object y l si el objeto ya existe. El formato log del objeto depende de la clase de objeto.

    Ejemplo: Crear una vista

    1. Obtenga una clave API que tiene los derechos Escribir siguiendo las instrucciones en Claves de autenticación de la API

    2. Cree una vista utilizando una solicitud de API GET. Tenga en cuenta que los parámetros de consulta de la URL deben estar codificados en la URL (+ o %20 para espacio, %2B para +, etc)

      curl https://data.servicepilot.com/cv?apikey=10000000-0000-0000-0000-000000000000&resname=compdate&c=class&v=view1&p=resname&ar=linear
      Clave del parámetro de consulta Valor del parámetro de consulta Notas
      apikey Llave API de capacidad de escritura de ServicePilot Requerido
      resname Nombre de recurso Requerido
      c Nombre de clase de vista Requerido
      v Nombre de la vista Requerido
      p Nombre de la vista padre Requerido
      posx Posición X de la vista padre desde arriba Valor totalmente divisible por 10. Opcional si la vista padre está auto-organizada.
      posy Posición Y de la vista padre desde la izquierda Valor totalmente divisible por 10. Opcional si la vista padre está auto-organizada.
      width Tamaño del icono de la vista padre Opcional. 30 por defecto.
      height Tamaño del icono en la vista padre Opcional. 30 por defecto.
      bg Ver nombre de imagen de fondo Opcional
      ar linear Ajuste este parámetro a Lineal para organizar los iconos de forma lineal dentro de la vista. No hay disposición por defecto.

    API de consulta SQL

    La API de Consulta SQL de ServicePilot permite consultar y extraer datos directamente de la base de datos de ServicePilot. Las consultas SQL simplificadas pueden optimizarse con cláusulas Lucene y el formato de salida puede establecerse como CSV o JSON en la solicitud de la API.

    La petición SQL Select consulta una colección de la base de datos en función de la información requerida. Cada colección almacena un tipo específico de datos. Las colecciones pueden contener datos actuales/en tiempo real o registros históricos. Cuando se consulta una colección con registros históricos, se debe especificar un intervalo de tiempo o un número de registros más recientes. Por defecto, sólo se devuelven las 10 primeras filas de resultados.

    Collection Description Historical
    events Alarmas de objetos y recursos, acuses de recibo y gestión de eventos, cambios de configuración e inicios de sesión de usuarios X
    objectstatus Información de última hora sobre las vistas, los objetos y los recursos (estado, reconocimientos, gestiones, ...)
    objectdata Estadísticas de los indicadores de objetos y recursos X
    objectml Machine Learning de indicadores de objetos y recursos: anomalías, tendencia y predicción X
    objectlog Mensajes de registro personalizados del objeto X
    objectrca Registros de Root Cause Analysis
    objectsl Estadísticas de nivel de servicio para vistas y recursos X
    apptrace Solicitudes de APM con información del cliente y del servidor (estado HTTP, errores, tiempos de respuesta, ...) X
    nettrace Conversaciones de Nettrace con estadísticas del cliente y del servidor X
    inventory Inventario de servidores y endpoints
    syslog Registros Syslog X
    trap Registros SNMP trap X
    voip Registros CDR VoIP X

    Consulta de la base de datos de ServicePilot mediante solicitudes SQL

    1. Obtenga una clave API que tiene los derechos Lectura siguiendo las instrucciones en Claves de autenticación de la API|
    2. Construya su consulta SQL especificando los campos y la colección necesarios e inserte la consulta en la URL de solicitud de la API junto con una clave de API que tiene los derechos Lectura.

    Ejemplo: Obtener una lista de objetos PING no disponibles supervisados por ServicePilot

    SQL Query:

    SELECT object,status FROM objectstatus WHERE status="-" AND class="ping" ORDER BY object ASC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT object,status FROM objectstatus WHERE status="-" AND class="ping" ORDER BY object ASC&apikey=10000000-0000-0000-READ-000000000002

    Ejemplo: Obtener una lista con formato JSON de las últimas 100 alarmas críticas en los recursos

    SQL Query:

    SELECT timestamp,resource,view,status,info FROM events WHERE source="resource" AND status="3" ORDER BY timestamp DESC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT timestamp,resource,view,status,info FROM events WHERE source="resource" AND status="3" ORDER BY timestamp DESC&rows=100&wt=JSON&apikey=10000000-0000-0000-READ-000000000002

    Ejemplo: Obtener la media de uso de memoria de los servidores durante los últimos 30 minutos

    SQL Query:

    SELECT object,MEAN(integer4) FROM objectdata WHERE class="server system" GROUP BY object ORDER BY timestamp DESC

    API Request URL:

    https://data.servicepilot.com/api/sql?q=SELECT object,MEAN(integer4) FROM objectdata WHERE class="server system" GROUP BY object ORDER BY timestamp DESC&rows=30&apikey=10000000-0000-0000-READ-000000000002

    Definiciones de la API de solicitud de SQL de ServicePilot

    ServicePilot también ofrece un asistente para ayudarle a crear consultas SQL personalizadas según sus necesidades. Visite la página Consulta en la interfaz web de ServicePilot para empezar:
    1. Acceda a la interfaz web de ServicePilot
    2. Abrir HERRAMIENTAS > Explorador de datos
    3. Ir a SQL
    4. Cree su consulta SQL

    Consulte la página AJUSTES > Ajustes > API de la interfaz web de ServicePilot para obtener información adicional y la sintaxis de la API de solicitudes SQL.
    1. Utilizando una cuenta con privilegios de administradores, acceda a ServicePilot
    2. Abrir AJUSTES > Ajustes
    3. Acceder al elemento API

    API de eliminación de recursos

    La API de eliminación de recursos de ServicePilot permite eliminar rápidamente las vistas, los recursos y los elementos gráficos de la monitorización de ServicePilot, de forma masiva según sea necesario.

    La API de eliminación de recursos de ServicePilot puede eliminar uno o más recursos basados en el mismo package por solicitud, ya que cada solicitud consiste en una URL que especifica el tipo de package y un cuerpo DELETE con los recursos asociados que se deben eliminar.

    Para eliminar recursos con la API REST, se utiliza una solicitud web con una clave de API capaz de DELETE.

    Ejemplo: eliminar recursos mediante una petición cURL

    1. Obtenga una clave API capaz de eliminar siguiendo las instrucciones en Claves de autenticación de la API|

    2. Prepare un archivo CSV llamado "data-delete.csv" que contenga las definiciones de los recursos a eliminar.

      name,view
*,View_Test
Ping-3,

    3. Edite los siguientes comandos según sea necesario y ejecútelos en una CLI

      REM Select an API key with DELETE access
set APIKEY=10000000-0000-0000-0000-DELETE000001

curl -X DELETE "https://data.servicepilot.com/api/provisioning/network-ping" -H "Content-Type: text/csv" -H "x-api-key: %APIKEY%" --data-binary @data-delete.csv

    Definiciones de la API de eliminación de recursos de ServicePilot

    Consulte la página AJUSTES > Provisioning > Packages > API de la interfaz web de ServicePilot para obtener información adicional.
    1. Utilizando una cuenta con privilegios de administradores, acceda a ServicePilot
    2. Abrir AJUSTES > Provisioning
    3. Acceder al elemento Packages
    4. Ir a API
    5. Siga los pasos del apartado API de eliminación de recursos

    Claves de autenticación de la API

    Una clave API es una clave secreta precompartida asociada a un cliente de ServicePilot y utilizada por los agentes de ServicePilot y los usuarios de la API para autorizar el acceso. Las diferentes solicitudes de la API requerirán diferentes niveles de autorización de la clave de la API.

    Solicitudes de API Autorización mínima de la clave API
    Añadir recursos Escritura
    Enviar datos Escritura
    Peticiones SQL Lectura
    Eliminar recursos Eliminación

    ¿Cómo puedo obtener una clave API de ServicePilot?

    La página "Claves de la API" le permite gestionar las claves de la API para los Agentes ServicePilot y la API REST. Se sugiere que utilice una llave API dedicada para la interfaz REST con privilegios de Lectura, Lectura y escritura o Lectura, escritura y eliminación, dependiendo del acceso requerido. Si esta clave está comprometida, puede ser eliminada sin afectar a la recopilación de datos del Agente ServicePilot.
    1. Utilizando una cuenta con privilegios de administradores, acceda a ServicePilot
    2. Abrir AJUSTES > Configuración
    3. Acceder al elemento Claves de API
    4. Cree y anote una Clave API con la autorización requerida