SparkAPI_开发指南_v2.1.4.pages

Size: px

Start display at page:

Download "SparkAPI_开发指南_v2.1.4.pages"

饶蒋
5 years ago
Views:

1 Spark API 开发指南版本 : 日期 : 北京梦之窗数码科技有限公司

2 目录 1. 概述通信约定 HTTP 方法返回格式编码格式加密接口访问次数限制 HTTP 接口获取用户信息获取视频信息批量获取视频信息获取视频播放代码编辑视频信息删除视频获取视频分类搜索视频 Flash 接口视频上传附录 1. HTTP 通信加密算法附录 2. Flash 和 JavaScript 交互... 16

3 1. 概述利用 Spark API 可以与 CC 视频 Spark 云进行对接, 使用 Spark 云的主要视频功能当前 Spark API 的版本号为 2.1, 具有上传播放获取视频信息获取用户信息删除视频获取视频分类等接口目前 Spark API 仅对合作方开启, 如果您有使用的需求, 请通过 CC 视频后台申请 API Key, 通过审核后才能使用 Spark API 2. 通信约定 Spark API 的远程通信接口基于 HTTP 协议, 并有以下约定 : 2.1 HTTP 方法所有接口采用 GET 请求 2.2 返回格式接口的返回格式包括 XML 格式和 JSON 格式, 编码均为 UTF-8 对于不同的接口, 正确的返回结果的格式会在每个接口中单独定义, 错误的返回结果具有统一的形式, 如下所示 : <error>error_code</error> error : ERROR_CODE 实际中, 下表中的某一个具体的错误码会替换掉上面的 ERROR_CODE: 错误码 INVALID_REQUEST SPACE_NOT_ENOUGH SERVICE_EXPIRED PROCESS_FAIL TOO_MANY_REQUEST PERMISSION_DENY 用户输入错误用户剩余空间不足用户服务已经过期服务器处理失败访问过于频繁用户服务无权限 2.3 编码格式 Spark API 只接受 UTF-8 格式编码的信息, 返回的数据也都是 UTF-8 编码的当需要通过 GET 请求传递时,QueryString 里面的 value 值都需要进行 URL Encode 之后, 再进行传递 2.4 加密所有的 HTTP 通信都是加密的, 加密的核心思想是将原始的 QueryString 转换为和请求时间相关的 HashedQueryString, 我们称这个加密算法为 THQS 算法关于 THQS 算法的细节请参见附录 1 第 1 页共 16 页

4 2.5 接口访问次数限制当某一个接口的访问频率在一分钟之内超过 100 次的时候, 该用户的 API 功能将被禁用, 之后所有请求都将失效如果上述阈值无法满足您的正常需求的时候, 可以联系 CC 客服申请提升 API 的请求频率 3. HTTP 接口 3.1 获取用户信息通过该接口可以获取指定用户的账户信息, 地址为 : 需要传递以下 : userid format 用户 id, 不可为空返回格式,xml 或 json 返回数据 user 包含如下字段 : account version expired space traffic 用户账户版本信息到期时间用户空间信息用户流量信息 space 包含如下字段 : total remain used 用户空间总量, 单位 G 用户空间剩余总量, 单位 G 用户空间使用总量, 单位 G traffic 包含如下字段 : total remain used 用户流量总量, 单位 G 用户剩余流量大小, 单位 G 用户已使用流量大小, 单位 G XML 格式的返回信息如下 : 第 2 页共 16 页

5 <user> <version><![cdata[ 试用版 ]]></version> <expired> </expired> <space> <total>2</total> <remain>1.9</remain> <used>0.1</used> </space> <traffic> <total>5</total> <remain>4.8</remain> <used>0.2</used> </traffic> </user> JSON 格式的返回信息如下 : "user": "account":"test@test.com", "version":" 试用版 ", "expired":" ", "space": "total":2, "remain":1.9, "used":0.1, "traffic": "total":5, "remain":4.8, "used": 获取视频信息通过该接口可以获取指定用户的有效视频的信息, 地址为 : 需要传递以下 : userid videoid format 用户 id, 不可为空视频 id, 不可为空返回格式,xml 或 json 返回数据 video 包括如下字段 : 第 3 页共 16 页

6 id title desp tags duration category image imageindex image-alternate 视频 ID 视频标题视频描述视频标签视频时长, 单位秒视频分类 ID 视频截图地址视频截图序号视频截图排列信息 image-alternate 包括如下字段 : index url 视频截图排列序号视频截图地址 XML 格式的返回信息如下 : <video> <id> </id> <title><![cdata[ 视频标题 ]]></title> <desp><![cdata[ 视频描述 ]]></desp> <tags><![cdata[ 标签 1 标签 2 标签 3]]></tags> <duration>12345</duration> <category>12345</category> <image> <imageindex>1</imageindex> <image-alternate> <index>0</index> <url> </image-alternate> <image-alternate> <index>1</index> <url> </image-alternate>... </video> JSON 格式的返回信息如下 : 第 4 页共 16 页

7 "video": "id":" ", "title":" 视频标题 ", "desp":" 视频描述 ", "tags":" 标签 1 标签 2 标签 3", "duration":12345, "category":"12345", "image":" "imageindex":1, "image- alternate":[ "index":0, "url":" ] 3.3 批量获取视频信息通过该接口可以获取指定用户的一批有效视频 ( 不包括删除正在处理的视频 ) 的信息, 地址为 : 需要传递以下 : userid videoid_from videoid_to 用户 id, 不可为空起始 videoid, 若为空, 则从上传的第一个视频开始终止 videoid, 若为空, 则到最后一个上传的视频 num_per_page 返回信息时, 每页包含的视频个数注 : 允许范围为 1~100 page format 当前页码返回格式,xml 或 json 返回数据 videos 包含以下字段 : total video 返回视频数量视频信息 video 包含以下字段 : 第 5 页共 16 页

8 id title desp tags duration category image imageindex image-alternate 视频 ID 视频标题视频描述视频标签视频时长, 单位秒视频分类 ID 视频截图地址视频截图序号视频截图排列信息 image-alternate 包含以下字段 : index url 视频截图排列序号视频截图地址 XML 格式的返回信息如下 : <videos> <total>100</total> <video> <id> </id> <title><![cdata[video Title]]></title> <desp><![cdata[video Description]]></desp> <tags><![cdata[tag1 tag2 tag3]]></tags> <duration>12345</duration> <category>12345</category> <image> <imageindex>1</imageindex> <image-alternate> <index>0</index> <url> </image-alternate> <image-alternate> <index>1</index> <url> </image-alternate>... </video>... </videos> JSON 格式的返回信息如下 : 第 6 页共 16 页

9 "videos": "total":100, "video":[ "id":" ", "title":"video Title", "desp":"video Description", "tags":"tag1 tag2 tag3", "duration":12345, "category":"12345", "image":" "imageindex":1, "image-alternate":[ "index":0, "url":" ], ] 3.4 获取视频播放代码通过该接口可以获取指定视频的视频播放 HTML 代码段, 地址为 : 需要传递以下 : videoid userid playerid player_width player_height auto_play format 视频 id, 不可为空用户 id, 不可为空播放器 id, 若为空则返回默认播放器播放器宽度, 单位 px 播放器高度, 单位 px 是否自动播放,true 或 false 返回格式,xml 或 json 返回数据 video 包含以下字段 : playcode 嵌入网页的播放代码 XML 格式的返回信息如下 : 第 7 页共 16 页

10 <video> <playcode> <![CDATA[<script src=' vid= c315e6a9&siteid=1936d297411c3a27&autostart=false&width=600&height=490&playerid =6ED7421AB96B522E&playertype=1' type='text/javascript'></script>]]> </playcode> </video> JSON 格式的返回信息如下 : "video": "playcode":"<script src=' vid= c315e6a9&siteid=1936d297411c3a27&autostart=false&width=600&height=490&playerid =6ED7421AB96B522E&playertype=1 type='text/javascript'></script>" 3.5 编辑视频信息通过该接口可以编辑指定视频的信息, 地址为 : 需要传递以下 : videoid userid title tag description categoryid playurl imageindex format 视频 id, 不可为空用户 id, 不可为空视频标题视频标签视频描述视频子分类 id 视频播放页面地址, 如果不编辑播放地址, 请勿加入此视频封面截图序号, 如果不编辑封面截图, 请勿加入此注 : 只可编辑正常可播放状态的视频截图返回格式,xml 或 json 返回数据 video 包含如下字段 : 第 8 页共 16 页

11 id title desp tags category playurl imageindex 视频 ID 视频标题视频描述视频标签视频分类 ID 视频播放页面地址视频截图序号 XML 格式的返回信息如下 : <video> <id> </id> <title><![cdata[video Title]]></title> <desp><![cdata[video Description]]></desp> <tags><![cdata[tag1 tag2 tag3]]></tags> <category>12345</category> <playurl> <imageindex>1</imageindex> </video> JSON 格式的返回信息如下 : "video": "id":" ", "title":"video Title", "desp":"video Description", "tags":"tag1 tag2 tag3", "category":"12345", "playurl":" "imageindex":1 3.6 删除视频通过该接口可以删除指定视频的信息, 地址为 : 需要传递以下 : videoid userid format 视频 id, 不可为空用户 id, 不可为空返回格式,xml 或 json XML 格式的返回信息如下 : 第 9 页共 16 页

12 <result>ok</result> JSON 格式的返回信息如下 : "result":"ok" 3.7 获取视频分类通过该接口可以获取指定用户创建的全部视频分类, 地址为 : 需要传递以下 : userid format 用户 id, 不可为空返回格式,xml 或 json 注 : 返回结果中的 level 包括 BASIC 和 PREMIUM,BASIC 中只包含一个默认父分类, 无法创建自定义父分类, PREMIUM 版本中包含用户创建的父分类返回数据 video 包含如下字段 : level category 视频分类等级视频分类信息 category 包含如下字段 : id name sub-category 分类 ID 分类名称子分类信息 sub-category 包含如下字段 : id name 子分类 ID 子分类名称 XML 格式的返回信息如下 : 第 10 页共 16 页

13 <video> <level>basic</level> <category> <id>123</id> <name><![cdata[category1]]></name> <sub-category> <id>456</id> <name><![cdata[sub category1]]></name> <sub-category>... </category>... </video> JSON 格式的返回信息如下 : "video": "level":"premium", "category":[ "id":123, "name":"category1", "sub-category":[ "id":456, "name":"sub category1",... ],... ] 3.8 搜索视频通过该接口可以搜索指定信息的视频, 地址为 : 需要传递以下 : 第 11 页共 16 页

14 userid q 用户 id, 不可为空查询条件, 不可为空格式 : 查询字段 : 查询内容查询字段 : 目前只支持 TITLE 查询内容 : 查询关键字注 : 格式中的 : 为英文半角 Example:q=TITLE:test sort 查询结果排序, 不可为空格式 : 排序字段 : 排序方式排序字段 :CREATION_DATE 或 FILE_SIZE 排序方式 :ASC 或 DESC 注 : 格式中的 : 为英文半角 Example:sort=CREATION_DATE:DESC categoryid 视频子分类 id, 如果不查询指定分类下的视频, 请勿加入此 num_per_page 返回信息时, 每页包含的视频个数注 : 阈值为 1~100 page format 当前页码返回格式,xml 或 json 返回数据 videos 包含如下字段 : total video 返回视频数量视频信息 video 包含如下字段 : id title desp tags duration category creation-date filesize image 视频 ID 视频标题视频描述视频标签视频时长, 单位秒视频分类 ID 视频创建时间视频文件大小, 单位字节视频截图地址 XML 格式的返回信息如下 : 第 12 页共 16 页

15 <videos> <total>100</total> <video> <id> </id> <title><![cdata[video Title]]></title> <desp><![cdata[video Description]]></desp> <tags><![cdata[tag1 tag2 tag3]]></tags> <duration>12345</duration> <category>12345</category> <creation-date> :16:50</creation-date> <filesize> </filesize> <image> </video>... </videos> JSON 格式的返回信息如下 : "videos": "total":100, "video":[ "id":" ", "title":"video Title", "desp":"video Description", "tags":"tag1 tag2 tag3", "duration":12345, "category":"12345", "creation-date":" :16:50", "filesize": , "image":" ] 4. Flash 接口 Spark API 中所有的 Flash 接口需要 Flash 插件的版本在 10.1 以上才有效, 使用前请确保 Flash 插件版本符合要求 4.1 视频上传在上传视频的过程中, 不用与 Spark 平台进行 HTTP 通信, 使用 JavaScript 和 Spark 平台提供的 Flash 进行交互即可完成关于如何在网页中嵌入 Flash 以及如何和 Flash 进行交互, 请参阅附录 2 上传接口用到的所有 JavaScript 函数定义见下表 : 第 13 页共 16 页

16 函数定义 on_spark_selected_file(file_name, file_size) on_spark_upload_validated(status, videoid) on_spark_upload_progress(progress) file_name: 上传文件名 file_size: 上传的文件大小, 单位字节 status: 验证结果 videoid: 视频 id progress: 上传进度正确时,0~100 之间的整数, 包括 0 和 100; 错误时, 返回 -1. 网页嵌入 Spark 平台提供的上传 Flash 时, 需要传递下列 : Flash (flashvars) progress_interval notify_url 回调进度函数的时间间隔, 默认 1 秒视频处理完毕后的通知地址上传文件的过程一共分为四步 : 第一步, 选择文件 Spark 平台提供一个透明的 Flash 进行文件上传, 地址如下 : 由于它是透明的, 所以可以置于任何一个 HTML 元素的上方而不影响的页面视觉效果上传文件时, 必须通过点击到该 Flash 从而打开浏览对话框进行文件选择文件选择成功后,Flash 会调用页面中的 on_spark_selected_file 函数, 页面可以选择合适的方式处理该事件第二步, 验证当用户选择文件后, 需将下面的按照 THQS 算法处理后传递给 Flash 的 start_upload 函数后, 才能开始上传流程首先要进行和权限的验证, 通过后才开始文件上传 userid title description tag categoryid 用户 id, 不可为空视频标题, 若为空, 则采用去后缀文件名作为 title 视频简介, 可以为空视频标签, 可以为空视频子分类 id, 可选验证完成后,Flash 会调用 on_spark_upload_validated 函数传递验证结果以及视频 id 验证状态码的含义如下 : 验证状态码 OK NETWORK_ERROR 其它成功网络错误 Spark API 错误码第 14 页共 16 页

17 第三步, 文件上传文件开始上传后,Flash 会周期性调用 on_spark_upload_progress 函数来报告上传进度, 间隔秒数由 progress_interval 指定如果上传的进度为负数, 则发生网络错误, 上传中断返回 100 则表示上传成功当返回 100 或者 -1 后,Flash 就不再调用该函数了第四步, 回调当 Spark 平台处理完毕视频后 ( 上传转码审核都完成后 ), 会通过 HTTP 的 GET 方式通知你的网站该地址由 notify_url 指定通知时会以 THQS 方式携带以下 : videoid status 视频 id,16 位 hex 字符串视频状态 OK 表示视频处理成功, FAIL 表示视频处理失败 duration 片长 ( 单位 : 秒 ) image 视频截图地址视频处理失败有多种情况, 例如视频文件异常视频内容违规等等 <result>ok</result> 当 notify_url 指定的接口返回上述 XML 时,Spark 平台会认为网站已经成功接收到了回调信息, 不再进行重试返回其它任何内容,Spark 平台会进行回调重试, 重试的间隔会随着重试次数的增大而增大若重试 7 次后, 依然没有成功, 则不再进行通知因此,Spark 平台最多通知 8 次这 8 次的通知时间距第一次的通知时间的差分别为 : [0,15s, 1m, 4m, 16m, 1h4m, 4h16m, 17h4m] 附录 1. HTTP 通信加密算法当需要和 Spark 平台进行 HTTP 通信时, 需要将原始的 Query String 转换为和请求时刻相关的 Hashed Query String 后再通过 GET 方法请求 Spark API 为了描述的方便, 我们将 Query String 转换为 Hashed Query String 的算法称为 THQS 算法在描述详细的算法流程之前, 我们先介绍一下 Unix 时间戳的概念 Unix 时间戳, 即该时间到 1970 年 1 月 1 日 (UTC/GMT 的午夜 ) 之间的秒数例如, 北京时间 2010 年 12 月 9 日 15 点 23 分 12 秒的 Unix 时间戳为 THQS 算法假设原来的 QueryString 为 q, 通过以下 4 个步骤, 即可得到最终用于通信的 HashedQueryString: 1. 对于 q 中的每个键值对按照键的字母顺序升序排序, 得到排序后的请求字符串 qs; 2. 加入当前时间的 Unix 时间戳和 Spark 平台帐号对应的 API Key 值, 得到散列前的字符串 qf: qf qs&time=12345&salt=asdf 计算得到 qf 的 md5 值, 假设为 abcdefg hash md5(qf) 4. 最终的 HashedQueryString 为 : hqs qs&time=12345&hash=abcdefg 用 hqs 代替 q 进行 Http 通信第 15 页共 16 页

18 下面举一个例子计算过程假设用户从 Spark 获取到的 API Key 值是 asdf1234, 当前时间为 2010 年 12 月 9 日 15 点 23 分 12 秒, 原始的 QueryString 是 name=harry&level=top&salary=1000 第一步, 将上述 QueryString 按照字母顺序进行升序排序, 结果是 level=top&name=harry&salary=1000 第二步, 附加 time 值和 salt 值, 得到取 hash 前的字符串 level=top&name=harry&salary=1000&time= &salt=asdf1234 第三步, 对上述字符串取 md5 值 hash=bf04a55b30cff562f7add9f054ab7ffb 因此, 最终进行 Http 通信的字符串为 level=top&name=harry&salary=1000&time= &hash=bf04a55b30cff562f7add9f054ab7ffb 附录 2. Flash 和 JavaScript 交互 Spark 平台的通信模式中, 有若干种方式需要通过与页面中嵌入的 Flash 交互完成 Flash 和页面有多种方式可以交互, 为了保证 Spark 平台提供的 Flash 能够在各种环境下都能正常工作, 推荐采用以下方式进行处理首先, 需要用将 swf 文件嵌入到网页中, 推荐采用 swfobject 1.5 版本将 swfobject.js 添加到网页中后, 用以下 js 语句将 swf 嵌入到网页中, <script type="text/javascript"> var swfobj=new SWFObject(' 'swfname', '80', '80', '8'); swfobj.addvariable('title','test'); swfobj.addvariable('number', 123); swfobj.addparam('allowfullscreen','true'); swfobj.addparam('allowscriptaccess','always'); swfobj.addparam('wmode','transparent'); swfobj.write('divid'); </script> 其次, 调用 Flash 中的函数的时候, 如果 Flash 提供的函数名叫 func, 而需要传递的是 param 的话, 那么下面这句就可以调用该函数 swfname["func"](param); 其中,swfname 是嵌入 Flash 的 id 值第 16 页共 16 页

SparkAPI_开发指南_v2.1.4.pages

SparkAPI_开发指南_v2.1.4.pages Spark API 开发指南北京梦之窗数码科技有限公司版本 : 2.1.4 日期 : 2014-03-21 目录 1. 概述... 1 2. 通信约定... 1 2.1 HTTP 方法... 1 2.2 返回格式... 1 2.3 编码格式... 1 2.4 加密... 1 2.5 接口访问次数限制... 2 3. HTTP 接口... 2 3.1 获取用户信息... 2 3.2 获取视频信息...