云观测开放API - 基本规范

URL

URL的格式为:https://api.su.baidu.com/{version}/ygc/{resouce}/{id}/

  • version: 是指所使用的API版本,当前为v1
  • resource:要操作的对象名称,例如site、task、alert等
  • 操作单个object的时候 需要提供id

HTTP Method

  • GET:读取一个或多个资源,如果url中提供id则读取一个,否则列出多个
  • POST:添加或创建一个资源,成功后返回资源id
  • PUT:修改资源,需要在参数中指定修改的字段和值
  • DELETE:删除资源,必须在url中指定id

附加请求头:

  • X-HTTP-Method-Override:为了兼容不支持PUT和DELETE的场景,对于HTTP method需要一种新的设置方法。通过指定HTTP请求头 X-HTTP-Method-Override 来重新声明HTTP method,例如:以指定 X-HTTP-Method-Override 为 DELETE 的POST请求来代替DELETE请求,以指定 X-HTTP-Method-Override 为 PUT 的POST请求来代替PUT请求

  • X-Auth-Access-Key:申请到的Access Key
  • X-Auth-Nonce:随机字符串,32位
  • X-Auth-Path-Info:当前请求的资源路径
  • X-Auth-Signature-Method:签名方式,为'HMAC-SHA1'
  • X-Auth-Timestamp:签名生成时的时间戳
  • X-Auth-Sign:生成的签名
  • X-User-Id:第三方合作商用户ID,整数,“站点管理”、“任务管理”、“告警管理”的所有API请求都必须带上这个字段。
  • X-User-Type:第三方合作商用户的类型,支持两种取值 uc 或 passport,如果未提供该参数,则表示X-User-Id非passport或uc用户

请求身份认证

云观测OpenAPI对于每个请求都会先进行身份认证,校验签名X-Auth-Sign是否合法。

  1. 合作商在接入云观测OpenAPI之前,需要先申请Access Key、Secret Key密钥对。申请入口见这里注:云观测OpenAPI的身份认证系统与百度云加速共用,因此见到申请入口在百度云加速官网时,请不要惊讶
  2. 获得Access Key、Secret Key后,根据后面“签名算法说明”一节的文档,在每次API请求前生成签名,并在请求中携带签名及其他必要信息,这里需要强调的是:获得的Secret Key只用于生成签名,但一定不要放入API请求中

响应格式:

  • 返回多条数据项
{
    "request_id": "xxx", // 请求的唯一性标识
    "success": true, // 请求是否成功,true/false
    // 错误信息列表
    "errors": [
        {
            "code": 404,    // 错误码
            "message":      // 错误信息
        }
    ],
    "messages": [],
    "result": {
        "total_page": xxx,
        "result": [
            {
                "xxx": "xxx",
                ...
            },
            ...
        ]
    }
}
  • 返回单条数据
{
    "request_id": "xxx", // 请求的唯一性标识
    "success": true, // 请求是否成功,true/false
    // 错误信息列表
    "errors": [
        {
            "code": 404,    // 错误码
            "message":      // 错误信息
        }
    ],
    // 信息列表
    "messages": [],
    "result": {
        "xxx": "xxx",
        ...
    }
}

注:对于错误响应,可不带result字段

响应码表:

200 成功
201 创建成功

404 资源不存在
423 缺少必要的请求参数
425 请求参数不正确
426 已经存在相同的资源
427 站点数量限制
428 站点验证失败
429 网站无法访问,无法监测该网站

500 系统异常

签名算法说明

API请求样例

以下是使用curl工具生成请求:

curl "https://api.su.baidu.com/v1/ygc/site"\
-H "X-Auth-Access-Key: 4ec3b3e19bb044c3b7451192cc099dc3"\
-H "X-Auth-Nonce:mdfzr2txy3dx8cpsop1ktbdfg0empqg0"\
-H "X-Auth-Path-Info:v1/ygc/site"\
-H "X-Auth-Signature-Method:HMAC-SHA1"\
-H "X-Auth-Timestamp:1416907901"\
-H "X-Auth-Sign:+fKMGAbP9/LJ+XSgbWRA1Bzx2ZA="\
-H "X-User-Id:414123141"

签名方法

1)生成待签名的字符串

对上述样例中的参数(除X-Auth-Sign外),按参数名称升序排列,若首字母相同,则比较第二个字母,以此类推。排序完成之后,再把所有参数值以“&”字符连接起来,如: X-Auth-Access-Key=4ec3b3e19bb044c3b7451192cc099dc3&X-Auth-Nonce=mdfzr2txy3dx8cpsop1ktbdfg0empqg0&X-Auth-Path-Info=v1/ygc/site&X-Auth-Signature-Method=HMAC-SHA1&X-Auth-Timestamp=1416907901&X-User-Id=414123141 此字符串便是“API请求样例”的待签名字符串。

注意事项:

根据HTTP协议要求,参数值中若存在特殊字符(如&、@等),则该值需要按URL Encoding规则进行编码。但需要注意的是,待签名数据应该是该参数的原生值而不是encoding之后的值。例如,调用某接口需要对请求参数email进行数字签名,那么待签名字符串应该是email=test@msn.com,而不是email=test%40msn.com。

2)计算“待签名字符串”的签名

  1. 将API密钥对中的SecretKey作为key,生成被签名字符串的HMAC-SHA1 签名(RFC2104);
  2. 将签名进行 Base64 编码;
  3. 将编码后的结果设置成参数X-Auth-Sign的值。

签名算法示例(Python版本):

def build_sign(secret_key, params):
    '''通过HMAC-SHA1构造签名串
    Args:
        secret_key: HMAC-SHA1所使用的key
        params: 待签名的参数dict'''
    try:
        ks = params.keys()
        ks.sort()
        base_str = '&'.join(['%s=%s' % (k, str(params[k])) for k in ks]) 
        return base64.b64encode(hmac.new(str(secret_key), base_str, sha1).digest())
    except Exception as e:
        import traceback 
        print traceback.format_exc()
        return None

def build_headers(access_key, secret_key, path, get_params={}, post_params={}):
    '''根据请求参数构建包含鉴权参数的请求Header
    Args:
        access_key: ak
        secret_key: sk
        get_params: 业务相关的GET参数
        post_params: 业务相关的POST参数
        view_params: url中的restful参数
    Returns:
        params: 添加了鉴权相关参数,并且签名过的参数'''
    headers = {}
    headers['X-Auth-Access-Key'] = access_key
    headers['X-Auth-Timestamp'] = str(int(time.time()))
    headers['X-Auth-Signature-Method'] = 'HMAC-SHA1'
    headers['X-Auth-Nonce'] = utils.randstr(32)
    all_params = {}
    all_params.update(get_params)
    all_params.update(post_params)
    all_params.update(headers)
    all_params['X-Auth-Path-Info'] = path.strip('/')
    auth_sign = build_sign(secret_key, all_params)
    headers['X-Auth-Sign'] = auth_sign
    return headers

调用示例:

method = 'post'
ak = your_access_key
sk = your_secret_key
url = 'http://www.apiserver.com/users/'
path = 'users'
get_params = {}
post_params = {"auth_userid": "5y1sesn8ph"}
headers = build_headers(ak, sk, path, get_params, post_params)
'''
     headers = {
    'X-Auth-Access-Key': 'd7a559051ee0456f9397f78c0b90d747',
    'X-Auth-Signature-Method': 'HMAC-SHA1',
    'X-Auth-Sign': 'Xi8JGn7gFTAWw/8oGibC0vioqMk=',
    'X-Auth-Nonce': 'eq2d8qosy5nape7r13qhaykotrsgq0r6',
    'X-Auth-Timestamp': '1413440640'}
''' 
resp = requests.request(method, url, params=get_params, data=post, headers=headers)
data = json.loads(resp.text)