常见问题 | 腾讯位置服务

常见问题

1、WebServiceAPI Key配置中的域名白名单如何使用？

域名白名单适用于浏览器端JSONP方式调用WebserviceAPI服务：

（1）仅白名单中的域名才可使用此key调用WebService服务

（2）留空则不限制调用来源

（3）每行填写一个域名，填写的域名及其子域名都会同时得到授权，如：qq.com，则qq.com下的子域名map.qq.com也可以使用此key

非授权域名使用您的key调用WebServiceAPI时会被拒绝，同时会返回本次请求来源域名，以便您更正配置：

{
    "status": 110,
    "message": "请求来源未被授权（本次请求来源为：lbs.qq.com），请检查key配置。"
}

2、WebServiceAPI Key配置中的授权IP如何使用？

用于限制此key的调用来源IP，以防key被盗用，优点：配置简单，无需开发，但IP地址有变化时，必须同时修改配置。

（1）配置填写方法：

进入Key管理界面，找到要设置的Key进入设置界面，启用产品勾选WebServiceAPI后，会出现相应安全设置，点击“授权IP”进行设置

a. 每行填写一条，留空则不限制。

b. 支持填写单一授权IP，例：202.106.0.99

c. 支持授权IP段，起始IP-结束IP。例(IPv4)：202.106.0.20-202.106.0.26

（2）如何准确得知我的IP地址：

首先您可询问您的网络供应商获悉，另外您可以通过IP定位接口，在接口返回结果中会包含您的服务器IP

（3）非授权IP使用您的key调用WebServiceAPI时会被拒绝，同时会返回本次请求来源IP，以便更正配置：

{
    "status": 112,
    "message": "IP未被授权（本次请求来源IP为：202.106.0.20），请检查key配置。"
}

3、WebServiceAPI Key配置中签名校验如何使用？

与授权IP方式比较，使用SN校验稍有开发量，但不必担心服务器换IP的问题。

选中SN校验后，会生成SecretKey (SK)，用于请求地图WebServiceAPI时计算签名，将签名做为参数（sig）附带到请求中，腾讯服务器会在收到请求后，使用相同的方式生成签名，并与请求中附带的签名进行比对，当一致时即为校验通过，反之则拒绝。

SecretKey (SK) 要注意保密，如有泄漏应尽快重新生成。

4、WebServiceAPI（GET方法）签名计算

（1）通用概念：

a. 请求路径：调用接口时的路径，如：/ws/geocoder/v1，末尾是否带 / 均可，不做要求，但需要保持一致，比如调用路径用了/ws/geocoder/v1，签名计算的时候也要用/ws/geocoder/v1

b. SecretKey (SK)：在腾讯位置服务控制台 > Key配置中，勾选WebServiceAPI的 SN校验时自动生成的随机字串，用于计算签名（sig）

c. sig：签名计算结果

通过以下示例讲解（本例为调用逆地址解析请求的url）:

https://apis.map.qq.com/ws/geocoder/v1?location=28.7033487,115.8660847&key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-B3FAO-*****

（2）GET请求分为：域名，请求路径和参数三个部分，用于签名计算的有：

请求路径：/ws/geocoder/v1

请求参数：location=28.7033487,115.8660847&key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-B3FAO-*****

a. 首先对参数进行排序：按参数名升序（本例结果为key在前，location在后）：

key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-B3FAO-*****&location=28.7033487,115.8660847

b. 签名计算(sig)：

请求路径+”?”+请求参数+SK进行拼接，并计算拼接后字符串md5值（字符必须为小写），即为签名(sig)：

要求：请求参数必须是未进行任何编码（如urlencode）的原始数据

md5("/ws/geocoder/v1?key=5Q5BZ-5EVWJ-SN5F3-*****&location=28.7033487,115.8660847SWvT26ypwq5Nwb5RvS8cLi6NSoH8HlJX")

本例计算得到结果为：90da272bfa19122547298e2b0bcc0e50

c. 生成最终请求：将计算得到的签名sig，放到请求中（参数名即为：sig）：

https://apis.map.qq.com/ws/geocoder/v1?key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-B3FAO-*****&location=28.7033487,115.8660847&sig=90da272bfa19122547298e2b0bcc0e50

注意：计算 sig 要使用原始参数值，不要进行任何编码，但最终发送时的参数，是需要对接口传入的参数值做url编码的，如果入参中有特殊字符，如：&、#等，需要在请求时在header中增加 x-legacy-url-decode:no

url编码方式：

以地点检索接口位例：
 
请求：...域名省略.../place/v1/search?boundary=region(北京)&keyword=美食

错误方式："...域名省略.../place/v1/search?"+urlencode("boundary=region(北京)&keyword=美食")
 
正确方式："...域名省略.../place/v1/search?boundary="+urlencode("region(北京)")+"&keyword="+urlencode("美食"）

注：示例中的urlencode()代表url编码函数，不同开发语言的存在不同，以您实际为准

5、WebServiceAPI和地点云API 的 POST接口（application/json）如何计算签名？

（1）通用概念：

a. 请求路径：调用接口时的路径，如：/place_cloud/data/create，末尾是否带 / 均可，不做要求

b. SecretKey (SK)：在腾讯位置服务控制台 > Key配置中，勾选WebServiceAPI的 SN校验时自动生成的随机字串，用于计算签名（sig）

c. sig：签名计算结果

（2）下文以地点云API的 [创建地点数据接口] 为例计算签名:

// POST请求地址
        https://apis.map.qq.com/place_cloud/data/create    
        // 请求头：content-type:application/json
         
        //Post方法提交数据
        {
          "key":"5Q5BZ-5EVWJ-SN5F3-K6QBZ-*****",
          "table_id":"5d405395d230bf1*****",
          "data":[
            {
              "ud_id":"156985",
              "title":"海淀区苏州街营业部",
              "location":{
                "lat":39.983988,
                "lng":116.307709
              },
              "x":{
                "price":15.5
              }
            }
          ]
        }

a. 参数排序：按JSON对象中的一级属性名字符升序排序，本例结果为：data,key,table_id

再将每个一级属性的 Value 转成最短JSON string形式：

data	[{“ud_id”:“156985”,“title”:“海淀区苏州街营业部”,“location”:{“lat”:39.983988,“lng”:116.307709},“x”:{“price”:“no price”}}]
key	5Q5BZ-5EVWJ-SN5F3-K6QBZ-*****
table_id	5d405395d230bf1d*****

b. 拼接成Querystring型的字符串：

data=[{"ud_id":"156985","title":"海淀区苏州街营业部","location":{"lat":39.983988,"lng":116.307709},"x":{"price":15.5}}]&key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-*****&table_id=5d405395d230bf1d9416be10

c. 签名计算(sig)：

请求路径+”?”+请求参数+SK进行拼接，并计算拼接后字符串md5值（字符必须为小写），即为签名(sig)：

要求：请求参数必须是未进行任何编码（如urlencode）的原始数据

md5('/place_cloud/data/create?data=[{"ud_id":"156985","title":"海淀区苏州街营业部","location":{"lat":39.983988,"lng":116.307709},"x":{"price":15.5}}]&key=5Q5BZ-5EVWJ-SN5F3-K6QBZ-*****&table_id=5d405395d230bf1d94******KIpUE64TiqLuF2vBJCLOvkFVy0we0Ypp')

本例计算得到结果为：782f2ca97e6592741049823787203e9c

d. 发送请求：

//URL与请求头
POST /place_cloud/data/create?sig=782f2ca97e6592741049823787203e9c HTTP/1.1
Host: sdkgw.noscan.sparta.html5.qq.com
User-Agent: python-requests/2.22.0
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Content-Length: 257
Content-Type: application/json
 
//Post Body
{
  "key": "5Q5BZ-5EVWJ-SN5F3-K6QBZ-B3FAO-******",
  "table_id": "5d405395d230bf1*****",
  "data": [{
    "ud_id": "156985", 
    "title": "\u6d77\u6dc0\u533a\u82cf\u5dde\u8857\u8425\u4e1a\u90e8",
    "location": {"lat": 39.983988, "lng": 116.307709},
    "x": {"price": 15.5}
  }]
}

发送的data里的JSON并不需要是最小形式，可以使用空格。

e. 返回结果：

{
  'status': 0,
  'message': '成功',
  'request_id': 'a98aec8aa0de7a2905ad347d85b188', 
  'result': {
    'count': 1,
    'failure': [], 
    'success': [
      {
      'id': '5d405d2918d433170478b790',
      'row_idx': 0, 
      'ud_id': '156985'
      }
    ]
  }
}

6、WebServiceAPI和地点云API 的接口返回签名失败如何排查？

接口验签失败大概率是您的md5加密方式错误，可通过接口md5加密工具验证，结合如下进行排查：
(1) md5加密前的拼接串儿是否有按照参数名称首字母排序(a-z)，根据接口的字段名进行排序，如首字母一致则向后顺位从第二个字母做比较，以此类推。
(2) md5加密前的拼接串儿参数与实际发起请求的参数是否一致，每次接口参数发生变更，都需要重新进行md5加密获取新的sig。
(3) md5加密的参数是否是原始未进行编码的参数。
(4) 对应key 的 Secret key 是否发生变更，可在控制台中进行查看。