开发者中心

报警

报警接口由三部分组成:

  • 资源 alarm API 返回一个或者多个URI和报警集合的URI模板,这样就可以检索全部的报警或者特定来源的设备报警还有状态。

  • 资源 alarm collection 检索报警,创建新的报警。

  • 资源 alarm 代表单独的报警,可以通过报警工作流进行查询、修改和推进。

注意,对于所有的PUT/POST request,应该提供accept header,否则一个空的response body将被返回。

报警API

AlarmAPI [application/vnd.com.nsn.cumulocity.alarmApi+json]
名字 类型 出现次数 描述
self URL 1 指向这个资源的链接
alarms AlarmCollection 1 所有告警的集合
alarmsForStatus AlarmCollection URI template 1 只读的处于特定状态(占位符{status},参见下面的"Alarm"资源中可以使用的值)的所有报警集合。
alarmsForSource AlarmCollection URI template 1 只读的特定源对象(占位符{source},目录中的对象的唯一ID)的所有报警集合。
alarmsForSourceAndStatus AlarmCollection URI template 1 只读的处于特定状态的特定源对象(占位符{source}和{status})的所有报警集合。
alarmsForTime AlarmCollection URI template 1 只读的在特定时间段内(占位符{dateFrom}和{dateTo})的所有报警集合。
alarmsForStatusAndTime AlarmCollection URI template 1 只读的在特定时间段内处于特定状态(占位符 {status},{dateFrom}和{dateTo})的所有报警集合。
alarmsForSourceAndTime AlarmCollection URI template 1 只读的在特定时间段内特定源对象(占位符 {source},{dateFrom}和{dateTo})的所有报警集合。
alarmsForSourceAndStatusAndTime AlarmCollection URI template 1 只读的在特定时间段内处于特定状态的特定源对象(占位符 {source}, {status},{dateFrom}和{dateTo})的所有报警集合。
GET AlarmAPI资源

应答正文: application/vnd.com.nsn.cumulocity.alarmApi+json

需要角色权限: ROLE_ALARM_READ

请求示例:

GET /alarm
                      Host: ...
                      Authorization: Basic ...
                    

应答示例:

HTTP/1.1 200 OK
                      Content-Type: application/vnd.com.nsn.cumulocity.alarmApi+json;ver=…
                      Content-Length: …
                      {
                      "self" : "<<AlarmAPI URL>>",
                      "alarms" : { "self" :"<<AlarmCollection URL>>" },
                      "alarmsForStatus" : "<<AlarmCollection URL>>?status={status}",
                      "alarmsForSource" : "<<AlarmCollection URL>>?source={source}",
                      "alarmsForSourceAndStatus" : "<<AlarmCollection URL>>?source={source}&status={status}",
                      "alarmsForTime" : "<<AlarmCollection URL>>?dateFrom={dateFrom}&dateTo={dateTo}",
                      "alarmsForStatusAndTime" : "<<AlarmCollection URL>>?status={status}&dateFrom={dateFrom}&dateTo={dateTo}",
                      "alarmsForSourceAndTime" : "<<AlarmCollection URL>>?source={source}&dateFrom={dateFrom}&dateTo={dateTo}",
                      "alarmsForSourceAndStatusAndTime" : "<<AlarmCollection URL>>?source={source}&status={status}&dateFrom={dateFrom}&dateTo={dateTo}"
                    }
                  

报警集合

AlarmCollection [application/vnd.com.nsn.cumulocity.alarmCollection+json]
名字 类型 出现次数 描述
self URL 1 指向这个资源的链接
alarms Alarm 0..n 报警列表, 参见下面。
statistics PagingStatistics 1 分页的统计信息。
prev URI 0..1 指向可能的前一页报警的链接。
next URI 0..1 指向可能的后一页报警的链接。
GET 报警集合

应答正文: AlarmCollection

需要角色权限: ROLE_ALARM_READ

请求示例:

GET /alarm/alarms
                    Host: ...
                    Authorization: Basic ...
                    Accept: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...
                  

应答示例:

HTTP/1.1 200 OK
                    Content-Type: application/vnd.com.nsn.cumulocity.alarmCollection+json;ver=...
                    Content-Length: ...

                    {
                    "self" : "...",
                    "next" : "...",
                    "prev" : "...",
                    "alarms": [
                    {
                    "id" : "10",
                    "self" : "...",
                    "creationTime" : "2011-09-06T12:03:27.927Z",
                    "type" : "com_cumulocity_events_TamperEvent",
                    "time" : "2011-09-06T12:03:27.845Z",
                    "text" : "Tamper sensor triggered",
                    "status" : "ACTIVE",
                    "severity" : "MAJOR",
                    "source": { "id" : "12345", "self" : "..." },
                    "count":1,
                    "history": { ... }
                  },
                  {
                  "id" : "11",
                  "self" : "...",
                  "creationTime" : "2011-09-06T12:03:27.927Z",
                  "type" : "com_cumulocity_events_BatteryWarning",
                  "time" : "2011-09-06T12:04:27.845Z",
                  "text" : "Low battery level",
                  "status" : "ACTIVE",
                  "severity" : "MINOR",
                  "source": { "id" : "1122", "self" : "..." },
                  "count":1,
                  "history": { ... }
                }
                ],
                "statistics" : {
                "totalPages" : 8,
                "pageSize" : 5,
                "currentPage : 1
              }
            }
          
POST - 创建一个新的报警

请求正文: 报警

应答正文: 报警

需要角色权限: ROLE_ALARM_ADMIN 或者一个源对象的所有者

请求示例:

POST /alarm/alarms
            Host: ...
            Authorization: Basic ...
            Content-Length: ...
            Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...

            {
            "type" : "com_cumulocity_events_TamperEvent",
            "time" : "2011-09-06T12:03:27.845Z",
            "text" : "Tamper sensor triggered",
            "status" : "ACTIVE",
            "severity" : "MAJOR",
            "source" : { "id" : "12345", "self" : "..." },
            "com_mycorp_MyProp" : { ... }
          }
        

应答示例:

HTTP/1.1 201 Created
          Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
          Content-Length: ...
          Location: <<URL of new alarm>>

          {
          "id" : "10",
          "self" : "<<URL of new alarm>>",
          "creationTime" : "2011-09-06T12:03:27.927Z",
          "type" : "com_cumulocity_events_TamperEvent",
          "time" : "2011-09-06T12:03:27.845Z",
          "text" : "Tamper sensor triggered",
          "status" : "ACTIVE",
          "severity" : "MAJOR",
          "source" : { "id" : "12345", "self" : "..." },
          "count": 1,
          "com_mycorp_MyProp" : { ... }
          "history" : { ... }
        }
      

对于POST请求,源参数必须只有一个"id"。

新的报警的"id"和"creationTime"是由服务器生成并在POST操作的应答中返回。

禁止报警 如果源设备处于 维护 状态, 报警不会创建,也不会发送到QuarkIoE的事件处理引擎。

消除重复报警 如果已经存在一个相同来源相同类型的报警,这个报警处于有效的或者被确认的状态(尚未清除),则不会产生新的报警。 只是增加现有报警的"count"属性值,其他变化都被忽略,不会更新报警的历史记录。第一次报警出现的时间被记录在 "firstOccurenceTime"。

DELETE - 删除一个报警集合

DELETE方法允许删除报警集合。使用的请求参数等同于GET方法。

请求正文: N/A

应答正文: N/A

需要角色权限: ROLE_ALARM_ADMIN

请求示例 :

 DELETE: /alarm/alarms....
       Host: ...
       Authorization: Basic ...
     

应答示例:

HTTP/1.1  204 NO CONTENT
     

报警

Alarm [application/vnd.com.nsn.cumulocity.alarm+json]
名字 类型 出现次数 描述 PUT/POST
id String 1 唯一标记一个报警 No
self URI 1 指向这个资源的链接。 No
creationTime String 1 在数据库中创建报警的时间。 No
type String 1 标记这个报警的类型,例如,"com_cumulocity_events_TamperEvent"。 POST: 强制 PUT: No
time String 1 报警的时间。 POST: 强制 PUT: No
text String 1 报警的文字描述。 POST: 强制 PUT: No
source ManagedObject 1 报警来源的ManagedObject, 对象包含"id"属性值。 POST: Mandatory PUT: No
status String 0..1报警的状态: ACTIVE, ACKNOWLEDGED or CLEARED。如果状态没有出现,则新的报警状态为ACTIVE。必须大写。 POST: 可选 PUT: 可选
severity String 1 报警的等级: CRITICAL, MAJOR, MINOR or WARNING。必须大写。 POST: 强制 PUT: 可选
count Long 1 这个报警发出的次数。 No
firstOccurenceTime String 1 第一次报警发生的时间 (即"count"为1)。 No
history AuditRecordCollection 1 追踪属性变化的修改历史记录。 No
* Object 0..n 事件的附加属性。
GET 一个报警

应答报文: 报警

需要角色权限: ROLE_ALARM_READ

请求示例:

GET /alarm/alarms/<<alarmId>>
      Host: ...
      Authorization: Basic ...
      Accept: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
    

应答示例 :

HTTP/1.1 200 OK
      Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
      Content-Length: ...
      {
      "id" : "10",
      "self" : "<<Alarm URL>>",
      "creationTime" : "2011-09-06T12:03:27.927Z",
      "type" : "com_cumulocity_events_TamperEvent",
      "time" : "2011-09-06T12:03:27.845Z",
      "text" : "Tamper sensor triggered",
      "status" : "ACTIVE",
      "severity" : "MAJOR",
      "source" : { "id" : "12345", "self" : "..." },
      "com_mycorp_MyProp" : { ... }
      "history" : {
      "self" : "...",
      "auditRecords" : [ ... ],
    }
  }
更新一个报警

报警的变化会生成一条新的监控记录,添加到"history"集合。监控记录包含用户名和触发更新的应用(如果适用)。

请注意,如果更新实际上并没有改变任何东西(即request body包含的数据和已经存储的的数据库中是相同的),将没有审计记录添加,并没有通知将被发送。

请求正文: 报警

应答正文: 报警

需要角色权限 : ROLE_ALARM_ADMIN or owner of source object

请求示例:

PUT /alarm/alarms/<<alarmId>>
  Host: ...
  Authorization: Basic ...
  Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
  {
  "severity" : "minor"
}

应答示例:

HTTP/1.1 200 OK
  Content-Type: application/vnd.com.nsn.cumulocity.alarm+json;ver=...
  Content-Length: ...
  {
  "id" : "10",
  "self" : "<<Alarm URL>>",
  "creationTime" : "2011-09-06T12:03:27.927Z",
  "type" : "com_cumulocity_events_TamperEvent",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Tamper sensor triggered",
  "status" : "ACKNOWLEDGED",
  "severity" : "MINOR",
  "source" : { "id" : "12345", "self" : "..." },
  "history" : {
  "self" : "link to audit history",
  "auditRecords" : [
  {
  "id" : "123",
  "self" : "...",
  "type" : "com_cumulcity_model_alarm_AlarmRaised",
  "creationTime" : "2011-09-06T12:03:32.103Z",
  "time" : "2011-09-06T12:03:27.845Z",
  "text" : "Alarm raised",
  "user" : "Spock",
  "application" : "Omniscape",
  "activity" : "Alarm raised",
  "severity" : "MINOR",
  "source" : { ... }
},
{
  "id" : "1234",
  "self" : "...",
  "type" : "com_cumulcity_model_alarm_AlarmChanged",
  "creationTime" : "2011-09-07T12:04:29.031Z",
  "changes": [{
  "attribute": "severity",
  "newValue": {},
  "previousValue": {},
  "type": "com.cumulocity.model.event.CumulocitySeverities"
}],
"time" : "2011-09-07T12:04:27.845Z",
"text" : "Alarm changed",
"user" : "Spock",
"application" : "Omniscape",
"activity" : "Alarm changed.",
"severity" : "Minor",
"source" : { ... }
}
]
}
}

通知

报警通知API允许监控特定设备的报警。

接收通知的基本协议在这个部分讲述 "Real-time notifications"。url是

/cep/realtime

订阅频道需要包含设备的托管对象ID或一个"*"作为占位符接收所有设备的报警通知。

/alarms/<<deviceId>>

应答将在报警对象上附加包含一个"realtimeaction"来标志哪些操作导致给定的对象(CREATE, UPDATE or DELETE)。在删除数据的情况下,只会包含删除报警的ID。

应答示例:

HTTP/1.1 200 OK 
  Content-Type: application/json
  [
  {
  "channel": "/alarms/12345", 
  "successful": true, 
  "error": "", 
  "data": [{
  "realtimeAction": "UPDATE",
  "data": {
  "id": "1",
  "self": "...",
  "source": { 
  "12345"
},
"type": "c8y_UnavailabilityAlarm",
"text": "I am an alarm",
"severity": "MINOR",
"status": "CLEARED",
"firstOccurrence": true,
"count": 1
}
}], 
"clientId": "Un1q31d3nt1f13r" 
}
]

需要角色权限: ROLE_ALARMS_READ