Descripción general de WebSocket - Documentación para desarrolladores de Rhombus

Nota

Esta página se tradujo automáticamente. Si encuentras errores o tienes sugerencias, escríbenos.

La plataforma Rhombus expone un endpoint WebSocket que transmite eventos en tiempo real a tu aplicación. Esto te permite recibir notificaciones instantáneas sobre eventos de seguridad, alertas de políticas, cambios en dispositivos y otra actividad organizacional sin hacer polling a la API REST. Para las integraciones, la conexión es de solo recepción: te suscribes a tópicos y usas la API REST para actuar.

Cómo funciona

Las conexiones WebSocket de Rhombus utilizan el protocolo de mensajería STOMP 1.2 (Streaming Text Oriented Messaging Protocol) sobre una conexión WebSocket estándar. STOMP proporciona un protocolo simple basado en frames para suscribirse a tópicos y recibir mensajes estructurados.

Your Application
      │
      ▼
  WebSocket (WSS)
      │
      ▼
  STOMP 1.2 Protocol
      │
      ▼
  Rhombus Event Bus ──► /topic/change/{orgUuid}

Endpoint de conexión

Conéctate al endpoint que corresponda a la región de tu organización:

Entorno	Endpoint
Producción (EE. UU.)	`wss://ws.rhombussystems.com:8443/websocket`
Producción (UE)	`wss://ws.eu.rhombussystems.com:8443/websocket`

Conceptos clave

Tópicos

Una vez conectado, te suscribes a un tópico para recibir mensajes. El tópico principal para eventos organizacionales es:

/topic/change/{orgUuid}

Este tópico emite eventos de cambio de tu organización, incluyendo alertas de políticas, actualizaciones de dispositivos y cambios de configuración. Una conexión recibe solo los eventos que puede ver el rol de su credencial, incluidas las alertas de políticas: un rol con acceso completo recibe todo, y los eventos de dispositivos o ubicaciones fuera del rol se descartan sin error. Consulta Qué recibe una conexión.

Tipos de eventos

Cada mensaje en el tópico de cambios contiene una carga útil JSON con:

Campo	Descripción
`entity`	El tipo de entidad que cambió (por ejemplo, `POLICY_ALERT`, `CAMERA_STATE`)
`entityUuid`	Identificador único de la entidad
`type`	El tipo de cambio: `REFRESH` (predeterminado), `CREATE`, `UPDATE` o `DELETE`
`update`	Los datos de la entidad modificada (presente en algunos eventos)
`deviceUuid`	UUID del dispositivo asociado (cuando aplica)

Autenticación

El handshake de WebSocket lleva la credencial. El WebSocket de eventos acepta una clave de API (estándar o de partner) o un access token de OAuth con el scope read, enviados como encabezados desde un servidor, o un token federado, que también puede ir en la URL para que un navegador se conecte directamente. Las credenciales de partner también deben enviar la organización cliente en el encabezado x-auth-org. Eliminar o revocar una credencial cierra sus conexiones abiertas en 60 segundos o menos.

Nota

Las claves de certificado (mTLS) no se aceptan en el WebSocket de eventos. Si te autenticas a la API REST de Rhombus con una clave de certificado, usa una clave de API estándar, un access token de OAuth o un token federado para las conexiones WebSocket.

Cuándo usar WebSocket vs. la API REST

Caso de uso	Enfoque recomendado
Reaccionar a alertas en tiempo real	WebSocket
Construir un dashboard en vivo	WebSocket
Disparar automatizaciones ante eventos	WebSocket
Consultar datos históricos	API REST
Administrar dispositivos o usuarios	API REST
Recuperar clips de video	API REST (streaming DASH)

Qué sigue

Autenticación

Autentica las conexiones WebSocket con una clave de API, un token de OAuth o un token federado.

Ciclo de vida de la conexión

Establece, mantén y cierra conexiones de forma adecuada.

Monitoreo de eventos

Suscríbete a tópicos y procesa eventos en tiempo real.

Ejemplos de código

Ejemplos completos y funcionales en Python, JavaScript y Go.