2018-07-13

车主电台接口文档

1、公共参数

1.1、客户端接入API公共参数

字段名	类型	必填	描述
app_key	String	是	喜马拉雅开放平台应用公钥
device_id	String	是	设备唯一标识，比如Android系统可以传imei，也可以传设备MAC地址。 如果公司有用户隐私政策考虑可以用MD5(真实设备号)取代。 但禁止伪造，否则会被检测出来并封号！
client_os_type	Int	是	客户端操作系统类型，1-iOS系统，2-Android系统，3-Web，4-Linux系统，5-ecos系统，6-qnix系统
pack_id	String	否	客户端包名，如果client_os_type为1或2时必填。对Android客户端是包名，对IOS客户端是Bundle ID
access_token	String	是	OAuth2访问令牌
sig	String	是	参数签名，对除sig外所有参数进行签名计算得到的值。每次请求都要重新生成，不可复用。签名生成算法见3.3。

1.2、服务端接入API公共参数

公共参数如下：

字段名	类型	必填	描述
app_key	String	是	喜马拉雅开放平台应用公钥
client_os_type	Int	是	固定值4，表示是服务端API接入
nonce	String	是	一个随机字符串，随机性越大越好，每个请求都需要重新生成
timestamp	Long	是	当前Unix毫秒数时间戳，每个请求都需要重新生成
sig	String	是	签名参数，对除sig外所有参数进行签名计算得到的值。每次请求都要重新生成，不可复用。签名生成算法见3.3

2、签名生成算法

签名计算建议在服务端完成

API接入时签名参数sig生成步骤：

1. 将除了sig以外的所有请求参数的原始值（即不做任何处理的参数值，比如不能进行URL编码）按照参数名的字典序排序

2. 将排序后的参数键值对用&拼接，即拼接成key1=val1&key2=val2&...

3. 将步骤2得到的字符串进行Base64编码（注意Base64编码时要设置字符集为utf8），假设Base64编码后的字符串为base64EncodedStr

4. 准备下一步需要的HMAC-SHA1哈希key，使用app_secret拼上serverAuthenticateStaticKey作为哈希key，假设得到的HMAC-SHA1哈希key是sha1Key

5. 使用sha1Key对base64EncodedStr进行HMAC-SHA1哈希得到字节数组（注意是字节数组，不要转成十六进制字符串，否则签名计算会出错；一般的HMAC-SHA1算法得到的结果是字节数组的十六进制表示，请务必留意这里和一般情况不太一样），用伪代码表示即

   sha1ResultBytes = hmac-sha1(base64EncodedStr, sha1Key)
   

6. 对上面得到的sha1ResultBytes进行MD5得到32位字符串，即为sig

3、接口说明

3.1、获取车主电台频道列表

3.1.1、/one_click_listen/channels

接口域名前缀

https://api.ximalaya.com

功能

获取车主电台频道列表

HTTP Method

GET

限制

支持客户端和服务端调用

参数

除公共参数外，还需要以下参数

参数名	类型	必填	描述
device_id	String	是	设备唯一标识，如果公共参数已经传了，此处可以不用重复传

返回值

返回为频道列表，其中每个频道包含以下字段：

参数名	类型	描述
channel_id	Int	车主电台频道Id
channel_name	String	车主电台频道名称
cover_url	String	车主电台频道封面
order_num	int	频道列表排序值，值越小越靠前

3.2、获取当前频道的下一条声音

3.1.2、/one_click_listen/get_next_track

接口域名前缀

https://api.ximalaya.com

功能

获取当前频道的下一条声音；

HTTP Method

GET

限制

支持客户端和服务端调用

参数

除公共参数外，还需要以下参数

参数名	类型	必填	描述
device_id	String	是	设备唯一标识，如果公共参数已经传了，此处可以不用重复传
channel_id	Int	是	车主电台频道id
pre_track_id	Long	否	当前频道上次收听的声音id，如果是首次进入可不填
pre_track_played_seconds	int	否	当前频道上次收听声音已播放的时长（单位秒），首次进入可不填

返回值

返回声音列表（内部只有一条待播放声音返回）

字段名	类型	描述
tracks	JSON Array	声音列表，每条声音的字段请参考Track

Track

字段名	类型	描述
id	Int	声音ID
kind	String	固定值"track"
track_title	String	声音标题
order_num	Int	声音在专辑中的排序值，从0开始依次递增，值越小排序越前
track_tags	String	声音标签列表，包含运营标签和主播个人打的标签，标签之间以英文逗号分隔
track_intro	String	声音简介
cover_url_small	String	声音封面小图url，尺寸为60x60（像素）
cover_url_middle	String	声音封面中图url，尺寸为180x180（像素）
cover_url_large	String	声音封面大图url，尺寸为640x640（像素）
announcer	JSON Object	声音所属主播，包含的字段请参考 Announcer
duration	Int	声音时长，单位秒
play_count	Int	声音被播放总次数
favorite_count	Int	声音被点赞总次数
comment_count	Int	声音被评论总次数
play_url_24_m4a	String	24位码率m4a格式音频播放地址
play_size_24_m4a	Int	24位码率m4a格式音频文件大小，单位字节
play_url_64_m4a	String	64位码率m4a格式音频播放地址
play_size_64_m4a	Int	64位码率m4a格式音频文件大小，单位字节
play_url_amr	String	amr格式音频播放地址，不保证该字段一定有值
play_size_amr	Int	amr格式音频文件大小，单位字节，如果play_url_amr值为""则该字段值为0
can_download	Bool	能否被下载到用户终端本地，禁止下载/缓存到服务器端
download_url	String	音频下载地址，m4a格式
download_size	Int	音频下载文件大小，单位字节
subordinated_album	JSON Object	声音所属专辑，包含的字段请参考 SubordinatedAlbum
source	Int	声音来源，1-用户原创，2-转采自其它专辑
updated_at	Int	声音更新时间，Unix毫秒数时间戳
created_at	Int	声音创建时间，Unix毫秒数时间戳

Announcer

字段名	类型	描述
id	Int	主播用户ID，即喜马拉雅账号ID
nickname	String	主播用户昵称
avatar_url	String	主播用户头像图片url
is_verified	Bool	主播是否加V

LastUpTrack

字段名	类型	描述
track_id	Int	最新上传声音ID
track_title	String	最新上传声音标题
duration	Int	最新上传声音时长，单位为秒
updated_at	Int	最新上传声音更新时间，Unix毫秒数时间戳
created_at	Int	最新上传声音创建时间，Unix毫秒数时间戳

SubordinatedAlbum

字段名	类型	描述
id	Int	声音所属专辑ID
album_title	String	声音所属专辑标题
cover_url_small	String	声音所属专辑封面小图url，尺寸为86x86（像素）
cover_url_middle	String	声音所属专辑封面中图url ，尺寸为140x140（像素）
cover_url_large	String	声音所属专辑封面大图url，尺寸为290x290（像素）