影视采集接口对接文档
这一页只写对接要用的东西:地址、参数、返回结构、字段规范、排障。不写概念,不写愿景。
列表地址
http://api.yingshicaiji.com/api/provide/vod/?ac=list&pg=1详情地址
http://api.yingshicaiji.com/api/provide/vod/?ac=detail&pg=1把这两条粘贴到苹果CMS 后台的“自定义采集”里即可,不需要改路径前缀。
返回结构
第一层两个键:code 为 1 表示成功,list 是数据数组。另有两个分页字段:pagecount 总页数、total 总条数、limit 单页条数、page 当前页。
detail 与 list 的差别只在 list 里不带 vod_play_url 与 vod_content,返回体因此小 4 倍左右。
请求参数
只有 6 个参数,常用的就前 3 个。
| 参数 | 取值 | 说明 |
|---|---|---|
| ac | list 或 detail | list 取列表,detail 取详情含播放串,默认 list |
| pg | 整数,从 1 起 | 翻页参数,超过 pagecount 返回空列表 |
| t | 分类 ID,可多个 | 按 type_id 过滤,多个用逗号分隔,最多 8 个 |
| ids | 影片 ID,可多个 | 仅在 detail 下生效,一次最多 50 个 |
| at | json 或 xml | 返回格式,默认 json |
| h | 整数小时 | 只回最近 N 小时变更的记录,用于增量采集 |
字段说明
完整 43 项,这里列对接最常读的 8 组。
| 字段 | 取值规范 |
|---|---|
| vod_id | 站内唯一主键,跨源不冲突 |
| vod_name | 片名,已去首尾空格与全角标点 |
| type_id / type_name | 分类 ID 与分类名,附三级路径 |
| vod_pic | 16:9 封面地址,另附 original_pic |
| vod_year / vod_area / vod_lang | 年份整数、地区、语言 |
| vod_remarks | 更新至X集 / 完结 / 修复 |
| vod_play_from | 播放组标识,$$$ 分组 |
| vod_play_url | 播放串,# 分集,$$$ 分组 |
首次对接的五步
按顺序做,别跳。第五步之前不要开全量。
第一步:拿测试密钥
联系接口咨询电话或发邮件,说明站点类型与日采量。当天给密钥,含 500 次调用。
第二步:核对一页数据
先用 ac=list 拉一页,看分类名与条数对不对;再拉一页 detail,看播放串是否是 ### 格式。
第三步:做分类映射
把本地的 28 个分类逐个绑到 type_id。绑完先空跑,确认没有两个分类绑到同一个 ID。
第四步:小批量入库
先入 200 条,检查封面比例、集数顺序、入库时间三项。三项都对再放大。
第五步:开定时任务
按分类拆时间段,间隔 30 到 40 分钟。第一次全量建议放在凌晨 2 点以后。
常见返工点
分类绑错、播放器标识写错、缓存没清。三处占了返工的八成,做完一步就核对一步。
排障表:8 种现象对应 8 个动作
按现象查,不用逐条读文档。
| 现象 | 原因 | 处理 |
|---|---|---|
| 返回 code 为 0 | 接口地址拼错或缺少 ac 参数 | 核对地址,补 ac=list 或 ac=detail |
| list 为空但 pagecount 有值 | pg 超过总页数 | 把 pg 收回到 pagecount 以内 |
| detail 缺播放串 | 片源尚未入库完成 | 等 15 分钟再查,或用 h 参数取最新变更 |
| 播放 403 | 源站防盗链 | 换线路或走 M3U8 解析接口代取 |
| 封面比例不对 | 模板读的不是 16:9 字段 | 改用 vod_pic,竖版用 original_pic |
| 分类名乱码 | 请求未带 UTF-8 声明 | 请求头加 Accept-Charset: utf-8 |
| 增量漏数据 | h 参数窗口太短 | 把窗口从 1 小时放宽到 2 小时 |
| 同一片重复入库 | 未按 vod_id 判重 | 入库前按 vod_id 做唯一约束 |
文档没写到的 5 个问题
接口支持 HTTPS 吗
支持,https 与 http 两个地址都能用,证书由我方维护,TLS 1.2 以上。
一次能拉多少条
detail 单页 20 条,ids 批量最多 50 条;一次请求超过 50 条会拆成多次。
有 SDK 吗
没有官方 SDK,接口就是普通 HTTP 请求,用 curl 或任何语言的 HTTP 库都能调。
返回体多大
detail 单页约 14KB,list 单页约 3KB,按 20 条一页算。
字段会增加吗
会增加,只增不改。新增字段在公告里说明,旧字段保持原有含义。