Difference between revisions of "Sensaphone.net API/history"
(→Sensaphone.net API) |
(→Event Log) |
||
(10 intermediate revisions by 2 users not shown) | |||
Line 8: | Line 8: | ||
The URI Mode for the History API is unique because it allows filtering options to be specified in pairs and can be added in any order. Also, the array values are expressed as a common-separated list. | The URI Mode for the History API is unique because it allows filtering options to be specified in pairs and can be added in any order. Also, the array values are expressed as a common-separated list. | ||
/history/audit_log/var_ids/{1234,9876}/changes/{create} | /history/audit_log/var_ids/{1234,9876}/changes/{create} | ||
+ | |||
+ | ==Timestamps== | ||
+ | The history APIs such as the Data Log use Sensaphone encoded timestamps. This allows the timestamps to be independent of the time zone of the client request, and return results adjusted to the time zone of the device, account, etc. Seconds, minutes, hours, days, and months are 0-indexed, in other words the range of month values is [0,11]. The year value is 2000-based and limited to 100 years. | ||
+ | |||
+ | In order to create a Sensaphone timestamp given the year, month, day, hours, minutes, and seconds, convert each parameter to its equivalent value in seconds. For the example, in pseudo-code, a factory method would look as following: | ||
+ | |||
+ | getSensaphoneTimestamp( year, month, day, hours, minutes, seconds ) { | ||
+ | return ((seconds % 60)) + | ||
+ | ((minutes * 60) % 3600) + | ||
+ | ((hours * 3600) % 86400) + | ||
+ | ((day * 86400) % 2678400) + | ||
+ | ((month * 2678400) % 32140800) + | ||
+ | ((year % 100 * 32140800)); | ||
+ | } | ||
==Audit Log== | ==Audit Log== | ||
Line 18: | Line 32: | ||
}}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids | }}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids | ||
}}{{TableRowN| changes | Optional | Array of String | list of change types ("create","delete","update") | }}{{TableRowN| changes | Optional | Array of String | list of change types ("create","delete","update") | ||
− | }}{{TableRowN| start | Optional | Integer | the start time ( | + | }}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp) |
− | }}{{TableRowN| end | Optional | Integer | the end time ( | + | }}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp) |
}}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | }}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | ||
}}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | }}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | ||
Line 49: | Line 63: | ||
}}{{TableEnd}} | }}{{TableEnd}} | ||
− | *Receive all | + | *Receive all changes for a variable: |
− | '''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/var_ids/{ | + | *'''URI Mode:''' |
+ | '''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/var_ids/{1234} | ||
+ | |||
+ | *'''JSON Mode:''' | ||
+ | '''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/ | ||
+ | |||
+ | { | ||
+ | "request_type": "read", | ||
+ | "history": | ||
+ | { | ||
+ | "audit_log": { | ||
+ | "var_ids" : [1234] | ||
+ | } | ||
+ | } | ||
+ | } | ||
==Data Log== | ==Data Log== | ||
Line 60: | Line 88: | ||
}}{{TableRowN| log_points | Optional | Array of Integer | list of variable ids | }}{{TableRowN| log_points | Optional | Array of Integer | list of variable ids | ||
}}{{TableRowN| status | Optional | Array of String | list of AlarmStatus ("normal", "dependency", "alarm") | }}{{TableRowN| status | Optional | Array of String | list of AlarmStatus ("normal", "dependency", "alarm") | ||
− | }}{{TableRowN| start | Optional | Integer | the start time ( | + | }}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp) |
− | }}{{TableRowN| end | Optional | Integer | the end time ( | + | }}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp) |
}}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | }}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | ||
}}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | }}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | ||
Line 90: | Line 118: | ||
}}{{TableRowN| history | data_log_filter | Object | Audit Log Filter Options (Only returned in V2) | }}{{TableRowN| history | data_log_filter | Object | Audit Log Filter Options (Only returned in V2) | ||
}}{{TableEnd}} | }}{{TableEnd}} | ||
+ | |||
+ | *Receive the last 50 logged datas for a log point | ||
+ | *'''URI Mode:''' | ||
+ | '''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log/log_points/{1234}/begin_offset/{0}/record_offset/{50} | ||
+ | |||
+ | |||
+ | *'''JSON Mode:''' | ||
+ | '''POST''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log | ||
+ | |||
+ | { | ||
+ | "request_type": "read", | ||
+ | "history": | ||
+ | { | ||
+ | "data_log": { | ||
+ | "log_points" : [1234], | ||
+ | "begin_offset" : 0, | ||
+ | "record_offset" : 50 | ||
+ | } | ||
+ | } | ||
+ | } | ||
==Data Log Points== | ==Data Log Points== | ||
Line 151: | Line 199: | ||
}}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids | }}{{TableRowN| user_ids | Optional | Array of Integer | list of user ids | ||
}}{{TableRowN| event_types | Optional | Array of String | list of event types | }}{{TableRowN| event_types | Optional | Array of String | list of event types | ||
− | }}{{TableRowN| start | Optional | Integer | the start time ( | + | }}{{TableRowN| start | Optional | Integer | the start time (Sensaphone timestamp) |
− | }}{{TableRowN| end | Optional | Integer | the end time ( | + | }}{{TableRowN| end | Optional | Integer | the end time (Sensaphone timestamp) |
}}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | }}{{TableRowN| begin_offset | Optional | Integer | the beginning offset of the first record | ||
}}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | }}{{TableRowN| record_offset | Optional | Integer | the offset from the beginning | ||
Line 185: | Line 233: | ||
*Receive last 50 "Alarms Events" for a device: | *Receive last 50 "Alarms Events" for a device: | ||
*'''URI Mode:''' | *'''URI Mode:''' | ||
− | '''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log/device_ids/{ | + | '''GET''' https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log/device_ids/{1234}/event_types/{alarm}/begin_offset/{0}/record_offset/{50} |
*'''JSON Mode:''' | *'''JSON Mode:''' |
Latest revision as of 09:52, 25 October 2017
Contents
Sensaphone.net API
Access
The History API allows access to the Audit Log, the Data Log, and the Event Log
Specifications
The URI Mode for the History API is unique because it allows filtering options to be specified in pairs and can be added in any order. Also, the array values are expressed as a common-separated list.
/history/audit_log/var_ids/{1234,9876}/changes/{create}
Timestamps
The history APIs such as the Data Log use Sensaphone encoded timestamps. This allows the timestamps to be independent of the time zone of the client request, and return results adjusted to the time zone of the device, account, etc. Seconds, minutes, hours, days, and months are 0-indexed, in other words the range of month values is [0,11]. The year value is 2000-based and limited to 100 years.
In order to create a Sensaphone timestamp given the year, month, day, hours, minutes, and seconds, convert each parameter to its equivalent value in seconds. For the example, in pseudo-code, a factory method would look as following:
getSensaphoneTimestamp( year, month, day, hours, minutes, seconds ) { return ((seconds % 60)) + ((minutes * 60) % 3600) + ((hours * 3600) % 86400) + ((day * 86400) % 2678400) + ((month * 2678400) % 32140800) + ((year % 100 * 32140800)); }
Audit Log
Audit Log Filter Options
Property | Status | Type | Description |
var_ids | Optional | Array of Integer | list of variable ids |
user_ids | Optional | Array of Integer | list of user ids |
changes | Optional | Array of String | list of change types ("create","delete","update") |
start | Optional | Integer | the start time (Sensaphone timestamp) |
end | Optional | Integer | the end time (Sensaphone timestamp) |
begin_offset | Optional | Integer | the beginning offset of the first record |
record_offset | Optional | Integer | the offset from the beginning |
GET
Audit Log Request Properties
Parent Property | Child Property | Type | Description |
acctid | Integer | Account ID | |
session | String | Session ID | |
request_type | String | "read" | |
history | Object | The History object | |
history | audit_log | Object | Audit Log Filter Options |
Audit Log Response Properties
Parent Property | Child Property | Type | Description |
history | Object | The history object | |
history | audit_log | Array of Objects | The returned log |
audit_log | change | String | The change that occurred |
audit_log | who | String | Who changed it |
audit_log | what | String | What changed |
audit_log | when | String | When it changed |
audit_log | epoch | Integer | The epoch time |
history | audit_log_filter | Object | Audit Log Filter Options (Only returned in V2) |
- Receive all changes for a variable:
- URI Mode:
GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/var_ids/{1234}
- JSON Mode:
POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/audit_log/
{ "request_type": "read", "history": { "audit_log": { "var_ids" : [1234] } } }
Data Log
Data Log Filter Options
Property | Status | Type | Description |
log_points | Optional | Array of Integer | list of variable ids |
status | Optional | Array of String | list of AlarmStatus ("normal", "dependency", "alarm") |
start | Optional | Integer | the start time (Sensaphone timestamp) |
end | Optional | Integer | the end time (Sensaphone timestamp) |
begin_offset | Optional | Integer | the beginning offset of the first record |
record_offset | Optional | Integer | the offset from the beginning |
GET
Data Log Request Properties
Parent Property | Child Property | Type | Description |
acctid | Integer | Account ID | |
session | String | Session ID | |
request_type | String | "read" | |
history | Object | The History object | |
history | data_log | Object | Data Log Filter Options |
Data Log Response Properties
Parent Property | Child Property | Type | Description |
history | Object | The history object | |
history | data_log | Array of Objects | The returned log |
data_log | record_id | String | The id of the record |
data_log | value | String | The value of the variable |
data_log | variable | String | The variable id |
data_log | is_alarm | String | Is an alarm |
data_log | epoch | Integer | The epoch time |
history | data_log_filter | Object | Audit Log Filter Options (Only returned in V2) |
- Receive the last 50 logged datas for a log point
- URI Mode:
GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log/log_points/{1234}/begin_offset/{0}/record_offset/{50}
- JSON Mode:
POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log
{ "request_type": "read", "history": { "data_log": { "log_points" : [1234], "begin_offset" : 0, "record_offset" : 50 } } }
Data Log Points
Poll the Data Log Points to get the possible logable points to use for the Data Log
GET
Data Log Points Request Properties
Parent Property | Child Property | Type | Description |
acctid | Integer | Account ID | |
session | String | Session ID | |
request_type | String | "read" | |
history | Object | The History object | |
history | data_log_points | Object | |
data_log_points | resource_type | String | the name of the resource, e.g. "device" |
data_log_points | (id_name) | Integer | The ID of the resource, e.g. "device_id" |
Data Log Points Response Properties
Parent Property | Child Property | Type | Description |
history | Object | The history object | |
history | data_log_points | Object | The returned log |
data_log_points | resource_type | String | the name of the resource, e.g. "device" |
data_log_points | (id_name) | Integer | The ID of the resource, e.g. "device_id" |
data_log_points | log_points | Array of Objects | The logable points |
log_points | category | String | The type of logable point |
log_points | (id_name) | Integer | The ID of the resource, e.g. "zone_id" |
log_points | log_point | Integer | The logable point ID |
- Receive all data logable points for a device:
- URI Mode:
GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points/resource_type/{device}/device_id/{1234}
- JSON Mode:
POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/data_log_points
{ "request_type": "read", "history": { "data_log_points": { "resource_type" : "device", "device_id" : 1234 } } }
Event Log
Event Log Filter Options
Property | Status | Type | Description |
contact_ids | Optional | Array of Integer | list of contact ids |
device_ids | Optional | Array of Integer | list of device ids |
zone_ids | Optional | Array of Integer | list of zone ids |
user_ids | Optional | Array of Integer | list of user ids |
event_types | Optional | Array of String | list of event types |
start | Optional | Integer | the start time (Sensaphone timestamp) |
end | Optional | Integer | the end time (Sensaphone timestamp) |
begin_offset | Optional | Integer | the beginning offset of the first record |
record_offset | Optional | Integer | the offset from the beginning |
GET
Event Log Request Properties
Parent Property | Child Property | Type | Description |
acctid | Integer | Account ID | |
session | String | Session ID | |
request_type | String | "read" | |
history | Object | The History object | |
history | event_log | Object | Event Log Filter Options |
Event Log Response Properties
Parent Property | Child Property | Type | Description |
history | Object | The history object | |
history | event_log | Array of Objects | The returned log |
event_log | event | String | Which event |
event_log | when | String | When it changed |
event_log | epoch | Integer | The epoch time |
event_log | type | String | The type |
event_log | source | Object | The sources of the event |
source | <source_name> | String | A source |
history | event_log_filter | Object | Event Log Filter Options (Only returned in V2) |
- Receive last 50 "Alarms Events" for a device:
- URI Mode:
GET https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log/device_ids/{1234}/event_types/{alarm}/begin_offset/{0}/record_offset/{50}
- JSON Mode:
POST https://rest.sensaphone.net/api/v1/{ACCOUNT}/{SESSION}/history/event_log
{ "request_type": "read", "history": { "event_log": { "event_types" : ["alarm"], "device_ids" : [1234], "begin_offset" : 0, "record_offset" : 50 } } }