# 接口说明

本接口为您提供了通过 HTTP 的方式上传动态实体资源,您可以通过本接口上传资源,并在 Android、iOS、Windows、Linux、WebAPI 应用中生效使用。

动态实体的使用分两步,上传资源,资源生效。本接口只提供上传资源,Android、iOS、Windows、Linux 请通过CMD_SET_PARAMS设置pers_param使之生效,具体方法请参阅动态实体,webapi 应用请传pers_param参数。

除了使用本接口上传动态实体,Android、iOS、Windows、Linux SDK 中同时提供函数接口直接上传,WebAPI 类应用需要使用 V2 版本协议动态实体方可生效。

# API说明

  • 授权认证,调用接口需要将nameSpace,nonce,curtime和checkSum信息放在HTTP请求头中。
  • 所有接口统一为UTF-8编码。
  • 所有接口支持http和https。

# Sample

Github (opens new window)

# 授权认证

AccountKey 为账户级Key,每个AIUI 账户具有一个AccountKey,在「技能工作室-我的实体-动态实体密钥」中即可查看。

在调用所有业务接口时,都需要在Http Request Header中加入以下参数作为授权验证

参数名 说明 是否必须
X-NameSpace aiui开放平台的命名空间
X-Nonce 随机数(最大长度128个字符)
X-CurTime 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数(String)
X-CheckSum MD5(accountKey + Nonce + CurTime),三个参数拼接的字符串,进行MD5哈希计算

注:

  • CheckSum有效期:出于安全性考虑,每个CheckSum的有效期为5分钟(用curTime计算),同时CurTime要与标准时间同步,否则,时间相差太大,服务端会直接认为CurTime无效。

  • checkSum生成示例,例如:

accountKey是abcd1234, Nonce是12, CurTime是1502607694。那么CheckSum为MD5(abcd1234121502607694)
最终MD5为32位小写 bf5aa1f53bd173cf7413bf370ad4bddc

# IP 白名单

IP 白名单具备打开和关闭两种状态。

  • 当 IP 白名单打开时,用户在调用所有业务接口时,在授权认证通过后,检查调用方ip是否在aiui开放平台配置的ip白名单中。若在,则向用户提供服务,否则拒绝提供服务。

  • 当 IP 白名单关闭时,任意终端均可访问 AIUI 服务器,开发者需要自行保证 nameSpace 和 key 值安全。

注:拒绝提供服务返回值:{"code":"20004","desc":"ip非法","data":null,"sid":"rwabb52e660@dx6c9b0e56f81d3ef000"}

# 通用请求地址

base_url:openapi.xfyun.cn

# AIUI接口

通用返回参数

参数名 说明 是否必须
code 结果码
data 返回结果
desc 描述
sid 本次webapi服务唯一标识

# 动态实体

# 上传资源

  • 接口描述

    本接口提供动态实体上传资源功能,用于动态更新实体资源。

  • 接口地址

    POST /v2/aiui/entity/upload-resource HTTP/1.1

    Content-Type:application/x-www-form-urlencoded; charset=utf-8

  • 参数说明

参数 类型 必须 说明
示例
appid string 应用id 5adde3cf
res_name String 资源名,XXX为用户的命名空间 XXX.music
pers_param String 个性化参数(json) {"appid":"xxxxxx"}
data String Base64编码的资源 示例1

其中,pers_param为个性化参数。示例如下:

维度 示例 说明
应用级 {"appid":"xxxxxx"}
用户级 {"auth_id":"d3b6d50a9f8194b623b5e2d4e298c9d6"} auth_id为用户唯一ID(32位字符串,包括英文小写字母与数字,开发者需保证该值与终端用户一一对应)
自定义级 {"xxxxxx":"xxxxxx"}

data为web页面定义的主子段、从字段给的json格式对应的base64。例如,主子段为song、从字段singer,上传资源的格式为:

{"song":"给我一首歌的时间","singer":"周杰伦"}
{"song":"忘情水","singer":"刘德华"}
{"song":"暗香","singer":"刘德华"}
{"song":"逆光","singer":"梁静茹"}

注:每条数据之间用换行符隔开。

Base64编码为

示例1:

eyJzb25nIjoi57uZ5oiR5LiA6aaW5q2M55qE5pe26Ze0Iiwic2luZ2VyIjoi5ZGo5p2w5LymIn0NCnsic29uZyI6IuW/mOaDheawtCIsInNpbmdlciI6IuWImOW+t+WNjiJ9DQp7InNvbmciOiLmmpfpppkiLCJzaW5nZXIiOiLliJjlvrfljY4ifQ0KeyJzb25nIjoi6YCG5YWJIiwic2luZ2VyIjoi5qKB6Z2Z6Iy5In0=
  • 返回说明
参数 类型 必须 说明 示例
sid String 本次上传sid,可用于查看上传资源是否成功 psn003478f3@ch00070e3a78e06f2601
csid String 本次服务唯一标识 rwa84b7a73b@ch372d0e3a78e0116200

# 查看上传资源是否成功

  • 接口描述

    本接口提供检查动态实体上传资源是否成功。

注意

上传资源数据后至少间隔10秒后再进行查看上传资源是否成功。

  • 接口地址

    POST /v2/aiui/entity/check-resource HTTP/1.1

    Content-Type:application/x-www-form-urlencoded; charset=utf-8

  • 参数说明

参数 类型 必须 说明 示例
sid string sid psn开头的sid
  • 返回说明
参数 类型 必须 说明
sid String 上传sid
csid String 上传sid
reply String 查看上传资源是否成功描述
error int 查看上传资源是否成功错误码