Message Broker V2.4

Changes are related to the camera detection event types and face resource messages. 

This is the server-to-server communication description.

With the server to server API, it is possible to receive (both camera, user and face resource) events through a message queue. The messages are JSON encoded and are sent over WebSockets with the STOMP protocol.

Before start using this API, we at CameraManger need to setup and configure the message queue before you can use this. The configuration and some more explanation need to be discussed beforehand.

Camera detection event types

There are following event types supported by the new version of the Message Broker: 

  • audioDetected 
  • vmdDetected
  • pirDetected
  • doorbellDetected
  • audioCategorized
  • objectDetected
  • objectInAreaDetected
  • objectTripwireDetected
  • personDetected
  • personInAreaDetected
  • personTripwireDetected
  • animalDetected
  • faceDetected
  • faceRecognized

 

Each event has the same JSON structure:

Fields explanation

Parameter Type Description
account_id integer Unique identifier of the account that event belongs to.
camera_id integer Unique identifier of the camera.
event_id integer Unique identifier of the event.
timestamp string: ISO 8601 date-time Timestamp when the event occurred. In format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ".
type string Type of the event.
action string

The action that took place:

  • “create”: the event was just created.

To get messages related to the events you can subscribe to a topic using following exchange name and routing key:

 

Note:
  exchange_name = {system name}_{message_type}
  routing_key = {partnerId}.{acountId}.{cameraId}.{action}.{eventTypes}

Fields explanation

Topic

Description

{system name} A unique name given by EEN to each analytics system
{message_type} Internal version of our event API. For camera detection events it is "event_v24".
{partnerId} Unique identifier of the partner (reseller or distributor) that the end-user account belongs to.
{accountId} Unique identifier of the account the event belongs to.
{cameraId} Unique identifier of the camera.
{action}

For event resource messages, there currently is a single action type:

  • “create”: the event was just created.

{eventTypes}

The “eventTypes” path variable can be used to identify and filter on the event types the client is interested in. The variable is composed of the event type of the event and all super types of that type, ordered from parent to child.

As an example, the `eventType` variable for a `faceRecognized` would be: `objectDetected.faceDetected.faceRecognized`, which allows clients that only support `objectDetected` to receive and handle the same events as a client that support `faceRecognized`.


Examples

 



Face resource messages 

JSON structure

Fields explanation

Parameter Type Description
account_id integer Unique identifier of the account that event belongs to.
identityId string:GUID Unique identifier in GUID format of the person.
timestamp string: ISO 8601 date-time Timestamp when the event occurred. In format: "yyyy-MM-dd'T'HH:mm:ss.SSSZ".
action string

The action that took place:

  • “create”: the face was just created.

  • “update”: the face just changed.

  • delete: an existing face was deleted by the system as it is not marked as “known” and no events remain with the identityId.

To get messages related to faces you can subscribe to a topic using following exchange name and routing key:
Note:
  exchange_name = {system name}_{message_type}
  routing_key = {partnerId}.{acountId}.{action}

Fields explanation

Topic

Description

{system name} A unique name given by EEN to each analytics system
{message_type} Internal version of our event API. For camera detection events it is "face_v24".
{partnerId} Unique identifier of the partner (reseller or distributor) that the end-user account belongs to.
{accountId} Unique identifier of the account the event belongs to.
{action}

For face resource messages, there are three possible action types:

  • create: a new face was created.

  • update: an existing face was changed.

  • delete: an existing face was deleted by the system as it is not marked as “known” and no events remain with the identityId.

Examples

Topic filtering

Although it can be useful to subscribe to a specific topic, normally wildcards will be used to receive events from a wide range. A topic is built up out of multiple words separated by `.` (dot) characters,

The following wildcards are accepted:

  • `*` (star) can substitute for exactly one word.

  • `#` (hash) can substitute for zero or more words.

For example, an event with routing key `12345.12345.32.create.objectDetected.faceDetected` Matches:

  • 12345.12345.32.create.objectDetected.faceDetected : True

  • 12345.12345.32.create.objectDetected.faceDetected.# : True

  • 12345.12345.32.create.objectDetected.# : True

  • 12345.12345.32.create.objectDetected : False

  • 12345.12345.*.create.objectDetected.faceDetected : True

  • 12345.*.*.create.objectDetected.faceDetected : True

  • 12345.*.*.*.objectDetected.faceDetected : True

  • *.12345.32.create.# : True

STOMP communication example


Message consumer connects to the Cameramanager server at IP messages.cameramanager.com using WebSockets protocol and STOMP transport.

The consumer is authenticated by using the partner email and its password to be used in the Authorization header like:

ws://messages.cameramanager.com:2080/stomp/v1

or

wss://messages.cameramanager.com:2443/stomp/v1

Authorization: Basic <partner_email>:<password>

(<partner_email>:<password> should be encoded in Base64)



Communication example on STOMP level:
*Client/message consumer messages are marked by red
*Server/message broker messages are marked by grey
*******************
CONNECT     
accept-version:1.2
heart-beat:30000,60000      <<< setup ping intervals in seconds


.
CONNECTED
session:session-1ft-6Znzeu34Y0bgw9ibaw
heart-beat:60000,30000
version:1.2


.
SUBSCRIBE
destination:/exchange/<exchange_name>/<routing_key    <<< subscribe to the exchange <exchange_name> for a specific routing key
ack:client                                           <<< client will send explicit acknowledgement message
prefetch-count:1                                <<< number of prefetch messages


.
MESSAGE
destination/exchange/<exchange_name>/123.456.32.create.objectDetected.faceDetected  <<< event of type «faceDetected»
message-id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@2
redelivered:false
expiration:120000
content-type:application/json
content-length:122


{"accountId":456,"cameraId":32,"eventId":15720517375,"timestamp":"2020-11-17T14:02:28.086+0000","type":"faceDetected","action":"create"}


ACK
id:Q_/exchange/<exchange_name>@@session-u0pwVrymhyUHmLLwD6ERnQ@@2

*****************


Note:
You can use all possibilities of the stomp protocol
- subscribe to different queues via the same connection
- open simultaneously multiple connections
- control the way of acknowledgement mechanism: auto/client/client-individual (for further information check stomp documentation at https://stomp.github.io/)