调用说明

概述

BCE CDN API接口域名http://cdn.baidubce.com,所有接口统一使用/v2前缀,接口规范遵循BCE标准,采用HTTP协议通信,支持HTTP1.0/1.1。支持HTTP的PUT、POST、GET、DELETE请求方法。

通用约定

编码及数据格式

数据交换格式使用JSON格式,Content-Type为applicaton/json样式,所有request/response body内容均使用UTF-8编码。

日期与时间

日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡是HTTP标准中规定的表示日期和时间字段用GMT,其他日期时间表示的地方一律采用UTC时间,遵循ISO 8601,并做以下约束:

  • 表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。
  • 表示时间一律采用hh:mm:ss方式,并在最后加一个大写字母Z表示UTC时间。例如23:00:10Z表示UTC时间23点0分10秒。
  • 凡涉及日期和时间合并表示时,在两者中间加大写字母T,例如2014-06-01T23:00:10Z表示UTC时间2014年6月1日23点0分10秒。

BCE CDN API与时间相关的数值类型统一采用上述格式,称为Timestamp类型。

规范化字符串

通常一个字符串中可以包含任何Unicode字符。在编程中这种灵活性会带来不少困扰。因此引入“规范字符串”的概念。一个规范字符串只包含百分号编码字符以及URI(Uniform Resource Identifier)非保留字符(Unreserved Characters)。
RFC 3986规定URI非保留字符包括以下字符:字母(A-Z,a-z)、数字(0-9)、连字号(-)、点号(.)、下划线(_)、波浪线(~)。
将任意一个字符串转换为规范字符串的方式是:

  • 将字符串转换成UTF-8编码的字节流。
  • 保留所有URI非保留字符原样不变。
  • 对其余字节做一次RFC 3986中规定的百分号编码(Percent-Encoding),即一个%后面跟着两个表示该字节值的十六进制字母。字母一律采用大写形式。
    示例:
    原字符串:this is an example for 测试
    对应的规范字符串:this%20is%20an%20example%20for%20%E6%B5%8B%E8%AF%95

在请求时,需要对Querystring的Value做UrlEncode,如下所示:

public static String uri-encode(CharSequence input, boolean encodeSlash) {
          StringBuilder result = new StringBuilder()
          for (int i = 0; i < input.length(); i++) {
              char ch = input.charAt(i);
              if ((ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '_' || ch == '-' || ch == '~' || ch == '.') {
                  result.append(ch)
              } else if (ch == '/') {
                  result.append(encodeSlash ? "%2F" : ch)
              } else {
                  result.append(toHexUTF8(ch))
              }
          }
          return result.toString()
}

编码规范

  • 可解析内容,所有request/response body内容目前均使用UTF-8编码,后续会支持更多encoding类型。
  • 在请求时,需要对QueryString的Value做UrlEncode。

公共头

公共请求头域

CDN API服务需要在请求的HTTP头域中包含以下信息:

头域(Header) 说明 是否必须
host http host
Authorization 包含Access Key与请求签名
x-bce-date 该请求创建的时间,表示日期一律采用YYYY-MM-DD方式,例如2014-06-01表示2014年6月1日。如果用户使用了标准的Date域,该头域可以不填。当两者同时存在时,以x-bce-date为准。
x-bce-content-sha256 表示内容部分的SHA256签名的十六进制字符串,其中内容指HTTP Request Payload Body,即Content部分在被HTTP encode之前的原始数据。
x-bce-request-id 用来跟踪调试的Id,为一个uuid字符

公共响应头域

头域(Header) 说明
x-bce-request-id 对应请求的requestId
Content-Type application/json,charset=utf-8。一期编码只支持utf-8,所以charset是固定的。

错误信息格式

BCE CDN API的错误信息除了HTTP状态码以外,在HTTP body中还包JSON格式的错误信息,内容如下:

参数名 类型 说明
requestId String 导致该错误的requestId
code String 表示具体错误类型
message String 有关该错误的详细说明

例如:

{ 
    "code":"IllegalRequestUrl", 
    "message":"The requested url belongs to domain which is not under acceleration",
    "requestId":" 81d0b05f-5ad4-1f22-8068-d5c9de60a1d7" 
}

通用错误码

除了后面各个接口单独列出的错误格式定义以外,BCE CDN API的通用错误码还包含但不限于以下形式:

HTTP Status Code Code Message 说明
400 InvalidArgument Invalid Argument. 无效参数
400 InvalidHTTPAuthHeader The HTTP authorization header is invalid. Consult the service documentation for details. Authorization头域格式错误
400 InvalidHTTPRequest There was an error in the body of your HTTP request. HTTP body格式错误。例如不符合指定的Encoding等
400 MalformedJSON The JSON you provided was not well-formed. JSON格式不合法
403 SignatureDoesNotMatch The request signature we calculated does not match the signature you provided. Check your Secret Access Key and signing method. Consult the service documentation for details. Authorization头域中附带的签名和服务端验证不一致
403 InvalidAccessKeyId The Access Key ID you provided does not exist in our records. Access Key ID不存在
405 MethodNotAllowed he specified method is not allowed against this resource. 请求的方法不允许
500 InternalError We encountered an internal error. Please try again. 未定义的系统错误

签名认证

签名申请步骤

关于AK/SK的获取,请参看获取AK/SK

签名生成算法

百度智能云采用统一的API鉴权认证机制,详情请见鉴权认证机制

省份、运营商格式

地区 映射 运营商 映射
北京 beijing 电信 ct
天津 tianjin 联通 cnc
河北 hebei 移动 cmnet
内蒙古 nmg 教育网 ce
山西 shanxi 鹏博士 pbs
上海 shanghai 广电 oc
安徽 anhui 世纪互联 sjhl
江苏 jiangsu 方正宽带 fdbn
浙江 zhejiang 华数 wasu
山东 shandong 其他 other
福建 fujian
江西 jiangxi
广东 guangdong
广西 guangxi
海南 hainan
河南 henan
湖北 hubei
湖南 hunan
黑龙江 hlj
吉林 jilin
辽宁 liaoning
陕西 shaanxi
甘肃 gansu
宁夏 ningxia
青海 qinghai
新疆 xinjiang
重庆 chongqing
四川 sichuan
云南 yunnan
贵州 guizhou
西藏 xizang
海外 oversea
其他 other