记一次百度地图 Web 服务 API 的签名踩坑
前阵子给一个内部小工具接百度地图的逆地理编码服务(把经纬度转成地址),功能本身十分钟就写完了,结果在签名上卡了整整半天。最后发现是一个很不起眼的细节问题,写下来给可能踩同款坑的朋友。
背景
百度地图的 Web 服务 API 有两种鉴权方式:老的 IP 白名单方式和 sk 签名方式。为了安全,我们用的签名方式——请求里带 ak(开发者密钥),再额外带一个 sn 参数。sn 是把请求参数按规则计算出来的校验码,服务端用它来确认请求确实来自你。
正确的计算流程
官方文档里 sn 的计算规则是这样的:
- 将所有请求参数(除了 sn 本身)按参数名的字典序排序;
- 把排序后的参数用
&连接成字符串(形如ak=xxx&callback=xxx&coordtype=xxx...); - 在这个字符串前面拼接请求路径,例如
/geocoding/v3/?ak=xxx&coordtype=...; - 使用 URL 编码(RFC 3986,注意空格要编码成
%20而不是+); - 用 UTF-8 编码的字符串与 sk 一起计算 HMAC-SHA1,输出 base64 后再做一次 URL 编码,得到 sn。
看着不复杂对吧?我一开始也是这么想的,结果照着写完,服务端一直返回 AK 校验失败。
坑在哪里
折腾了一下午,最后对着官方调试工具一点一点比对,才发现问题出在编码的时机上。我一开始是先把每个参数值单独做了 URL 编码,再拼起来去算 HMAC——这是错的。正确做法是:先把整个参数字符串原样拼好(不预先编码单个参数),算 HMAC 之前才做统一的 URL 编码。
这俩的区别在于:如果参数值里本身含有 &、=、% 之类的保留字符,先单独编码和最后统一编码得到的字符串不一样,HMAC 自然也就算不对。我们的场景里正好有个参数值带中文(要转成 %E4%B8%AD...),对编码顺序极其敏感。
可用的参考代码
下面是一段可以直接用的 PHP 实现(官方示例里也有,这里按我踩坑后理解的方式重写并加了注释):
<?php
/**
* 计算百度地图 Web 服务 API 的 sn 签名
* @param string $url 请求路径,如 /geocoding/v3/
* @param array $params 请求参数(不含 sn)
* @param string $sk 开发者密钥
*/
function baiduSn($url, array $params, $sk) {
// 1. 按参数名做字典序排序
ksort($params);
// 2. 拼成 a=1&b=2 形式的字符串(注意:此时不做 URL 编码)
$queryStr = http_build_query($params); // PHP 默认 & 分隔,正好是普通 &
// 3. 前面拼上请求路径,得到待签名串
$toSign = $url . '?' . $queryStr;
// 4. 对整串做 RFC 3986 编码(rawurlencode 空格编码为 %20)
$encoded = rawurlencode($toSign);
// 5. HMAC-SHA1 → base64 → 再 URL 编码,得到 sn
$sn = rawurlencode(base64_encode(hash_hmac('sha1', $encoded, $sk, true)));
return $sn;
}
// 用法示例
$ak = '你的ak';
$sk = '你的sk';
$params = [
'ak' => $ak,
'coordtype' => 'wgs84ll',
'location' => '39.9042,116.4074', // 样例值
'output' => 'json',
];
$url = '/geocoding/v3/';
$sn = baiduSn($url, $params, $sk);
// 实际请求
$realUrl = 'https://api.map.baidu.com' . $url
. '?' . http_build_query($params) . '&sn=' . $sn;
几个容易错的小点顺便提一下:
location参数里的逗号是英文半角逗号,别写成中文的;- 调用 URL 和签名时拼接的路径必须一致,
/geocoding/v3/结尾的斜杠不能省; - 如果开了
callback(JSONP 场景),callback 参数也要参与签名,且名字要按字典序排好。
排查建议
如果你也遇到 AK 校验失败,别急着怀疑 ak 本身,先做两件事:一是去百度地图开放平台的 SN 校验工具里把参数粘进去算一遍,看官方工具算出来的 sn 和你的一致不一致;二是把自己拼出来的待签名串打印出来,肉眼对照参数顺序和编码结果。九成的问题,在这两步里都能现形。
半天时间换一个教训:签名类的东西,一定要严格按文档的步骤顺序来,尤其是"编码"和"拼接"的先后次序。望后来者少踩一次坑。
评论(2)