Monitorear el estado de los dispositivos

Esta guía vigila una implementación de Rhombus desde tus herramientas de monitoreo o tu mesa de servicio: qué dispositivos están en línea, cuáles necesitan atención y cuánto tiempo de un periodo estuvo activa cada cámara. Usa tres piezas: listas de estado que consultas, webhooks de Diagnóstico que Rhombus envía y ventanas de disponibilidad para los informes.

Necesitas una clave de API con un rol de solo lectura que cubra las ubicaciones que monitoreas.

Consulta el estado de los dispositivos

Cada familia de dispositivos tiene una lista de estado que devuelve todos los dispositivos que la clave puede ver, con un estado de conexión y uno de salud. Para las cámaras, llama a getMinimalCameraStateList:

import os
import requests

URL = "https://api2.rhombussystems.com/api/camera/getMinimalCameraStateList"
HEADERS = {"x-auth-scheme": "api-token", "x-auth-apikey": os.environ["RHOMBUS_API_KEY"]}

cameras = requests.post(URL, headers=HEADERS, json={}).json()["cameraStates"]
for camera in cameras:
    if camera["connectionStatus"] != "GREEN" or camera.get("healthStatus") not in (None, "GREEN"):
        print(camera["name"], camera["uuid"], camera["connectionStatus"], camera.get("healthStatus"))

connectionStatus y healthStatus valen GREEN, YELLOW, ORANGE o RED, de mejor a peor. Cada cámara también informa firmwareVersion, locationUuid y sus datos de red, que ayudan a dirigir un ticket al sitio correcto.

Las demás familias tienen una lista equivalente:

Consultar cada cinco minutos cuesta unas pocas solicitudes por ejecución, muy por debajo de tu límite de tasa. Genera una alerta cuando un dispositivo siga en un estado distinto de verde durante dos ejecuciones seguidas, en lugar de hacerlo con una sola lectura.

Recibe webhooks de Diagnóstico

Para enterarte de los problemas en cuanto ocurren, agrega un webhook de organización con Tipo de activador Diagnóstico (Configuración → Integraciones y recursos para desarrolladores → Webhooks). Rhombus enviará entonces cada notificación de diagnóstico a tu URL, por ejemplo CAMERA_DISCONNECTED cuando una cámara se desconecta y CAMERA_CONNECTED cuando vuelve. Los sensores y los controladores de puerta usan nombres como DOOR_OFFLINE y DOOR_ONLINE.

{
  "version": "2",
  "diagnosticTrigger": "CAMERA_DISCONNECTED",
  "diagnosticUuid": "BBBBBBBBBBBBBBBBBBBBBB",
  "summary": "One-line summary of the event",
  "deviceUuid": "AAAAAAAAAAAAAAAAAAAAAA",
  "deviceType": "CAMERA",
  "location": "CCCCCCCCCCCCCCCCCCCCCC",
  "timestampMs": 1767230000000
}

Verifica el encabezado x-rhombus-signature-sha256 (Verifica una solicitud) y confirma la recepción rápidamente (Entrega). Los webhooks de Diagnóstico se entregan una sola vez y no se reintentan, así que mantén la consulta anterior como respaldo.

Abre tickets en tu mesa de servicio

Rhombus tiene integraciones nativas con ServiceNow y PagerDuty, que se configuran en la consola o con las operaciones de Incident Management Integrations de la referencia de la API (en inglés). Úsalas cuando encajen en tu proceso. Para otra herramienta, convierte tú mismo los webhooks o los resultados de la consulta en tickets:

• Un ticket abierto por dispositivo, con deviceUuid como clave, para que un dispositivo intermitente actualice su ticket en lugar de abrir otros nuevos.
• Cierre automático cuando el dispositivo vuelva a GREEN en la siguiente consulta.
• Incluye la ubicación y el nombre del dispositivo de la lista de estado, para que el ticket llegue al sitio correcto.

Informa la disponibilidad

Para informes de SLA y disponibilidad, getUptimeWindowsForOrg devuelve, para cada cámara, los periodos en que estuvo en línea entre startTimeMs y endTimeMs:

{
  "uptimeByDevice": [
    {
      "deviceUuid": "AAAAAAAAAAAAAAAAAAAAAA",
      "uptimeWindows": [
        { "startSeconds": 1767225600, "durationSeconds": 86100 }
      ]
    }
  ]
}

La disponibilidad de una cámara en el periodo es la suma de sus durationSeconds dividida entre la duración del periodo. Ten en cuenta que las ventanas están en segundos, mientras que la solicitud usa milisegundos.