跳到主要内容

会话协议

连接 websocket 之后，需要创建会话（session），在会话中与情感云计算平台进行数据交互。针对会话的操作如下：

服务操作备注
sessioncreate认证并创建会话
restore恢复会话
close结束会话

创建并认证会话（Session Create & Authentication)​

创建并认证会话。

[!WARNING] 请求所有情感云计算的服务必须先进行会话认证。

认证并创建对话的 Request​

{
    "services": "session",
    "op": "create",
    "kwargs": {
        "app_key": app_key, # 云后台生成的APP Key
        "user_id": userid,    # 会话关联的唯一用户 id 的 md5 哈希值
        "timestamp": timestamp,  # 实时时间戳
        "sign": sign,   # 详见sign步骤
        "upload_cycle": upload_cycle  # 上传周期倍数(见表)
    }
}

上传周期倍数（upload_cycle）​

在 V2 及以上版本的接口中，支持客户端按照不同倍数的上传周期上传数据。用户可以根据需求，通过设置 upload_cycle 参数来设置上传周期。设置上传周期可以有效的降低资源消耗，以及节省接口使用费用。在不同的上传周期倍数下，客户端每次上传的数据包帧数也不同，与情感云服务器的上传数据包和接收计算结果包的时间间隔也将随着倍数增大而延长，具体参数参考方内容。

提示
  • V1 版本接口不需要设置此参数
  • V1 版本接口自 2020 年 8月 25 日起不对新用户开放（老用户可以继续使用，但推荐及时升级到新接口，可以享受更低的接口使用费用）
  • 上传周期倍数可以是 3 ~ 100 之间的任意整数（需要 3 以下的倍数，请联系客服）
  • 情感云配套硬件不同模块的周期说明
    • 脑电
      • 情感云配套硬件的理论发包间隔为每个包间隔 0.012 秒（每个包长 20 个字节）
      • 上传周期 1 倍，客户端需要从硬件接收 50 个包；每增加一个倍数包数增加 50 个包
      • 上传周期 1 倍，客户端从硬件接收第 1 个包到第 50 个包的理论时间间隔 0.6 秒（0.012 * 50），周期每增加 1 倍，时间间隔延长 0.6 秒
      • 如：设置 3 倍的上传周期，客户端需要从硬件接收到 50 3 = 150 个包（理论时间间隔为 0.6 3 = 1.8 秒）后才向服务端上传数据；服务端处理完成即返回有效数据
    • 心电
      • 情感云配套硬件的理论发包间隔为每个包间隔 0.2 秒（每个包长 1 个字节）
      • 上传周期 1 倍，客户端需要从硬件接收 3 个包；每增加一个倍数包数增加 3 个包
      • 上传周期 1 倍，客户端从硬件接收第 1 个包到第 3 个包的理论时间间隔 0.6 秒（0.2 * 3），周期每增加 1 倍，时间间隔延长 0.6 秒
      • 如：设置 3 倍的上传周期，客户端需要从硬件接收到 3 3 = 9 个包（理论时间间隔为 0.6 3 = 1.8 秒）后才向服务端上传数据；服务端处理完

上传周期倍数参考表

倍数累积 EEG 包个数累积 HR 包个数理论周期时长（秒）备注
0302EEG: 0.36 ; HR: 0.40 倍只允许使用 v1 版本接口的老用户使用
15030.6
315091.8默认倍数；想使用更小倍数请联系客服
10500306

sign 步骤​

  • 从后台获取 app_secret。
  • 将待签名字符串要求按照参数名进行排序；(首先比较所有参数名的第一个字母，按abcd顺序排列，若遇到相同首字母，则看第二个字母，以此类推)
  • 将排好序后的参数拼接成字符串；
  • 然后对拼接好后的字符串做 md5；
  • md5 后的值全部转为大写。

例如：对于如下的参数进行签名：

app_key = "c821db84-6fbd-11e4-a9e3-c86000d36d7c",
app_secret = "b1a071f0d3f119de465a6d8c9a8c0e7f",
timestamp = 1566971668,  # 实时时间戳
user_id = "098f6bcd4621d373cade4e832627b4f6"

sign_str = "app_key={}&app_secret={}&timestamp={}&user_id={}".format(
    app_key, app_secret, timestamp, user_id
) # 将待签名字符串要求按照参数名进行排序(首先比较所有参数名的第一个字母，按 abcd 顺序排列，若遇到相同首字母，则看第二个字母，以此类推)

sign = hashlib.md5(sign_str).hexdigest().upper()  # sign 即为签名值（需全大写）

user_id​

user_id 为开发者 app 内的唯一用户 id 经过 md5 哈希之后的值。user_id 可用于定位会话用户归属，可用于后期数据关联查询和错误追踪。

提示
  • App 内的唯一用户 id 可为手机号、邮箱、用户 id、账户名等，但需要保证唯一性。
  • 我们保存的仅为 md5 之后的值，不会知道 app 内用户的原始 id。
  • 用户上传的 user_id 必须为 md5 值，且通过验证接口上传的 timestamp 和 user_id 必须和参与签名的完全一致。

认证并创建对话的 Response​

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "start"
    },
    "data": {
        "session_id": session_id    # 会话 ID，每次 Start 连接会生成唯一 ID, 可以用来做会话恢复
    }
}

恢复会话（Session Restore）​

恢复会话。会话因为网络条件不好而中断，可以选择恢复。

提示
  • 会话保留时间为 10 分钟，10 分钟内可以根据 session_id 来恢复会话，超过 10 分钟会话将会被销毁。
  • 测试应用的保留时间为 2 分钟。

恢复会话的 Request​

{
    "services": "session",
    "op": "restore",
    "kwargs": {
        "app_key": app_key, # 云后台生成的 APP Key
        "session_id": session_id,    # 会话 ID，由 Session Start 生成
        "user_id": userid,    # 会话关联的唯一用户 id 的 md5 哈希值
        "timestamp": timestamp,  # 实时时间戳
        "sign": sign,   # 详见 sign 步骤
        "upload_cycle": upload_cycle  # 上传周期倍数(见表)
    }
}

恢复会话的 Response​

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "restore"
    }
}

结束会话（Session Close）​

结束会话。

警告

会话结束后一定要调用 session close，不然服务端仍然会保留会话，并产生费用。

结束会话的 Request​

{
    "services": "session",
    "op": "close"
}

结束会话的 Response​

{
    "code": 0,
    "request": {
        "services": "session",
        "op": "close"
    }
}