Control API: registros, auditoría y uso
Utilice FoxIDs Control API para consultar registros de diagnóstico, eventos de auditoría y datos de uso, y para configurar los tipos de registros emitidos por un entorno. Estos recursos tienen diferentes finalidades y derechos de acceso:
- Los registros ayudan a los operadores a diagnosticar errores, advertencias, flujos de protocolo, eventos y métricas.
- Auditoría registra acciones administrativas y de seguridad, incluida la actividad de inicio de sesión y Control API solicitudes de creación, actualización y eliminación.
- Uso agrega actividad para análisis operativo y de facturación.
Antes de llamar a estas operaciones, configure Control API autenticación y derechos de acceso. Swagger sigue siendo la referencia exacta para todos los parámetros de consulta, valores de enumeración, configuraciones y esquemas de respuesta:
Alcance de la consulta y puntos finales
FoxIDs proporciona tres ámbitos de consulta.
| Alcance | Base de punto final | Registro de diagnóstico | Auditoría | Uso |
|---|---|---|---|---|
| Un entorno | /api/{tenant_name}/{track_name} |
!tracklog |
!tracklogaudit |
!tracklogusage |
| Tu tenant | /api/{tenant_name}/master |
!mytenantlog |
!mytenantlogaudit |
!mytenantlogusage |
| Administración de implementación | /api/master/master |
!tenantlog |
!tenantlogaudit |
!tenantlogusage |
Prefije la base con el host FoxIDs Control, por ejemplo https://control.foxids.com. Cambie el host para una implementación autohospedada. Envíe el token de acceso en el encabezado Authorization: Bearer {access_token}.
Las consultas de entorno utilizan el entorno de la ruta. Tenant consultas pueden seleccionar opcionalmente un entorno con trackName. Las consultas de administración de implementación pueden seleccionar un tenant y un entorno con tenantName y trackName. La consulta de diagnóstico de implementación también puede incluir solicitudes rechazadas antes de tenant y enrutamiento del entorno.
Utilice derechos de acceso track:log, track:audit o track:usage, opcionalmente restringidos a un entorno específico. La auditoría y el uso en toda la implementación requieren los derechos de acceso master correspondientes. Consulte las tablas completas de derechos de acceso.
Consultar registros de diagnóstico
Una solicitud de registro de diagnóstico especifica fromTime y toTime como tiempo Unix en segundos. Una sola solicitud puede abarcar como máximo 24 horas. Seleccione una o más categorías, como errores, advertencias, seguimientos, eventos y métricas, y utilice filter para filtrar texto libre.
Una respuesta contiene hasta 300 de las entradas coincidentes más recientes. Marque responseTruncated; cuando sea true, reduzca el rango de tiempo o filtre y realice la consulta nuevamente en lugar de asumir que el resultado está completo.
Application Insights no admite la consulta de seguimientos y eventos juntos mediante esta operación. Envíe solicitudes por separado cuando se requieran ambas categorías. Mantenga los intervalos de tiempo lo más estrechos posible para mejorar el rendimiento de las consultas y reducir la cantidad de datos confidenciales devueltos.
Los puntos finales de consulta requieren un repositorio de registros primario con capacidad de búsqueda. No pueden recuperar registros cuando la salida de registro principal de la implementación es la salida estándar (Stdout). En esa configuración, consulte el contenedor de la plataforma o el sistema de registro del host. FoxIDs admite consultas de control en los repositorios Application Insights y OpenSearch configurados.
Consultar eventos de auditoría
Una solicitud de auditoría especifica fromTime y toTime como tiempo Unix en segundos y puede abarcar como máximo siete días. toTime debe ser igual o posterior a fromTime. El filter opcional realiza una búsqueda general de texto libre en los campos de auditoría y los datos del evento.
Una respuesta contiene hasta 300 de los eventos de auditoría coincidentes más recientes. Marque responseTruncated y divida o limite la consulta cuando se requiera un resultado completo.
Los eventos de auditoría incluyen actividad de autenticación de cara al usuario y mutaciones administrativas. Las acciones Control API POST, PUT y DELETE se auditan automáticamente, mientras que las solicitudes GET de solo lectura no. Un evento de auditoría puede contener valores de correlación útiles como tenant, entorno, método de autenticación, aplicación, usuario, sesión, IP del cliente y agente de usuario cuando esos valores están disponibles para la acción.
La auditoría está diseñada para mostrar qué acción ocurrió y su contexto. No es una cola de eventos transaccionales y no debe utilizarse como único desencadenante de una sincronización crítica para el negocio. Los resultados de la búsqueda también dependen del repositorio de registros configurado y de la retención.
Uso de consultas
Las solicitudes de uso seleccionan un ámbito de tiempo, un desplazamiento UTC y un nivel de resumen. Los indicadores de inclusión determinan si la respuesta contiene tenants, entornos, métodos de autenticación, usuarios, inicios de sesión, solicitudes de token, uso adicional y actividad Control API.
Elija el alcance más estrecho y solo las dimensiones que necesite el consumidor. Esto mantiene las respuestas más pequeñas y evita exponer tenant o detalles del usuario innecesariamente. Utilice Swagger para los valores de resumen y alcance temporal actuales.
Configurar el registro del entorno
La configuración del registro del entorno utiliza:
| Operación | Punto final | Objetivo |
|---|---|---|
| Obtener configuración | GET /!tracklogsetting |
Lea los tipos de registros de diagnóstico habilitados para el entorno de ruta. |
| Guardar configuración | POST /!tracklogsetting |
Reemplace la configuración de registro del entorno. |
| Obtener transmisiones | GET /!tracklogstreamssettings |
Leer la configuración del flujo de registro externo. |
| Guardar transmisiones | POST /!tracklogstreamssettings |
Reemplace la configuración del flujo de registro externo. |
La configuración controla los seguimientos de información, los seguimientos de reclamaciones, los seguimientos de mensajes y las métricas. Los errores, advertencias, errores críticos y eventos permanecen disponibles de forma independiente, como se describe en Registro. POST reemplaza el recurso de configuración completo; obtenga el recurso actual, conserve las propiedades sin cambios y luego guarde la representación completa.
Una secuencia de registros reenvía categorías seleccionadas a un destino externo independientemente del repositorio de registros principal. Esto se puede utilizar para enviar un conjunto controlado de registros de entorno a un recurso Application Insights independiente.
Los seguimientos de reclamos y mensajes pueden contener datos personales, tokens y mensajes de protocolo completos. Habilítelos solo para una necesidad de diagnóstico definida, restrinja el acceso, establezca un período de retención adecuado y desactívelos nuevamente cuando se complete la investigación.
Orientación operativa
- Utilice marcas de tiempo UTC Unix en integraciones y aplique
timeOffsetsolo cuando la presentación del uso requiera un límite local. - Divida las investigaciones largas en solicitudes dentro del rango de tiempo máximo del punto final.
- Mantenga filtros de texto libre específicos y evite depender del texto mostrado como identificador permanente de la máquina.
- Proteja los datos de registro y auditoría devueltos como información operativamente confidencial.
- Utilice la auditoría para investigar y evidenciar acciones, no para reemplazar una notificación o sincronización garantizada API.
- Espere que los cambios en la configuración de registros y las transmisiones sean auditados porque son Control API mutaciones.
Respuestas de error comunes
400 Bad Requestcuando un intervalo de tiempo, selector, tenant, entorno o recurso de configuración no es válido.401 Unauthorizedcuando falta el token de acceso o no es válido.403 Forbiddencuando la persona que llama carece del derecho de registro, auditoría o acceso de uso requerido.404 Not Foundcuando el entorno o recurso de configuración seleccionado no existe.
Utilice el cuerpo de la respuesta para los detalles de validación y Swagger UI para las respuestas declaradas por cada operación.