API 推送开发实战

API 推送是三种提交方式里最快的一种，也是唯一需要开发的。本篇把从获取 token、调用接口到解读返回码的完整链路讲清楚。

第一步：获取调用入口与 token

进入搜索资源平台的 API 推送工具后，会看到接口调用地址，其中包含一个 token——由 16 个英文数字组成的字符串。接口地址形如：

http://data.zz.baidu.com/urls?site=您的域名&token=您的token

第二步：调用接口

接口接受 POST 请求，body 为纯文本（text/plain），每行一个 URL。官方给出了多种语言的推送示例。

curl 推送示例

将要提交的 url 数据写入一个本地文件（如 urls.txt，每个 url 占一行），然后调用：

curl -H 'Content-Type:text/plain' --data-binary @urls.txt "http://data.zz.baidu.com/urls?site=www.example.com&token=您的token"

POST 请求示例

请求头携带 Host 与 Content-Type，body 每行一个网址：

POST /urls?site=www.example.com&token=您的token HTTP/1.1
User-Agent: curl/7.12.1
Host: data.zz.baidu.com
Content-Length: 83

http://www.example.com/1.html
http://www.example.com/2.html

php、python、java 等语言可参照这个过程推送，本质就是「向接口 POST 一个每行一个 URL 的纯文本」。

第三步：解读返回结果

推送后通过状态码和字段判断是否成功。

状态码 200 表示推送成功，返回字段：

  • success：成功推送的 url 条数；
  • remain：当天剩余的可推送 url 条数；
  • not_same_site（可选）：因不是本站 url 而未处理的列表；
  • not_valid（可选）：不合法的 url 列表。

状态码 4XX 或 500 表示推送失败，常见错误：

状态码 报错信息 含义
400 site error 站点未在站长平台验证
400 empty content post 内容为空
400 only 2000 urls are allowed once 每次最多只能提交 2000 条链接
400 over quota 超过每日配额，再提交无效
401 token is not valid token 错误
404 not found 接口地址填写错误
500 internal error 服务器偶然异常，重试通常成功

六条必知的使用纪律

官方问答里的关键提醒：

  1. 提交时机：页面链接产生或发布时立即提交，效果最好；
  2. 重复提交旧链接：会浪费当日配额，且长期重复提交会被下调配额、甚至失去 API 推送权限；
  3. 每次提交上限：单次最多 2000 条；
  4. 配额是动态的：可提交链接数量上限根据您提交的新产生有价值链接数量决定，提交的优质新链接越多，上限越高；
  5. 重复提交不计数：已提交过的链接再次提交，success 不会统计；
  6. 失败要处理：报错的链接无法提交成功，程序里应根据错误码做相应处理。

小结

API 推送实战要点：拿 token、POST 纯文本、按状态码做事。工程上把它接进 CMS 的「发布」动作——内容一上线就自动推送，既抢时间又省人工。