概述

智能设备分析目前支持智能设备通过WebAPI接口上传数据至开放统计云端,并对数据进行处理、分析和展示。

开发者通过以下接入指南,首先需要获取令牌,取得服务权限,然后通过数据上传服务接口将数据上传到云端保存分析。

获取token服务的域名:openapi.openspeech.cn

数据上传服务的域名:scsdev.openspeech.cn

以下对获取令牌、数据上传接口进行介绍,并以python代码进行了调用示例,python版本为2.7.5(Python版本不是向后兼容的,请确保你下载的版本是python2.7)。

获取令牌

1.  接口描述

调用接口获取所需要的服务令牌。

2.  请求消息

    GET /index.htm?svc=token HTTP/1.0
    Host: openapi.openspeech.cn
    X-Par: aW1laT0xMTExJmltc2k9MTExMSZtYWM9MTExMSZhcHBpZD0xMTEx

除了HTTP 1.0规范自带的各种字段外,WebAPI支持扩展请求头:X-Par

(1)X-Par的说明:

X-Par X-Par扩展请求头是带appid的base64编码 ,编码格式如mac=12:a2:45:14:23&appid=1234abc。其中appid可在讯飞开放统计上申请。

(2)X-Par支持的参数列表:

字段 说明
mac mac地址
appid 设备appid,用于标识设备

3.  响应消息

    HTTP/1.1 200 OK
    Content-Type: text
    Content-Length: 10
    \r\n
    \r\n
    exxzaWQdOnh4eHgsHXRvY2tlbh06HTEyMzQ1NjcdLB1leHBpcmVzHTo3MjAwLB1yZXQdOjB9

(1)http状态码:

http状态码 说明
200 操作执行成功
298 部分操作执行成功
400 请求报文格式错误
401 认证授权失败,可能是密钥信息不正确、数字签名错误或授权已超时
404 资源不存在
405 请求方式错误,非预期的请求方式
406 上传的数据 CRC32 校验错
419 用户账号被冻结
503 服务端不可用
504 服务端操作超时

(2)经过base64解码后结果:

    {
        "sid": "xxxx",
        "token": "1234567",
        "expires": 7200,
        "ret": 0
    }

(3)参数说明:

字段 取值 描述
sid 32位字符串 本次服务唯一标识
token 字符串 服务令牌,失效之后需重新获取
ret 错误码 0表示成功
expires 令牌有效时间 单位:秒

4.  代码示例

(1)代码:

    # -*- coding: utf-8 -*- #文本编码为utf-8
    import base64
    import httplib

    xpar="mac=12:a2:45:14:23&appid=1234abc"     #假设你申请到的appid为:1234abc
    xpar_encode=base64.encodestring(xpar)            #对xpar字符串用标准base64进行编码
    print xpar_encode                                                #打印出X-Par供转写等服务使用
    requrl = "/index.html?svc=token"                       #请求url
    header = {"X-Par":xpar_encode}                         #消息头

    conn = httplib.HTTPConnection("openapi.openspeech.cn")             #连接服务主机
    conn.request(method="GET",url=requrl,headers = header)             #发送请求
    response = conn.getresponse()                                       		      #得到响应
    print base64.b64decode(response.read())                                       #对响应字符串base64解码并打印

(2)响应:

    base64解码前数据:
    eyJleHBpcmVzIjo3MjAwLCJyZXQiOjAsInRva2VuIjoiNDc4MzdhZmU0OWY3Yjg1NDcyZDM5NjkwZTg0ZGQ
zZDQiLCJzaWQiOiJ3YnM0ZDBjNmYwY0BjaDAzOTMwOGMxYTlkMDQ3MGUwMSJ9 base64解码后数据: { "expires": 7200, "ret": 0, "token": "77e0acbb6e5b73fd226eb12a9d4eb4a7", "sid": "wbs2f0881bb@ch035e06fc86ef470e01" }

数据上传服务

1.  接口描述

开发者调用此接口将智能硬件数据上传保存到云端maple集群中、云端再对上传数据进行分析并在页面展示。

2.  请求消息体

    POST /scs?cmd=develop&token=&enc=0&gzip=0 HTTP/1.1
    Accept-Encoding: identity
    Content-Length: 70
    Host: scs.openspeech.cn

    ~'duula'?'=<300667')'uwjapfqla'?'3101313113')'hdf'?'16?d`?16?6d?61'x..'			

3.  消息体参数说明

(1)url中携带的参数说明:

字段 取值 是否必传 描述
cmd String 该字段目前取值为develop
enc String 是否压缩的标识,enc=0则携带的数据不压缩
gzip gzip Int(0/1) 否(nc=0时不携带,其他情况必须要携带) 压缩方法,gzip=0采用zlib压缩,不携带或者gzip=1则表示采用gzip压缩
token Int 服务令牌失效后需要重新获取

(2)body中携带数据说明:

body中携带未加密压缩前的数据为json格式,上传前需要进行0x05异或加密,如果url参数中未携带enc=0则需要对body进行压缩,压缩方式可采用zlib或者gzip。

Body中json数据格式如下(加密压缩前的数据)

    {
        "appid":"89655332",
        "productid":"6454646446", 
        "mac":"43:ae:43:3a:34", 
        "extinfo": {
            "event":[{
                "eventid":"value11",
                "eventlabel":"value12",
                "durationtime":timestamp1,
                "starttime":timestamp2,
                "endtime":timestamp3,
                },
                {
                "eventid":"value21",               
                "eventlabel":"value22",
                "durationtime":timestamp1,
                "starttime":timestamp2,
                "endtime":timestamp3,
                }]
            "key1":"value1",
            "key2":"value2",
        }
    }
字段 取值 是否必传 描述
appid String 设备 appid,用于标识设备
productid String 同appid,便于日后扩展
mac String 智能硬件mac地址
extinfo Json Object 客户端自定义扩展字段(目前暂时不支持分析)

4.  调用返回

(1)返回结果:

    {
        "rsp":{"code":0,"des":"upload success"}
    }		

上传数据是否成功是以其中的code为准,0则上传成功,不为0的表示失败;如果出现下面中的错误码,请开发者根据下面的错误码提示修改相关代码后重试,出现其他错误码请重新上传数据。

(2)错误码说明:

错误码 对应的宏 说明
10106 MSP_ERROR_INVALID_PARA url中cmd不合法
10304 MSP_ERROR_MSG_CONTENT_EMPTY 携带上来的body为空
10117 MSP_ERROR_NO_ENOUGH_BUFFER 单个文件大于4M
10407 MSP_ERROR_DB_INVALID_APPID 携带数据中productid没有携带或者不合法
10109 MSP_ERROR_INVALID_DATA 携带的数据格式不合法 可能是没有异或加密,还有可能Json格式不合法
11201 MSP_ERROR_AUTH_NO_ENOUGH_LICENSE 授权不足,智能设备分析服务现处于内测阶段,如需开通,请 联系我们

常见问题

1. Python示例代码的消息头中均无参数"Content-Length:",是不是这个参数不必要?

不是,这个参数是必要的,只是python解释器会给Post请求自动增加这个参数。

2. 为什么调用API返回都是http 200?

云端只要收到请求都会返回http200,数据上传是否成功需要根据返回消息体中的具体错误码来判断。

Python2.7示例代码

    #coding=utf-8
    import socket
    import httplib
    import gzip
    import zlib
    import json
    import StringIO
    def post_scslog(host,server_url,benc,bzlib):
        body = """{"appid":"89655332","productid":"demo_test","mac":"43:ae:43:3a:51"}"""
        heads = {"Host":"scsdvc.openspeech.cn"}
        try:
            post_data = body
            if (benc!="enc"):                       #判断是否需要压缩
                if bzlib == "zlib":                 #zlib压缩
                    post_data=zlib.compress(body)
                else:                                     #gzlib压缩
                    zbuf = StringIO.StringIO()
                    zfile = gzip.GzipFile(mode='wb', compresslevel=9, fileobj=zbuf)
                    zfile.write(body)
                    zfile.close()
                    post_data=str(zbuf.getvalue())
            in_dt = []
            for x in post_data:
                in_dt.append(chr(ord(x)^0x05))
            in_dtate= ''.join(in_dt)
            socket.setdefaulttimeout(30)
            conn = httplib.HTTPConnection(host)               #连接服务主机
            print
            conn.request('POST',server_url,in_dtate,heads)
            response = conn.getresponse()
            code = response.status
            if code==200:
                msg = response.reason
                result = response.read()
                json_data = json.loads(result)
                print json_data
            else:
                print "http error:" + str(code)
        except Exception as e:
                print str(e)    
        return 0, ''
    def main():
          post_scslog(r'scsdev.openspeech.cn','/scs?cmd=mscmini&token=1234565456&gzip=0&enc=0','enc','zlib')  
          #token是通过获取令牌服务获取到的
    if __name__ == '__main__':
        print __name__
        main()