开发者中心

实时通知

概述

本节介绍QuarkIoE平台的实时通知。

服务的订阅通道名称格式和URL参见REST接口的通知一节。

实时通知API让QuarkIoE平台可以和受限网络客户端(如web浏览器和移动设备)响应通讯。客户端订阅所谓的通道接收消息。这些通道由QuarkIoE平台的实时语句或新创建的操作输出来填充。 此外, 特定的系统通道用于和客户端的握手信息, 订阅通道, 从通道一出和连接。通讯机制采用Bayeux协议 over HTTP。

注意: 所有的PUT/POST请求必须设置accept头, 否则会返回空的应答正文。

握手

实时通知客户端通过发送消息到"/meta/handshake"通道协商连接初始化。客户端在应答报文中收到clientId用于标记会话, 在非握手请求中必须包含。

请求
名称 类型 次数 描述
id Integer 1 消息Id, 用于匹配应答消息
channel URI 1 通道名称, "/meta/handshake"中的值。
version String 1 客户端使用的Bayeux协议版本。
minimumVersion String 0..1 客户端需要的服务器端最低Bayeux协议版本。
supportedConnectionTypes Array 1 客户端支持的连接类型列表。
advice Object 0..1 Session配置参数。
参数协商
名称 类型 次数 描述
timeout Integer 0..1 发送连接信息和服务器应答之间的最大毫秒数。本session中覆盖服务器缺省设置。缺省值: 3600000, 最大值: 7200000
interval Integer 0..1 如果没有从客户端收到下一个连接消息, 超出此时长服务器关闭session。覆盖本session中覆盖服务器缺省设置。缺省值: 10000

请求示例:

POST /cep/realtime
                      Host: ...
                      Authorization: Basic ...
                      Content-Length: ...
                      Content-Type: application/json
                      [
                      {
                      "channel": "/meta/handshake",
                      "version": "1.0",
                      "mininumVersion": "1.0beta",
                      "supportedConnectionTypes": ["long-polling","callback-polling"],
                      "advice":{"timeout":120000,"interval":30000}
                    }
                    ]
                  
应答
名称 类型 次数 描述
id Integer 1 请求消息中的消息Id
channel URI 1 通道名称, "/meta/handshake"中的值。
version String 0..1 服务器使用的Bayeux协议版本。
minimumVersion String 0..1 服务器需要的客户端最低Bayeux协议版本。
supportedConnectionTypes Array 0..1 客户端和服务器都支持的连接类型列表。(也就是, 客户端和服务器的交集)。
clientId String 0..1 服务器生成的客户端唯一ID。
successful Boolean 1 握手结果。
error String 0..1 握手失败原因。

成功应答示例:

HTTP/1.1 200 OK
                    Content-Type: application/json
                    [
                    {
                    "channel": "/meta/handshake",
                    "version": "1.0",
                    "minimumVersion": "1.0beta",
                    "supportedConnectionTypes": ["long-polling"],
                    "clientId": "Un1q31d3nt1f13r",
                    "successful": true
                  }
                  ]
                

失败应答示例:

HTTP/1.1 200 OK
                  Content-Type: application/json
                  [
                  {
                  "channel": "/meta/handshake",
                  "successful": false,
                  "error":"403::Handshake denied"
                }
                ]
              

订阅

通知客户端可以发送订阅消息, 指定通道接收QuarkIoE平台输出的消息。客户端将在后续的连接请求中接收到消息。

通道名称格式因REST api而不同。详情参见:

  • 实时语句
  • 设备控制
请求
名称 类型 次数 描述
id Integer 1 消息Id, 用于匹配应答消息。
channel String 1 通道名称, "/meta/subscribe"中的值。
clientId String 1 握手报文中收到的客户端唯一ID。
subscription String 1 要订阅的通道名称。

请求示例:

POST /cep/realtime
                Host: ...
                Authorization: Basic ...
                Content-Length: ...
                Content-Type: application/json
                [
                {
                "channel": "/meta/subscribe",
                "clientId": "Un1q31d3nt1f13r",
                "subscription": "/alarms/overHeatAlarms"
              }
              ]
            
应答
名称 类型 次数 描述
id Integer 1 请求消息的消息Id。
channel URI 1 通道名称, "/meta/subscribe"中的值。
clientId String 1 客户端唯一ID。
subscription String 1 通道名称。
successful Boolean 1 订阅结果。
error String 0..1 订阅失败原因。

应答示例:

HTTP/1.1 200 OK
              Content-Type: application/json
              [
              {
              "channel": "/meta/subscribe",
              "clientId": "Un1q31d3nt1f13r",
              "subscription": "/alarms/overHeatAlarms",
              "successful": true,
              "error": ""
            }
            ]
          

退订

在通道中停止接受消息, 发送消息到"/meta/unsubscribe", 需要提供和订阅时相同格式的通道名称。

请求
名称 类型 次数 描述
id Integer 1 消息Id, 用于匹配应答消息。
channel URI 1 通道名称, "/meta/unsubscribe"中的值。
clientId String 1 握手报文中收到的客户端唯一ID。
subscription String 1 通道名称。

请求示例:

POST /cep/realtime
            Host: ...
            Authorization: Basic ...
            Content-Length: ...
            Content-Type: application/json
            [
            {
            "channel": "/meta/unsubscribe",
            "clientId": "Un1q31d3nt1f13r",
            "subscription": "/CepModuleName/CepStatementName"
          }
          ]
        
应答
名称 类型 次数 描述
id Integer 1 请求消息的消息Id。
channel URI 1 通道名称, "/meta/unsubscribe"中的值。
clientId String 1 客户端唯一ID。
subscription String 1 订阅的通道名称。
successful Boolean 1 退订结果。
error String 0..1 退订失败原因。

应答示例:

HTTP/1.1 200 OK
          Content-Type: application/json
          [
          {
          "channel": "/meta/unsubscribe",
          "clientId": "Un1q31d3nt1f13r",
          "subscription": "/CepModuleName/CepStatementName",
          "successful": true,
          "error": ""
        }
        ]
      

连接

Bayeux客户端通过和服务器握手交换信息并订阅通道后, 向"/meta/connect"通道发送消息创建连接。每次收到应答后必须立即再次连接通道以取得下一个通知。

请求
名称 类型 次数 描述
id Integer 0..1 消息Id, 用于匹配应答消息
channel URI 1 通道名称, "/meta/connect"中的值。
clientId String 1 握手报文中收到的客户端唯一ID。
connectionType String 1 选中的连接类型。
advice Object 0..1 当前连接消息的配置参数。
参数协商
名称 类型 次数 描述
timeout Integer 0..1 发送连接信息和服务器应答之间的间隔时间。本请求应答会话中覆盖服务器缺省设置。
interval Integer 0..1 超出此时还没有收到客户端下一个连接消息, 服务器关闭session。本请求应答会话中覆盖服务器缺省设置。

请求示例:

POST /cep/realtime
                  Host: ...
                  Authorization: Basic ...
                  Content-Length: ...
                  Content-Type: application/json
                  [
                  {
                  "channel": "/meta/connect",
                  "clientId": "Un1q31d3nt1f13r",
                  "connectionType": "long-polling",
                  "advice":{"timeout":1200000,"interval":30000}
                }
                ]
              
应答
名称 类型 次数 描述
id Integer 0..1 请求消息中的消息Id。
channel URI 1 通道名称。
clientId String 1 客户端唯一ID。
successful Boolean 1 连接结果。
data Array 1 通道通知列表。
error String 0..1 连接错误原因。

应答示例:

HTTP/1.1 200 OK
                Content-Type: application/json
                [
                {
                "channel": "/cepModuleName/cepStatementName",
                "successful": true,
                "error": "",
                "data": [{
                "id" : "10",
                "self" : "...",
                "creationTime" : "2011-09-06T12:03:27.927+02:00",
                "type" : "com_cumulocity_model_DoorSensorEvent",
                "time" : "2011-09-06T12:03:27.845+02:00",
                "text" : "Door sensor was triggered.",
                "com_othercompany_Extension" : { ... },
                "source":{ "id":"12345", "self": "..." }
              }],
              "clientId": "Un1q31d3nt1f13r"
            },{
            "channel": "/cepModuleName/cepStatementName",
            "successful": true,
            "error": "",
            "data": [{
            "id" : "11",
            "self" : "...",
            "creationTime" : "2011-09-06T12:03:27.927+02:00",
            "type" : "com_cumulocity_model_DoorSensorEvent",
            "time" : "2011-09-06T12:03:27.845+02:00",
            "text" : "Door sensor was triggered.",
            "com_othercompany_Extension" : { ... },
            "source":{ "id":"12345", "self": "..." }
          }],
          "clientId": "Un1q31d3nt1f13r"
          },
          {
            "channel":"/meta/connect",
            "successful":true
          }
          ]
          

断开连接

向"/meta/disconnect"通道发送消息, 从所有通道停止接收通知并关闭会话。

请求
名称 类型 次数 描述
id Integer 0..1 消息Id, 用于匹配应答消息
channel URI 1 通道名称, "/meta/disconnect"中的值。
clientId String 1 握手报文中收到的客户端唯一ID。

应答示例:

POST /cep/realtime
            Host: ...
            Authorization: Basic ...
            Content-Length: ...
            Content-Type: application/json
            [
            {
            "channel": "/meta/disconnect",
            "clientId": "Un1q31d3nt1f13r",
          }
          ]
          
应答
名称 类型 次数 描述
id Integer 0..1 请求消息中的消息Id。
channel URI 1 通道名称, "/meta/disconnect"中的值。
successful Boolean 1 断开连接操作结果。
clientId String 1 握手报文中收到的客户端唯一ID。
error String 0..1 断开连接错误原因。

应答示例:

HTTP/1.1 200 OK
            Content-Type: application/json
            [
            {
            "channel": "/meta/disconnect",
            "clientId": "Un1q31d3nt1f13r",
            "successful": true
          }
          ]
          

网络流量

通过长连接监听通知根据超时的不同会产生一定的流量。下表列出了1小时超时并且请求之间无间隔产生的流量。数值不包括通知本身和session重连的流量。

周期 流量
7 kB
50 kB
210 kB

握手或连接时, 客户端可以覆盖缺省的服务器连接设置, 如超时和间隔。长连接情况下, 客户端可以通过传送超时时间改变请求时长。超时时间越长发送请求和应答产生的流量越少, 但更可能导致连接丢失。客户端还可以设置更长的间隔值,并等待接收到最后一个响应之后发送下一个连接消息(代价是较低的交互性)。