Common use-cases with Device Management APIs

A detailed documentation of all available APIs can be found in Device Management API Documentation. Here are some basic use-cases.

• List all cameras claimed to an Azena account
• Claim a device to an Azena account
• List all cameras claimed via API
• Get a list of all available applications/licenses in your account
• Get number of available applications/licenses for specific application 
• Install application on online camera
• Install an application on offline camera
• Uninstalling applications from online camera
• Get all applications currently installed on online camera
• Managing Application Status
• Updating an application

List all cameras claimed to an Azena account

Our Device Management API offers a possibility to list all cameras claimed to an Azena account. Please use the Device Management Tool or login to the camera web-frontend to claim a device to the Azena Cloud. A description on how to access camera web-frontend can be found in Connecting Cameras section.

 

Claim a device to an Azena account

Devices require an active internet connection in order to be claimed to the Azena Platform. More information on potential URL whitelisting can be found here. More information on how to claim a device can be found here.

 

List all cameras claimed via API

API: GET /devices/v1/devices

Returns a list of cameras claimed to the Azena account. Additional filters can be set in the query to limit the number of results.

Remarks:

• The maximum number of returned devices is currently limited to 1000. In case there are more devices claimed to your account, use the page query parameter until the API does not provide any devices anymore.
• Devices in state UNCLAIMED are devices that have installed licenses associated to your account, even if the devices themselves have not been claimed to your account before. This is used to keep track of your license usage also on offline devices.
• The returned deviceID is used to identify a device and is used to perform further API actions.

 

Get a list of all available applications/licenses in your account

API: GET /license/v1/licensequantities

Returns a list that contains the number of used and free license quantities per application and license type in your account. Application license quantities need to be bought via the Azena Application Store. 

 

Get number of available applications/licenses for specific application 

API: GET /license/v1/licensequantities/apps/{appId}

Returns the number of free and used quantities of licenses for a specific application ID and license type.

 

 

Install application on online camera

Step 1: Buy license type quantity for application ID

Application license quantities need to be bought via the Azena Application Store. 

Step 2: Check quantities for application and license type

See Get a list of all available applications/licenses in your account section.

Step 3: Get device ID

See List all cameras claimed via API section.

Step 4: Install application on device

API: PUT /software/v1/apps/{appId}/devices/{deviceId}

Installs the application on the device with the license type specified in payload (FULL, TRIAL, SUBSCRIPTION). Prerequisite is an existing free license quantity for the given license type and application ID and an active internet connection of the device.

 

Install an application on offline camera

Step 1: Buy license type quantity for application ID

Application license quantities need to be bought via the Azena Application Store. 

Step 2: Check quantities for application and license type

See Get a list of all available applications/licenses in your account section.

Step 3: Get device ID

For claimed devices: See List all cameras claimed via API section.

For offline devices: Use ONVIF Discovery.

Step 4: Check for existing license

Check whether a license for specific app and device combination already exists:

API: GET /license/v1/licenses/apps/{appId}/devices/{deviceId}

The response will be an array of license information, each including license ID, license token, application ID and license type.

Step 5: Generate new license (optional)

Generate a new license for a given application ID, device ID and license type. Remark: For license type SUBSCRIPTION, you also need to provide the order ID.

API: PUT /license/v1/licenses

Returns license information for the license created, including a unique license token. Each license has a unique license ID and is bound to a device ID and application ID.

Step 6: Download License

API: GET /license/v1/licenses/{licenseId}/token

Triggers download of a license file with given license ID.

Step 7: Download Application

API: GET /software/v1/apps/{appId}/download

Triggers download of the application .apk binary file.

Step 8: Upload Application and License on Device via ONVIF

Upload the license file and the .apk file on your camera via ONVIF API, see ONVIF server.

 

Uninstalling applications from online camera

API: DELETE /software/v1/apps/{appId}/devices/{deviceId}

Will uninstall an application from a device. This will automatically return the license to your Azena account.

 

Get all applications currently installed on online camera

API: GET /device/v1/devices/{deviceId}/apps

Returns all application IDs currently installed on a device with specified device ID.

 

Managing Application Status

Get application status for a device

API: GET /software/v1/apps/{appId}/devices/{deviceId}

Returns information about application installation state, application running state and whether the app is updatable.

Start or stop application

API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/RUNNING

Starts application on online device.

API: POST /software/v1/apps/{appId}/devices/{deviceId}/state/NOT_RUNNING

Stops application on online device.

 

Updating an application

Follow the optional steps to get information which devices need to be updated.

Step 1: Get all devices with available application updates (optional)

With filter option you can query all devices in your account that have applications installed that can be updated.

API: GET /device/v1/devices?appsUpdatePossible=true

Step 2: Get all applications currently installed on device

API: GET /device/v1/devices/{deviceId}/apps

Returns all application IDs and application status for applications currently installed on a device.

Step 3: Check what application is updatable (optional)

API: GET /software/v1/apps/{appId}/devices/{deviceId}

Returns app status including information whether the app is updatable (true or false).

Step 4: Update app

API: POST /software/v1/apps/{appId}/devices/{deviceId}

Triggers an update of the given application to the latest version.