附录

附录1:错误码说明

以下列表为鹰眼错误码,为鹰眼 Android SDK、iOS SDK、Web 服务 API 所公用。除鹰眼错误码外,其他通用控制服务错误码请见通用控制服务错误码定义

status 状态码 message 描述信息 注释
0 成功 请求成功
1 服务器内部错误 该服务响应超时或系统内部错误
2 参数错误 具体错误信息将在 message 中给出
3 http method错误 检查请求的 http method(GET/POST)是否与接口描述一致
3003 指定 entity 不存在 未查询到 entity_name 为设定值的 entity,请检查 entity_name 是否输入错误或已被删除
3005 entity_name已存在 entity_name 是 entity 的唯一标识,在同一 service 中不可创建 entity_name 重复的 entity,请更换名字后再次尝试
3006 查询时间段内的轨迹点过多,无法进行纠偏,请缩短查询时间 entity_name不符合命名规范:仅支持中文、英文大小字母、英文下划线"_"、英文横线"-"和数字。
3007 数据解析失败,数据中包含非utf8编码字符 返回的字段值中存在非 utf8编码的字符。所有上传的字符均应以 utf8 编码
3100 loc_time 不可晚于当前服务端时间10分钟以上,即不支持上传未来的轨迹点 上传轨迹点时,不可上传未来的点,建议检查设备时间是否设置正确
3101 上传轨迹点数量太大 批量上传轨迹点时,一次请求最多上传100个轨迹点
3200 起止时间差不可超过24小时 查询轨迹或里程时,起止时间差不可超过24小时
3201 结束时间不可小于开始时间 查询轨迹或里程时,结束时间不可小于开始时间
5101 监控对象的围栏个数超出范围,最多100个 一个监控对象最多可创建100个围栏,建议定期清理无效围栏
5102 监控对象不存在 创建或更新围栏时,指定的监控对象 entity_name 不存在
5103 监控对象上没有fence_id为XXX的围栏
5104 指定fence_id不存在
9001 查询时间段内的轨迹点过多,无法进行轨迹分析,请缩短查询时间 一次请求查询的轨迹点不可超过两万,否则将返回失败

附录2:编码说明

API请求中需要用到中文或一些特殊字符的参数,为了避免提交到后台乱码,需要对这几个 参数值进行编码处理,转换成UTF-8字符的二字符十六进制值,凡是不在下表中的字符都需要进行编码。

字符集合 字符
URL非保留字 a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 - _ . ~
URL保留字 ! * ' ( ) ; : @ & = + $ , / ? % # [ ]

如果参数值中使用URL保留字字符的字面意思,例如,检索关键字包含一个问号,此问号也必须进行编码。

附注:

javascript中一般采用encodeURIComponent函数对特殊字符进行编码。

Java中可以使用函数URLEncoder.encode对特殊字符进行编码。

C#中可以使用函数HttpUtility.UrlEncode对特殊字符进行编码。

php中可以使用函数urlencode对特殊字符进行编码。

注:只需要对请求中的参数值做编码处理

附录3:sn计算算法

sn计算主要分为以下几个步骤:


1. 按顺序对所有参数值做URLEncode处理,以"key1=value1&key2=value2..."的形式拼接到一起生成字符串paramStr; (注:GET请求参数的顺序可以自定义,POST请求参数必须按字母a-z顺序)


2. 使用URL中域名之后参数之前的部分(如:"/geocoder/v2/?" 或 "/api/v3/track/gettrack?")加上paramStr再加上你的sk拼接成字符串wholeStr;


3. 对wholeStr整体做一次URLEncode处理,得到tempStr;


4. 使用MD5方法对tempStr计算得到最终的sn签名字符串snStr;


5. 在请求原有已编码的参数最后增加一个参数sn=snStr,发起http/https请求。如果是GET请求,最终的请求串应该是:

"api.map.baidu.com" + "/geocoder/v2/?" + paramStr + "&sn=" + snStr

鹰眼v3请求: "yingyan.baidu.com" + "/api/v3/track/gettrack?" + paramStr + "&sn=" + snStr

POST请求同理,把参数sn放到原有已编码的参数最后,拼装请求发送。


代码示例:

假设ak=yourak(yourak为一个字符串),在 API控制台 中配置了该ak的验证方式是sn签名的验证方式,点击下面那排星号,显示Security Key,可以看到此ak对应的sk私钥,假设sk=yoursk。

请求的url是:http://api.map.baidu.com/geocoder/v2/?address=百度大厦&output=json&ak=yourak&sn=7de5a22212ffaa9e326444c75a58f9a0

后面的sn就是要计算的,sk不需要在url里出现,但是在计算sn的时候需要sk(假设sk=yoursk)


下面提供java、PHP、C#、python 2.7的参考代码。


java参考代码如下:

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.security.NoSuchAlgorithmException;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Map.Entry;
 
/**
 * java版计算signature签名
 */
public class SnCal {
    public static void main(String[] args) throws UnsupportedEncodingException, NoSuchAlgorithmException {
        SnCal snCal = new SnCal();
 
        // 计算sn跟参数对出现顺序有关,get请求请使用LinkedHashMap保存<key,value>,该方法根据key的插入顺序排序;post请使用TreeMap保存<key,
        // value>,该方法会自动将key按照字母a-z顺序排序。所以get请求可自定义参数顺序(sn参数必须在最后)发送请求,但是post请求必须按照字母a-z顺序填充body(sn参数必须在最后)。以get
        // 请求为例:http://api.map.baidu.com/geocoder/v2/?address=百度大厦&output=json&ak=yourak,paramsMap中先放入address
        // ,再放output,然后放ak,放入顺序必须跟get请求中对应参数的出现顺序保持一致。
        Map paramsMap = new LinkedHashMap<String, String>();
        paramsMap.put("address", "百度大厦");
        paramsMap.put("output", "json");
        paramsMap.put("ak", "yourak");
 
        // 调用下面的toQueryString方法,对LinkedHashMap内所有value作utf8编码,拼接返回结果address=%E7%99%BE%E5%BA%A6%E5%A4%A7%E5%8E%A6
        // &output=json&ak=yourak
        String paramsStr = snCal.toQueryString(paramsMap);
 
        // 对paramsStr前面拼接上/geocoder/v2/?,后面直接拼接yoursk得到/geocoder/v2/?address=%E7%99%BE%E5%BA%A6%E5%A4%A7%E5%8E%A6
        // &output=json&ak=yourakyoursk
        String wholeStr = new String("/geocoder/v2/?" + paramsStr + "yoursk");
 
        // 对上面wholeStr再作utf8编码
        String tempStr = URLEncoder.encode(wholeStr, "UTF-8");
 
        // 调用下面的MD5方法得到最后的sn签名7de5a22212ffaa9e326444c75a58f9a0
        String snStr = snCal.MD5(tempStr);
        System.out.println(snStr);
        String requestUrl = new String("http://api.map.baidu.com/goecoder/v2/?" + paramsStr + "&sn=" + snStr);
        System.out.println(requestUrl);
    }
 
    // 对Map内所有value作utf8编码,拼接返回结果
    public String toQueryString(Map<?, ?> data)
            throws UnsupportedEncodingException {
        StringBuffer queryString = new StringBuffer();
        for (Entry<?, ?> pair : data.entrySet()) {
            queryString.append(pair.getKey() + "=");
            queryString.append(URLEncoder.encode((String) pair.getValue(),
                    "UTF-8") + "&");
        }
        if (queryString.length() > 0) {
            queryString.deleteCharAt(queryString.length() - 1);
        }
        return queryString.toString();
    }
 
    // 来自stackoverflow的MD5计算方法,调用了MessageDigest库函数,并把byte数组结果转换成16进制
    public String MD5(String md5) {
        try {
            java.security.MessageDigest md = java.security.MessageDigest
                    .getInstance("MD5");
            byte[] array = md.digest(md5.getBytes());
            StringBuffer sb = new StringBuffer();
            for (int i = 0; i < array.length; ++i) {
                sb.append(Integer.toHexString((array[i] & 0xFF) | 0x100)
                        .substring(1, 3));
            }
            return sb.toString();
        } catch (java.security.NoSuchAlgorithmException e) {
        }
        return null;
    }
}


PHP参考代码如下:

<?php
 
//API控制台申请得到的ak(此处ak值仅供验证参考使用)
$ak = 'yourak';
 
//应用类型为for server, 请求校验方式为sn校验方式时,系统会自动生成sk,可以在应用配置-设置中选择Security Key显示进行查看(此处sk值仅供验证参考使用)
$sk = 'yoursk';
 
//以Geocoding服务为例,地理编码的请求url,参数待填
$url = "http://api.map.baidu.com/geocoder/v2/?address=%s&output=%s&ak=%s&sn=%s";
 
//get请求uri前缀
$uri = '/geocoder/v2/';
 
//地理编码的请求中address参数
$address = '百度大厦';
 
//地理编码的请求output参数
$output = 'json';
 
//构造请求串数组
$querystring_arrays = array (
	'address' => $address,
	'output' => $output,
	'ak' => $ak
);
 
//调用sn计算函数,默认get请求
$sn = caculateAKSN($ak, $sk, $uri, $querystring_arrays);
 
//请求参数中有中文、特殊字符等需要进行urlencode,确保请求串与sn对应
$target = sprintf($url, urlencode($address), $output, $ak, $sn);
 
//输出计算得到的sn
echo "sn: $sn \n";
 
//输出完整请求的url(仅供参考验证,故不能正常访问服务)
echo "url: $target \n";
?>


其中,caculateAKSN的定义如下:

function caculateAKSN($ak, $sk, $url, $querystring_arrays, $method = 'GET')
{  
    if ($method === 'POST'){  
        ksort($querystring_arrays);  
    }  
    $querystring = http_build_query($querystring_arrays);  
    return md5(urlencode($url.'?'.$querystring.$sk));  
}


C#参考代码如下:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
 
 
    public class AKSNCaculater
    {
       private static string MD5(string password)
       {
           byte[] textBytes = System.Text.Encoding.UTF8.GetBytes(password);
           try
           {
               System.Security.Cryptography.MD5CryptoServiceProvider cryptHandler;
               cryptHandler = new System.Security.Cryptography.MD5CryptoServiceProvider();
               byte[] hash = cryptHandler.ComputeHash(textBytes);
               string ret = "";
               foreach (byte a in hash)
               {
                   ret += a.ToString("x2");
               }
               return ret;
           }
           catch
           {
               throw;
           }
       }
 
       private static string UrlEncode(string str)
       {
           str = System.Web.HttpUtility.UrlEncode(str);
           byte[] buf = Encoding.ASCII.GetBytes(str);//等同于Encoding.ASCII.GetBytes(str)
           for (int i = 0; i < buf.Length; i++)
               if (buf[i] == '%')
               {
                   if (buf[i + 1] >= 'a') buf[i + 1] -= 32;
                   if (buf[i + 2] >= 'a') buf[i + 2] -= 32;
                   i += 2;
               }
           return Encoding.ASCII.GetString(buf);//同上,等同于Encoding.ASCII.GetString(buf)
       }
 
       private static string HttpBuildQuery(IDictionary<string, string> querystring_arrays)
       {
 
           StringBuilder sb = new StringBuilder();
           foreach (var item in querystring_arrays)
           {
               sb.Append(UrlEncode(item.Key));
               sb.Append("=");
               sb.Append(UrlEncode(item.Value));
               sb.Append("&");
           }
           sb.Remove(sb.Length - 1, 1);
           return sb.ToString();
       }
 
       public static string CaculateAKSN(string ak, string sk, string url, IDictionary<string, string> querystring_arrays)
       { 
           var queryString = HttpBuildQuery(querystring_arrays);
 	  // url为域名之后,参数之前的部分(不带问号), 如/geocoder/v2/  
           var str = UrlEncode(url + "?" + queryString + sk); 
 
           return MD5(str);
       }
    }


python 2.7参考代码如下:

# -*- coding: utf-8 -*-
# 第一行必须有,否则报中文字符非ascii码错误
import urllib
import hashlib
 
# 以 GET 请求为例
uri = '/geocoder/v2/?'
queryStr = 'address=百度大厦&output=json&ak=yourAK'
# 对queryStr进行转码,safe内的保留字符不转换
paramsStr = urllib.quote(queryStr, safe="/:=&?#+!$,;'@()*[]")
 
# 在最后直接追加上yoursk
wholeStr = uri + paramsStr + 'yourSK'
tempStr = urllib.quote_plus(wholeStr);
# md5计算出的sn值7de5a22212ffaa9e326444c75a58f9a0
snStr = hashlib.md5(tempStr).hexdigest()
# 最终合法请求url是http://api.map.baidu.com/geocoder/v2/?address=%E7%99%BE%E5%BA%A6%E5%A4%A7%E5%8E%A6&output=json&ak=yourAK&sn=7de5a22212ffaa9e326444c75a58f9a0
requestStr = 'http://api.map.baidu.com' + uri + paramsStr + '&sn=' + snStr
print requestStr