ZaneYork
/
zoneminder
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Added updated API information 

Reflected new APIs, corrected and updated examples
This commit is contained in:
Pliable Pixels 2015-06-14 11:21:00 -04:00
parent 3ef916f49c
commit 71665a3315
1 changed files with 131 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

224
docs/api.rst
View File

@ -24,16 +24,25 @@ you will be in. I like json, however you can use xml if you'd like.
(In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running) (In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running)
API Version
^^^^^^^^^^^
To retrieve the API version:
::
http://server/zm/api/host/getVersion.json
Return a list of all monitors Return a list of all monitors
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:: ::
curl -XGET http://server/zm/api/monitors.json curl -XGET http://server/zm/api/monitors.json
Retrieve monitor 1 Retrieve monitor 1
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
:: ::
curl -XGET http://server/zm/api/monitors/1.json curl -XGET http://server/zm/api/monitors/1.json
@ -41,36 +50,37 @@ Change State of Monitor 1
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
This API changes monitor 1 to Modect and Enabled This API changes monitor 1 to Modect and Enabled
``` ::
curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true"
``` curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true"
Add a monitor Add a monitor
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
This command will add a new http monitor. This command will add a new http monitor.
``` ::
curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \
&Monitor[Function]=Modect \ curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \
&Monitor[Protocol]=http \ &Monitor[Function]=Modect \
&Monitor[Method]=simple \ &Monitor[Protocol]=http \
&Monitor[Host]=usr:pass@192.168.11.20 \ &Monitor[Method]=simple \
&Monitor[Port]=80 \ &Monitor[Host]=usr:pass@192.168.11.20 \
&Monitor[Path]=/mjpg/video.mjpg \ &Monitor[Port]=80 \
&Monitor[Width]=704 \ &Monitor[Path]=/mjpg/video.mjpg \
&Monitor[Height]=480 \ &Monitor[Width]=704 \
&Monitor[Colours]=4" &Monitor[Height]=480 \
``` &Monitor[Colours]=4"
Edit monitor 1 Edit monitor 1
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^
This command will change the 'Name' field of Monitor 1 to 'test1' This command will change the 'Name' field of Monitor 1 to 'test1'
``` ::
curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1"
``` curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1"
Delete monitor 1 Delete monitor 1
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
@ -78,16 +88,18 @@ Delete monitor 1
This command will delete Monitor 1, but will _not_ delete any Events which This command will delete Monitor 1, but will _not_ delete any Events which
depend on it. depend on it.
``` ::
curl -XDELETE http://server/zm/api/monitors/1.json
``` curl -XDELETE http://server/zm/api/monitors/1.json
Return a list of all events Return a list of all events
^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``` ::
curl -XGET http://server/zm/api/events.json
``` curl -XGET http://server/zm/api/events.json
Note that events list can be quite large and this API (as with all other APIs in ZM) Note that events list can be quite large and this API (as with all other APIs in ZM)
uses pagination. Each page returns a specific set of entries. By default this is 25 uses pagination. Each page returns a specific set of entries. By default this is 25
@ -95,46 +107,51 @@ and ties into WEB_EVENTS_PER_PAGE in the ZM options menu.
So the logic to iterate through all events should be something like this (pseudocode): So the logic to iterate through all events should be something like this (pseudocode):
(unfortunately there is no way to get pageCount without getting the first page) (unfortunately there is no way to get pageCount without getting the first page)
```
data = http://server/zm/api/events.json?page=1 # this returns the first page ::
# The json object returned now has a property called data.pagination.pageCount
count = data.pagination.pageCount; data = http://server/zm/api/events.json?page=1 # this returns the first page
for (i=1, i<count, i++) # The json object returned now has a property called data.pagination.pageCount
{ count = data.pagination.pageCount;
data = http://server/zm/api/events.json?page=i; for (i=1, i<count, i++)
doStuff(data); {
} data = http://server/zm/api/events.json?page=i;
``` doStuff(data);
}
Retrieve event Id 1000 Retrieve event Id 1000
^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^
``` ::
curl -XGET http://server/zm/api/events/1000.json
``` curl -XGET http://server/zm/api/events/1000.json
Edit event 1 Edit event 1
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
This command will change the 'Name' field of Event 1 to 'Seek and Destroy' This command will change the 'Name' field of Event 1 to 'Seek and Destroy'
``` ::
curl -XPUT http://server/zm/api/events/1.json -d "Event[Name]=Seek and Destroy"
``` curl -XPUT http://server/zm/api/events/1.json -d "Event[Name]=Seek and Destroy"
Delete event 1 Delete event 1
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
This command will delete Event 1, and any Frames which depend on it. This command will delete Event 1, and any Frames which depend on it.
``` ::
curl -XDELETE http://server/zm/api/events/1.json
``` curl -XDELETE http://server/zm/api/events/1.json
Return a list of events for a specific monitor Id =5 Return a list of events for a specific monitor Id =5
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``` ::
curl -XGET http://server/zm/api/events/events/index/MonitorId:5.json``
``` curl -XGET http://server/zm/api/events/events/index/MonitorId:5.json``
Note that the same pagination logic applies if the list is too long Note that the same pagination logic applies if the list is too long
@ -142,22 +159,25 @@ Note that the same pagination logic applies if the list is too long
Return a list of events for a specific monitor within a specific date/time range Return a list of events for a specific monitor within a specific date/time range
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``` ::
http://server/zm/api/events/events/index/MonitorId:5/StartTime >=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json
``` http://server/zm/api/events/events/index/MonitorId:5/StartTime >=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json
To try this in CuRL, you need to URL escape the spaces like so: To try this in CuRL, you need to URL escape the spaces like so:
``` ::
curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json"
``` curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json"
Return a list of events for all monitors within a specified date/time range Return a list of events for all monitors within a specified date/time range
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``` ::
curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json"
``` curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json"
Configuration Apis Configuration Apis
@ -166,9 +186,10 @@ Configuration Apis
The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console. The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console.
This returns the full list of configuration parameters: This returns the full list of configuration parameters:
``` ::
curl -XGET http://server/zm/api/configs.json
``` curl -XGET http://server/zm/api/configs.json
Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3. Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3.
@ -180,48 +201,65 @@ Run State Apis
ZM API can be used to start/stop/restart/list states of ZM as well ZM API can be used to start/stop/restart/list states of ZM as well
Examples: Examples:
``` ::
curl -XGET http://server/zm/api/states.json # returns list of run states
curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM curl -XGET http://server/zm/api/states.json # returns list of run states
curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM
curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM
``` curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM
Create a Zone Create a Zone
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
``` ::
curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \
&Zone[MonitorId]=3 \ curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \
&Zone[Type]=Active \ &Zone[MonitorId]=3 \
&Zone[Units]=Percent \ &Zone[Type]=Active \
&Zone[NumCoords]=4 \ &Zone[Units]=Percent \
&Zone[Coords]=0,0 639,0 639,479 0,479 \ &Zone[NumCoords]=4 \
&Zone[AlarmRGB]=16711680 \ &Zone[Coords]=0,0 639,0 639,479 0,479 \
&Zone[CheckMethod]=Blobs \ &Zone[AlarmRGB]=16711680 \
&Zone[MinPixelThreshold]=25 \ &Zone[CheckMethod]=Blobs \
&Zone[MaxPixelThreshold]= \ &Zone[MinPixelThreshold]=25 \
&Zone[MinAlarmPixels]=9216 \ &Zone[MaxPixelThreshold]= \
&Zone[MaxAlarmPixels]= \ &Zone[MinAlarmPixels]=9216 \
&Zone[FilterX]=3 \ &Zone[MaxAlarmPixels]= \
&Zone[FilterY]=3 \ &Zone[FilterX]=3 \
&Zone[MinFilterPixels]=9216 \ &Zone[FilterY]=3 \
&Zone[MaxFilterPixels]=230400 \ &Zone[MinFilterPixels]=9216 \
&Zone[MinBlobPixels]=6144 \ &Zone[MaxFilterPixels]=230400 \
&Zone[MaxBlobPixels]= \ &Zone[MinBlobPixels]=6144 \
&Zone[MinBlobs]=1 \ &Zone[MaxBlobPixels]= \
&Zone[MaxBlobs]= \ &Zone[MinBlobs]=1 \
&Zone[OverloadFrames]=0" &Zone[MaxBlobs]= \
``` &Zone[OverloadFrames]=0"
PTZ Control APIs
^^^^^^^^^^^^^^^^
PTZ controls associated with a monitor are stored in the Controls table and not the Monitors table inside ZM. What that means is when you get the details of a Monitor, you will only know if it is controllable (isControllable:true) and the control ID.
To be able to retrieve PTZ information related to that Control ID, you need to use the controls API
This returns all the control definitions:
::
curl http://server/zm/api/controls.json
This returns control definitions for a specific control ID=5
::
curl http://server/zm/api/controls/5.json
Host APIs Host APIs
^^^^^^^^^^ ^^^^^^^^^^
ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples: ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples:
``` ::
curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running
curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running
curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) `` curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM
``` curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) ``