AliGenie开发者平台
动态内容API方式接入
一、登录阿里百川无线开放平台，创建应用，获得appKey
登录淘宝开放平台后，创建应用，选择‘百川无线应用’，获得appKey。
创建成功后，登录淘宝开放平台，点击已创建应用的‘应用管理’按钮，在页面内的‘功能场景’栏中申请‘天猫精灵内容库API’权限(如未发现此API权限，请联系对接人员线下申请)。
二、登录AliGenie开发者平台，创建技能
创建技能链接：https://open.bot.tmall.com/console/skill/list
选择技能类型为“内容”，选择相应技能模板，并填写好其他信息。点击下一步，并在“API接入”信息填写界面按要求补充信息：
待填写信息包括：
1. 第一步淘宝开放平台所创建应用的appKey，必填，可修改；
2. 接入方自定义身份标识ID（数字字母下划线），必填项，值唯一，不可修改；
3. 接入方名称，必填项，不可修改；
4. 播放链接查询回调接口，非必填（如需要通过回调查询播放链接，请参考下述播放链接回调说明）；
填写完成后保存。
三、按照API文档接入系统
等待步骤一中权限申请审核通过，即可通过淘宝开放平台“应用管理-SDK下载-服务端SDK”页面下载SDK包进行接口开发。
按照 类目-专辑-音频 的结构关系，设计如下接口。其中类目信息需要三方平台自行对应到‘AliGenie开发者平台’中已有的类目信息（如需新增类目需要提交审核），专辑和音频结构信息由三方平台自行组织好后传入。
API入参字段说明
详见淘宝开放平台天猫精灵内容库API接口调用说明。
其中关于extend_info字段的填写说明如下所示。
extendInfo作为扩展字段，为JSON格式，详细字段信息如下:
一、 版权相关信息，请在extendInfo中填写limitRegion字段
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| limitRegion | String | 否 | 限制播放区域 | 美国 |
| expiryTime | Long | 否 | 过期时间，unix时间戳形式，为从1970年1月1日到指定时间经历的秒数，单位秒 | 1515758372 |
| canDistribute | boolean | 否 | 是否允许二次分发，即是否允许外发给其他平台使用 | 是 |
| limitDevice | String | 否 | 限制播放的终端类型，例如内容只限制在手机端播放 | 故事 |
二、 内容分级
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| contentRate | String | 否 | 内容分级，暂填内容适合人群的年龄段信息 | 0-18 |
三、 extendInfo作为各个不同类型内容输入的扩展字段，根据不同的内容类型输入字段有所不同：
- 新闻类型：
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| region | String | 否 | 新闻所属地域 | 杭州 |
| content | String | 否 | 新闻内容，文字版内容，长度300 | 文本内容 |
| sub_source | String | 否 | 新闻子来源 | 新华社 |
| is_tts | Boolean | 是 | 是否是TTS转换的音频 | false |
- 儿童内容类型：
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| applyAgeStart | int | 类目选择为‘儿歌’、‘故事’、‘百科’、‘课文（教辅）’、‘英语’、‘育儿知识’时必填 | 开始年龄 | 1 |
| applyAgeEnd | int | 类目选择为‘儿歌’、‘故事’、‘百科’、‘课文（教辅）’、‘英语’、‘育儿知识’时必填 | 结束年龄 | 12 |
| applyAgeGroup | long | 类目选择为‘儿歌’、‘故事’、‘百科’、‘课文（教辅）’、‘英语’、‘育儿知识’时必填 | 年龄层，及年龄单位，目前支持‘岁’、‘月’两种 | 岁 |
- AR绘本内容：
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| ar_pic | JSONArray | 是 | AR图片信息 | [ { “cdnUrl”: “http://example.com/arpic/a.jpg", ”position“: ”left“, ”pageNum“: 1 }, { ”cdnUrl“: ”http://example.com/arpic/b.jpg“, ”position“: ”right“, ”pageNum": 1 } ] |
| has_sublicense | boolean | 是 | 是否可转授权 | true |
| no_sublicense_url | String | 否 | 无转授权时的播放链接 | alipays://platformapi/startapp?appId=20000067| |
其中cdnUrl为AR绘本图片地址链接，position标明是绘本的左页或者右页，pageNum表示绘本的页数。
API响应字段说明
成功响应:
| 字段名称 | 类型 | 说明 | 示例 |
|---|---|---|---|
| ret_code | int | 状态码(200正常，其他，其他异常) | 200 |
| ret_msg | String | 状态码说明 | success |
失败响应:
| 字段名称 | 类型 | 说明 | 示例 |
|---|---|---|---|
| code | int | 平台错误码 | 15 |
| msg | String | 平台错误信息 | Remote service error |
| sub_code | int | 具体业务返回错误码 | 400 |
| sub_msg | String | 具体业务返回错误信息 | openContents[0].playUrls[0].type must match “audio|video” |
附1：播放链接回调说明：
播放链接查询回调接口是在内容方不提供固定的播放地址，需要实时获取播放地址的情况下需要填写的，由用户选填。调用该接口时将会使用平台私钥对请求进行签名，接入方需要使用平台公钥对签名进行验证。
播放链接查询回调接口需接收以下请求参数：
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| sourceId | string | 是 | 三方平台在AliGenie开放平台登记的sourceId | test_source |
| albumId | string | 存在此字段时必填 | 节目在三方平台的原始专辑id(此值是通过内容推送接口推送至开放平台) | 10 |
| contentId | string | 是 | 节目在三方平台的原始id(此值是通过内容推送接口推送至开放平台) | 1001 |
| requestTime | long | 是 | 请求时间戳，unix时间戳，单位毫秒 | 1546852336 |
| randomId | int | 是 | 请求随机数 | 21121 |
| signature | string | 是 | 签名信息 | signature |
播放链接查询接口应当返回包含播放链接信息的List类型，数据格式如下：
| 字段名称 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
| bitrate | int | 是 | 音频码率 | 128 |
| type | String | 是 | 音视频类型 | audio/video |
| expire | int | 是 | 播放链接在多长时间内有效，如每次播放都需实时查询，请填写-1，单位：秒 | 100 |
| url | url | 是 | 音频可播放链接 | http://example.fm/favoursong.mp3 |
组合字符串sourceId + albumId(若存在) + contentId + requestTime + randomId，开放平台将对该字符串使用平台私钥进行SHA1withRSA签名加密，对加密结果进行Base64编码得到签名字段signature连同其它参数一同传递给接入方。服务端收到请求后，请使用开放平台提供的公钥对签名进行验证。（为了防止重复请求攻击，服务端可对请求参数requestTime及randomId进行识别，当收到的requestTime值比上一个小10秒则认为非法，其次每个请求的requestTime与randomId拼接后的字符串必须是唯一的）
签名验证代码示例(Java)
Signature mySig = Signature.getInstance("SHA1withRSA");
String pbkeyStr = "";
X509EncodedKeySpec keySpec = new X509EncodedKeySpec(Base64.getDecoder().decode(pbkeyStr));
PublicKey pb = f.generatePublic(keySpec);
mySig.initVerify(pb);
mySig.update(parametersStr.getBytes("UTF-8"));
if(mySig.verify(Base64.getDecoder().decode(signature))){
//TODO
}
附2：类目名称及ID对应关系
- 新闻类目
| 新闻类目 | 对应Id |
|---|---|
| 国际 | 80010001 |
| 国内 | 80010002 |
| 军事 | 80010003 |
| 社会 | 80010004 |
| 体育 | 80010005 |
| 娱乐 | 80010006 |
| 财经 | 80010007 |
| 科技 | 80010008 |
| 汽车 | 80010009 |
| 房产 | 80010010 |
| 时尚 | 80010011 |
| 生活 | 80010012 |
| 旅游 | 80010013 |
| 游戏 | 80010014 |
| 人文 | 80010015 |
| 城市本地 | 80010016 |
| 搞笑 | 80010017 |
- 儿童
| 儿童类目 | 对应Id |
|---|---|
| 儿歌 | 80011001 |
| 童谣 | 80011002 |
| 国学 | 80011003 |
| 故事 | 80011004 |
| 百科 | 80011005 |
| 古诗 | 80011006 |
| 宋词 | 80011007 |
| 课文（教辅） | 80011008 |
| 英语 | 80011009 |
| 育儿知识 | 80011010 |
- 绘本
| 绘本类目 | 对应Id |
|---|---|
| 精选绘本 | 80020001 |
| 英语学习 | 80020002 |
| 历史故事 | 80020003 |
| 科技介绍 | 80020004 |
| 组词卡片 | 80020005 |
- 娱乐
| 娱乐类目 | 对应Id |
|---|---|
| 游戏动漫 | 80018001 |
| 体育 | 80018002 |
| 影视 | 80018003 |
| 星座 | 80018004 |
| 综艺 | 80018005 |
| 二次元 | 80018006 |
| 笑话 | 80018008 |
| 儿童笑话 | 80018009 |
- 有声书
| 有声书类目 | 对应Id |
|---|---|
| 人物传记 | 80012001 |
| 佛教 | 80012002 |
| 军事 | 80012003 |
| 历史 | 80012004 |
| 古风言情 | 80012005 |
| 官场 | 80012006 |
| 恐怖惊悚 | 80012007 |
| 悬疑灵异 | 80012008 |
| 推理刑侦 | 80012009 |
| 文学名著 | 80012010 |
| 武侠仙侠 | 80012011 |
| 玄幻 | 80012012 |
| 现代言情 | 80012013 |
| 社科经管 | 80012014 |
| 穿越 | 80012015 |
| 评书 | 80012016 |
| 都市现代 | 80012017 |
| 青春校园 | 80012018 |
| 非书籍 | 80012019 |
| 玄幻奇幻 | 80012020 |
| 科幻 | 80012021 |
| 游戏竞技 | 80012022 |
| 广播剧 | 80012023 |
| 其他 | 80012024 |
| 鬼故事 | 80012025 |
- 音乐
| 音乐类目 | 对应Id |
|---|---|
| 音乐 | 80021001 |
