How to Change Resource Attributes Using API?

Abstract

The article exposes the procedure of how to programmatically change parameters for a generic RTSP resource. Manual invocation of API calls is being discovered in step by step manner in order to make possible the procedure be automated by a script.

The API methods used below can modify the most basic structure of the resource, which makes use of these methods dangerous. These methods have to be used carefully.

Back your databases up before proceeding with activities described hereafter.

Identifying your resource

1.1. Log in to your System with Nx Witness.

1.2. In the resource tree select the RTSP resource of your interest. 

1.3. Right-click on the camera, select “Camera Settings...”

1.4. Copy camera ID from the “Camera ID” field on the “Advanced” tab into a text file.

Getting the list of parameters

Log in with a web browser to your server which the camera is connected to.

http://<your server address>:<port>

For example: http://localhost:7001

Select the “For Developers” menu item. Then click the link “API Testing Tool (new)”

In the search field type “getResourceParams”

Click the link “getResourceParams” appeared in the method tree below.

On the page appears 

• in the “id” field type the ID you got in the step 1.4;
• click “Test method” button;
• copy content of the “Response” field to the text editor of your choice.

Pay your attention,  the opening square bracket in the beginning of the “Response” field means the method returns an array of json objects.

Find the “streamUrl” string. The json object for the parameters has to be similar to the following:

{
    "name": "streamUrls",
    "resourceId": "{c6c4978e-01a8-92d0-a330-d2833596f6bd}",
    "value": "{\n \"1\": \"rtsp://192.168.0.64:554/ISAPI/Streaming/channels/103\",\n \"2\": \"rtsp://192.168.0.64:554/ISAPI/Streaming/channels/104\",\n \"3\": \"rtsp://192.168.0.64:554/ISAPI/Streaming/channels/105\"\n}\n"
}

The “value” is a serialized json object.

Changing resource parameters

In order to change resource parameters, the setResouceParams API method should be used. Note, this method is not documented in version 3.2 and below.

Parameters have to be passed as a JSON object in POST message body with content-type "application/json". 

This is a System API method. The /ec2/ string has to be put in the URL

http://<your_server_address>:<port>/ec2/setResouceParams

Let’s consider an example to demonstrate how this method works.

If we want to set URLs of two streams for the generic RTSP resource, we have to change the streamUrls parameter of the resource. As it was shown above we have to construct json object of the following structure:

{
  "name": "streamUrls",
  "resourceId": "{c6c4978e-01a8-92d0-a330-d2833596f6bd}",
  "value": ""
}

Here is the structure of “value”:

"value": {
    "2": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/102"
}

That means the stream number 2 of the resource with resourceId will have the value assigned rtsp://192.168.0.64:554/ISAPI/Streaming/channels/102

If you want to change several streams at once you have to enumerate all of them in the “value” object. Here is the example for our case:

"value": {
    "1": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/110",
    "2": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/102"
}

Note: The “value” object has to be serialized before passing to the setResouceParams method.

Now the object of streamUrls parameter has to be put to the json array before passing to setResouceParams method. The final view of the structure to be passed looks like this:

[
    {
        "name": "streamUrls",
        "resourceId": "{c6c4978e-01a8-92d0-a330-d2833596f6bd}",
        "value": {
            "1": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/110",
            "2": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/102"
        }
]

Here the example code in python for our case:

import requests
import json

# constructing the json array with one object for the streamUrls parameter to be changed.
payload = [
    # constructing the object for streamUrls parameter
    dict(
        # the ID of the resource got in the step 1.4
        resourceId='{c6c4978e-01a8-92d0-a330-d2833596f6bd}',
        name='streamUrls',
        # constructing value object
        # the json.dumps - serializes the object to the string
        value=json.dumps({
            "1": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/110",
            "2": "rtsp://192.168.0.64:554/ISAPI/Streaming/channels/102"
        })

]
api_method = 'setResourceParams'
request_url = server_url + api_method
res = requests.post(
    request_url,
    auth=(username, password),
    json=payload
)
res = res.json()
print(res)