服务端 API 文档

Key 防盗链

最近更新时间:2020-05-27 16:08:25

功能介绍

  • 支持在视频 URL 中指定过期时间,他人获取后无法长期使用。
  • 支持在视频 URL 中指定最大允许播放 IP 数,他人获取后不能无限制地分发给更多人观看。
  • 支持在视频 URL 中指定试看时长,实现试看功能。
  • 开发者使用密钥KEY对视频 URL 签名,并在 URL 中带上签名结果。只要用户密钥不泄露,其他用户无法伪造视频 URL。
  • CDN 节点检查视频 URL 中的参数和签名,对视频播放请求进行控制。如果请求检查不通过,则返回403响应码。
  • 支持的文件类型:MP4、TS、M3U8、FLV、AAC、MOV、WMV、AVI、MP3、RMVB、MKV、MPG、3GP、WEBM、M4V、ASF、F4V、WAV、MPEG、VOB、RM、WMA、DAT、M4A、MPD、M4S。
说明:

开启 Key 防盗链请参见 设置防盗链

防盗链 URL 生成方式

  • 开发者在云点播中的视频均存在视频原始 URL。未开启防盗链时,使用视频原始 URL 即可播放视频。
  • 开启 Key 防盗链后,视频原始 URL 不再能播放,此时需要构造视频的防盗链 URL

防盗链 URL 的生成规则是在原始 URL 尾部,以 QueryString 的方式加入防盗链参数,形如:

http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=[t]&exper=[exper]&rlimit=[rlimit]&us=[us]&sign=[sign]

QueryString 中的防盗链参数必须按照texperrlimitussign的顺序拼接,下面详细介绍防盗链 URL 中各个参数的含义和取值方法。

防盗链参数

参数名 必选 说明
KEY 开启 Key 防盗链时填写的密钥。必须由大小写字母(a - Z)或者数字(0 - 9)组成,长度在8 - 20个字符之间。建议在控制台中单击【生成KEY】生成,具体操作步骤请参见 设置防盗链
Dir 视频原始 URL 的 PATH 中除去文件名的那部分路径。如果原始 URL 为http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4,则播放路径为/dir1/dir2/
t
  • 播放地址的过期时间戳,以 Unix 时间的十六进制小写形式表示
  • 过期后该 URL 将不再有效,返回403响应码。考虑到机器之间可能存在时间差,防盗链 URL 的实际过期时间一般比指定的过期时间长5分钟,即额外给出300秒的容差时间
  • 建议过期时间戳不要过短,确保视频有足够时间完整播放
  • exper
  • 试看时长,单位为秒,以十进制表示,不填或者填0表示不试看(即返回完整视频)
  • 试看时长不要超过视频原始时长,否则可能导致播放失败
  • rlimit
  • 最多允许多少个不同 IP 的终端播放,以十进制表示,不填表示不做限制
  • 当限制 URL 只能被1个人播放时,建议 rlimit 不要严格限制成1(例如可设置为3),因为移动端断网后重连 IP 可能改变
  • us
  • 链接标识,用于随机化一个防盗链 URL,增强链接的唯一性
  • 建议每次生成防盗链 URL 时,指定一个随机的 us 值
  • sign
  • 防盗链签名,以32个字符长的十六进制数表示,用于校验防盗链 URL 的合法性
  • 签名校验失败将返回403响应码。下面将介绍 签名计算公式
  • 签名计算公式

    sign = md5(KEY + Dir + t + exper + rlimit + us)

    公式中的+代表字符串拼接,选填参数可以为空字符串。

    防盗链 URL 生成示例

    如果某个开发者在云点播中有一个视频,视频的原始播放 URL 是http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4。该开发者开通了 Key 防盗链,生成的密钥是24FEQmTzro4V5u3D5epW,生成的随机字符串为72d4cd1101,现有如下需求:

    1. 为这个视频生成防盗链 URL,URL 的过期时间是2018年01月31日20:00(Unix 时间为1517400000)。
    2. 生成一个试看 URL,试看时长为视频的前5分钟(视频原始时长大于5分钟)。
    3. 限制 URL 可播放的 IP 数,允许最多3个不同 IP 的终端可以播放该 URL。

    下面分别对“视频播放地址有效时间控制”、“视频播放地址允许最多播放 IP 数”和“视频允许播放时长控制”的场景,介绍如何生成防盗链 URL。

    示例1:播放地址有效时间控制

    步骤1:确定防盗链参数

    参数名 取值 说明
    KEY 24FEQmTzro4V5u3D5epW 开发者开通 Key 防盗链时选择的密钥
    Dir /dir1/dir2/ 原始播放 URL 的 PATH 中除去myVideo.mp4的剩余部分
    t 5a71afc0 过期时间戳1517400000的十六进制表示结果
    us 72d4cd1101 生成的随机字符串

    步骤2:计算签名

    sign = md5("24FEQmTzro4V5u3D5epW/dir1/dir2/5a71afc072d4cd1101") = "3d8488faeb37d52d6bf63b63c1b171c3"

    步骤3:生成防盗链 URL

    将防盗链参数拼接到视频原始 URL 的 QueryString 中,得到视频防盗链 URL:

    http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&us=72d4cd1101&sign=3d8488faeb37d52d6bf63b63c1b171c3

    示例2:播放地址最多可播放 IP 数

    步骤1:确定防盗链参数

    参数名 取值 说明
    KEY 24FEQmTzro4V5u3D5epW 开发者开通 Key 防盗链时选择的密钥
    Dir /dir1/dir2/ 原始播放 URL 的 PATH 中除去myVideo.mp4的剩余部分
    t 5a71afc0 过期时间戳1517400000的十六进制表示结果
    rlimit 3 限制最多允许3个不同的 IP 播放 URL
    us 72d4cd1101 生成的随机字符串

    步骤2:计算签名

    sign = md5("24FEQmTzro4V5u3D5epW/dir1/dir2/5a71afc0372d4cd1101") = "c5214f0d5961b13acd558b4957c4dfc5"

    步骤3:生成防盗链 URL

    将防盗链参数拼接到视频原始 URL 的 QueryString 中,得到视频防盗链 URL:

    http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&rlimit=3&us=72d4cd1101&sign=c5214f0d5961b13acd558b4957c4dfc5

    示例3:允许播放时长控制

    步骤1:确定防盗链参数

    参数名 取值 说明
    KEY 24FEQmTzro4V5u3D5epW 开发者开通 Key 防盗链时选择的密钥
    Dir /dir1/dir2/ 原始播放 URL 的 PATH 中除去myVideo.mp4的剩余部分
    t 5a71afc0 过期时间戳1517400000的十六进制表示结果
    exper 300 试看前5分钟,即300秒
    us 72d4cd1101 生成的随机字符串

    步骤2:计算签名

    sign = md5("24FEQmTzro4V5u3D5epW/dir1/dir2/5a71afc030072d4cd1101") = "547d98c4b91e81b5ea55c95cef63223f"

    步骤3:生成防盗链 URL

    将防盗链参数拼接到视频原始 URL 的 QueryString 中,得到视频防盗链 URL:

    http://example.vod2.myqcloud.com/dir1/dir2/myVideo.mp4?t=5a71afc0&exper=300&us=72d4cd1101&sign=547d98c4b91e81b5ea55c95cef63223f

    Key 防盗链生成和校验工具

    云点播为开发者提供了 Key 防盗链 URL 的生成工具和校验工具,开发者可以使用该工具快速准确地生成和校验符合要求的防盗链 URL。

    注意事项

    • 该功能为可选项,默认不启用。
    • 启用该功能后,视频原始 URL 将不再能直接播放,需要按规则生成合法的防盗链 URL。
    • 密钥KEY必须由大小写字母(a - Z)或者数字(0 - 9)组成,长度在8 - 20个字符之间。
    • 若防盗链 URL 过期,或者签名不能通过,将无法播放视频,并返回403响应码。
    • 防盗链 URL 中 QueryString 的各参数必须按照texperrlimitussign的顺序出现,如果顺序不正确将无法播放视频。
    • 如果使用试看功能,需确保试看时长不大于视频时长,否则将导致视频无法播放。
    • 试看对视频的格式有较严格的要求(仅支持 H.264,视频元信息在视频文件的头部等),不符合格式要求的原始视频使用试看功能将产生异常。建议使用云点播转码功能进行转码,对转码后视频设置试看(转码后的格式均符合试看格式要求)。
    目录