Skip to main content

Analytics MQTT API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to the Device Configuration APIs section in the VAPIX®.

warning

This API is in BETA stage and provided for testing purposes. It is subject to backward-incompatible changes, including modifications to its functionality, behavior and availability. The API should not be used in production environments.

Overview​

There are internal producers of analytics data on the camera, known as "analytics data sources". The Analytics MQTT API allows you to create publishers to send analytics data from these sources to the specified MQTT (Message Queuing Telemetry Transport) topics.

Use cases​

Get available analytics data sources​

This example shows how to get all analytics data sources available for sending data over MQTT.

JSON request:

GET /config/rest/analytics-mqtt/v1beta/data_sources HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "data_sources": [
            {
                "key": "com.axis.analytics_scene_description.v0.beta#1"
            },
            {
                "key": "com.axis.consolidated_track.v1.beta#1"
            },
            {
                "key": "some_other_structure#other_information=value1"
            }
        ]
    }
}

Add a publisher​

This example shows how to add a publisher that sends data from the analytics data source over MQTT.

JSON request:

POST /config/rest/analytics-mqtt/v1beta/publishers HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {
        "id": "my_publisher",
        "data_source_key": "com.axis.analytics_scene_description.v0.beta#1",
        "mqtt_topic": "my_mqtt_topic",
        "qos": 0,
        "retain": false,
        "use_topic_prefix": false
    }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

Get existing publishers​

This example shows how to get the existing publishers.

JSON request:

GET /config/rest/analytics-mqtt/v1beta/publishers HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": [
        {
            "id": "my_publisher",
            "key": "com.axis.analytics_scene_description.v0.beta#1",
            "mqtt_topic": "my_mqtt_topic",
            "qos": 0,
            "retain": false,
            "use_topic_prefix": false
        },
        {
            "id": "another_publisher",
            "key": "com.axis.analytics_scene_description.v0.beta#1",
            "mqtt_topic": "my_other_mqtt_topic",
            "qos": 1,
            "retain": true,
            "use_topic_prefix": false
        }
    ]
}

Delete a publisher​

This example shows how to delete a specified publisher to stop it from sending data over MQTT.

JSON request:

DELETE /config/rest/analytics-mqtt/v1beta/publishers/my_publisher HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success"
}

API definition​

Structure​

analytics-mqtt.v1 (Root Entity)
    ├── data_sources (Entity Collection)
        ├── key (Property)
    ├── publishers (Entity Collection)
        ├── data_source_key (Property)
        ├── id (Property)
        ├── mqtt_topic (Property)
        ├── qos (Property)
        ├── retain (Property)
        ├── use_topic_prefix (Property)

Entities​

analytics-mqtt.v1​

  • Description: Root entity
  • Type: Singleton
  • Operations:
    • Get

analytics-mqtt.v1.data_sources​

  • Description: The data sources
  • Type: Collection (Key property: key)
  • Operations:
    • Get
Properties​
analytics-mqtt.v1.data_sources.key​
  • Description: A key to reference an analytics data source
  • Data Type: data_source_key
  • Operations:
    • Get
      • Permissions: admin

analytics-mqtt.v1.publishers​

  • Description: The created publishers
  • Type: Collection (Key property: id)
  • Operations:
    • Get
    • Add
      • Permissions: admin
      • Required properties: id, data_source_key, mqtt_topic
      • Optional properties: qos, retain, use_topic_prefix
    • Remove
      • Permissions: admin
Properties​
analytics-mqtt.v1.publishers.data_source_key​
  • Description: An analytics datasource key
  • Data Type: data_source_key
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.id​
  • Description: Publisher identifier
  • Data Type: id
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.mqtt_topic​
  • Description: The MQTT topic
  • Data Type: mqtt_topic
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.qos​
  • Description: The quality of service level
  • Data Type: qos
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.retain​
  • Description: The retain policy
  • Data Type: Boolean
  • Operations:
    • Get
      • Permissions: admin
analytics-mqtt.v1.publishers.use_topic_prefix​
  • Description: Use topic prefix, configured in MQTT client
  • Data Type: Boolean
  • Operations:
    • Get
      • Permissions: admin

Data types​

data_source_key​

{
      "description": "An analytics datasource key.",
      "maxLength": 128,
      "minLength": 3,
      "type": "string"
}

id​

{
      "description": "Publisher identifier.",
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
}

mqtt_topic​

{
      "description": "The mqtt topic",
      "maxLength": 128,
      "minLength": 1,
      "pattern": "^([a-zA-Z0-9_-]+)(/[a-zA-Z0-9_-]+)*$",
      "type": "string"
}

qos​

{
      "description": "The quality of service level of a publisher",
      "enum": [
        0,
        1,
        2
      ],
      "type": "integer"

}
Last updated on