文件预取
更新时间：2021-01-22 13:34:54
一. 功能简介
缓存和存储的主要区别在于缓存是用户请求触发，可以边存储边响应，而且缓存文件具有一定的时效性。当用户首次请求文件时，CDN节点并没有缓存，需要先回源获取文件，再响应给用户，同时将文件缓存下来，方便后续其他用户访问。CDN节点回源获取文件需要消耗一定的时间，会增加用户的首包时间和首帧时间。
文件预取功能，将CDN节点的被动触发式，转为主动拉取式，即在用户还未请求时，先让CDN节点回源获取指定的文件，等用户过来访问时，CDN节点命中缓存直接响应，缩短响应时间，提高首包时间和首帧时间。
二. 功能说明
2.1 基本原理
网宿通过内容管理系统，将需要预取的URL下发给CDN节点，CDN节点获取到预取的指令后，会主动回源拉取指定的文件。当用户首次请求这些文件时，CDN节点就可以直接响应，无需再回源。
2.2 业务流程
（1）客户通过Web页面或者API接口向网宿内容管理系统提交需要预取的URL列表；
（2）网宿内容管理系统将客户提交的URL列表，下发给CDN节点；
（3）CDN节点接收到URL列表后，根据列表信息向视频源站请求对应文件；
（4）视频源站响应CDN节点请求，CDN节点将对应文件缓存到本地；
（5）用户向CDN节点发起请求；
（6）CDN节点命中缓存，直接响应。
2.3 使用说明
网宿提供Web页面和API接口两种方式，供客户提交需要预取的URL信息。
2.3.1 SI Web配置界面
SI Web操作页面截图如下：
2.3.2 SI API自助化接口
2.3.2.1 接口功能描述
将源站的内容主动预取到CDN节点，用户首次访问可直接命中缓存，既提升首次访问速度，又能有效缓解源站压力。
- 调用URL： https://open.chinanetcenter.com/ccm/fetch/ItemIdReceiver
- 限制说明：每日不超过5000条，10G文件大小，每次接口调用url的总数不超过400条。
- 调用频率：10/5min
2.3.2.2 请求参数
| 参数名称 | 类型 | 必填 | 描述 |
| urls | Array | 是 | 要预取到CDN节点的url集合，单次调用最多允许提交400条。 url格式说明： 1）URL 必须以'http://' 或 'https://' 开头，输入示例：http://www.a.com/image/test.png。 2）每个url最大长度 1000 字符。 3）每个url所在的域名必须是在网宿科技加速的域名且有预取权限。 4）url中如果包含中文字符，则提交的url需要是中文转义后的url，采用utf-8方式转义。 |
| fetchOption | String | 否 | 预取的方式，数值说明： "Y"表示只预取，默认为"Y" "N"表示非只预取 名词说明： 只预取：不管节点是否有缓存要预取的文件，都将文件预取并缓存到节点。即只有当要预取的文件在CDN节点上不存在或缓存已过期，CDN节点才会回源获取文件。 非只预取：先清理节点要预取文件的缓存，再将文件预取到节点。即不管要预取的文件在CDN节点上是否有缓存或是否过期，CDN节点都会回源获取文件。 |
| isRange | Int | 否 | 本次提交的任务是否要只预取range段，假如一个文件有200M，用户访问文件都是从头开始，那么为了加快用户访问的首屏时间，可以只预取文件0~range的大小，而不是预取整个文件。每次预取多大的range支持配置，有需要可以根据自身文件的大小联系网宿客技人员进行配置。默认只预取0~512KB的大小。 0表示否，预取完整的文件（默认值） 1表示是只预取文件前面的range段，不预取完整文件。 |
2.3.2.3 返回参数
| 参数名称 | 类型 | 描述 |
| x-cnc-request-id | String | 本次请求的唯一标识,当接口调用异常时，可将requestID提供给网宿技术支持，便于排查接口的访问日志。 |
| Code | Int | 表示任务创建结果的状态码，1表示任务提交成功，0表示任务提交失败 |
| Message | String | 表示任务提交后，系统的响应消息 |
| itemId | String | 调用一次接口并提交任务成功后，将返回一个itemId，是当次提交任务的唯一标识，通过itemId可批量查询任务的状态（成功/失败）。 |
2.3.2.4 错误码
| 错误代码（code） | 描述（message） | HTTP状态码 | 语义 |
| 1 | success | 200 | 任务已提交成功，内容管理系统已成功接收到预取任务 |
| 0 | parse json error | 200 | Json解析出错 |
| 0 | urls must be array | 200 | 要预取的urls入参必须为json数组格式 |
| 0 | username is invalid | 200 | 您调用预取接口的用户不存在或用户未启用 |
| 0 | storage today has reached the limit | 200 | 您今日文件预取总存储量已超标 |
| 0 | urls can not be empty | 200 | 要预取的文件集合不允许为空，即入参urls不允许为空 |
| 0 | the remaining number of urls today can submit is [] | 200 | 您本次提交的任务数超过每日剩余可预取任务数 |
| 0 | the number of url out of limit | 200 | 您单次调用提交的url超过400条的数目限制 |
| 0 | urls submitted today has reached the limit [] | 200 | 您今日可预取的文件数量已用完 |
| 0 | these urls are wrong,[url1,url2,...] | 200 | 提交的部分url中频道不允许预取或url格式错误（例如不以http://、https://开头）或频道和用户无关联关系（此次提交的正确的url预取任务不会执行） |
| 0 | all the urls are wrong | 200 | 提交的所有url中频道不允许预取或url格式错误（例如不以http://、https://开头）或频道和用户无关联关系 |
| 0 | system error | 200 | 未知错误 |
2.3.2.5 接口请求示例
!/bin/bash
username=“username”
apiKey=“apiKey”
date=env LANG="en_US.UTF-8" date -u "+%a, %d %b %Y %H:%M:%S GMT"
password=echo -en "$date" | openssl dgst -sha1 -hmac $apiKey -binary | openssl enc -base64
curl -i --url “https://open.chinanetcenter.com/ccm/fetch/ItemIdReceiver”
-X “POST”
-u “$username:$password”
-H “Date:$date”
-H “Content-Type: application/json”
-d ‘{
“fetchOption”:“Y”,
“urls”: [
“https://www.testb.com/test/test1.txt”,
“https://www.testb.com/test/test2.txt”
],
“isRange”:0
}’
2.3.2.6 返回示例
HTTP/1.1 200 OK
Date: Fri, 26 Oct 2012 06:33:26 GMT
Content-Type: application/json;charset=UTF-8
x-cnc-request-id:{id string auto generated by cloud server}
{
“code”: 1,
“message”: “success”,
“itemId”: “a2cfcc6fe79c4a8abcab806578f9bada”
}
2.3.3 每日预取限制
（1）每日预取文件数：5000
（2）每日预取空间大小：10G
三. 使用场景
通过文件预取功能把热点文件提前预取到CDN节点，确保用户访问时能命中缓存直接响应，缩短响应时间，提高首包时间和首帧时间，同时避免回源带宽突增。