关于我们About

    API参考

    DNS.jpg

    DNS.png

    API参考

    简介

    概述

    百度对象存储BOS(Baidu Object Storage),是百度开放云对外提供的稳定、安全、高效以及高扩展存储服务,支持文本、多媒体、二进制等任何类型的数据存储。数据多地域跨集群的存储,以实现资源统一利用,降低使用难度,提高工作效率。用户可以通过本文档提供的简单的REST API接口,进行数据上传和下载等操作。

    接口概览

    本节汇总了内容分发网络CDN可调用 API,具体接口信息请点击链接查看详细内容。

    域名操作接口

    接口 描述
    域名操作接口 域名列表查询、创建、启用、停用、删除加速域名。
    域名配置接口 查询加速域名详情、更新加速域名回源地址、SEO开关属性的查询与设置、缓存过期规则的查询与设置、缓存参数过滤规则,访问Referer控制、访问IP控制、限速、HTTPS加速、访问鉴权和协议跟随回源功能的设置。
    统计接口 pv/qps、带宽&流量、回源流量、字节命中率、状态码统计、TopN url、TopN referer、域名uv请求量和平均速率记录。
    缓存管理接口 刷新缓存、查询刷新状态、预加载缓存、查询预加载状态及查询用户当前的限额(Quota)值。
    日志接口 本接口用于获取某一个域名某一指定时间段内的日志下载地址。
    工具接口 本接口包含IP检测,用于验证指定的IP是否属于百度开放云CDN服务节点。

    产品限制

    目前产品仅白名单开放/在每个区域最多创建20个实例/一个A实例最多绑定5个B实例/等等

    通用说明

    实名认证(分配写作)

    百度云提供个人认证、企业认证两种认证方式,您可以选择任意一种方式进行认证。

    认证机制(分配写作)

    所有API的安全认证一律采用Access Key与请求签名机制。 Access Key由Access Key ID和Secret Access Key组成,均为字符串。 对于每个HTTP请求,使用下面所描述的算法生成一个认证字符串。提交认证字符串放在Authorization头域里。服务端根据生成算法验证认证字符串的正确性。 认证字符串的格式为bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}

    • version是正整数。
    • timestamp是生成签名时的UTC时间。
    • expirationPeriodInSeconds表示签名有效期限。
    • signedHeaders是签名算法中涉及到的头域列表。头域名之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。(本API签名仅使用host和x-bce-date两个header)
    • signature是256位签名的十六进制表示,由64个小写字母组成。

    当百度云接收到用户的请求后,系统将使用相同的SK和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。鉴权认证机制的详细内容请参见鉴权认证机制

    通信协议(分配写作)

    支持HTTP和HTTPS两种调用方式。为了提升数据的安全性,建议通过HTTPS调用。

    请求结构说明

    数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。

    请求参数包括如下4种:

    参数类型 说明
    URI 用于指明操作实体,如:PUT /v1/cluster/{clusterUuid}
    Query参数 URL中携带的请求参数
    HEADER 通过HTTP头域传入,如:x-bce-date
    RequestBody 通过JSON格式组织的请求数据体

    响应结构说明

    响应值分为两种形式:

    响应内容 说明
    HTTP STATUS CODE 如200,400,403,404等
    ResponseBody JSON格式组织的响应数据体

    版本号(分配写作)

    参数 类型 参数位置 描述 是否必须
    version String URI参数 API版本号 必须

    幂等性 (分配写作)

    当调用创建接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过clientToken参数避免创建出比预期要多的资源,即保证请求的幂等性。

    幂等性基于clientToken,clientToken是一个长度不超过64位的ASCII字符串,通常放在query string里,如http://bcc.bj.baidubce.com/v1/instance?clientToken=be31b98c-5e41-4838-9830-9be700de5a20

    如果用户使用同一个clientToken值调用创建接口,则服务端会返回相同的请求结果。因此用户在遇到错误进行重试的时候,可以通过提供相同的clientToken值,来确保只创建一个资源;如果用户提供了一个已经使用过的clientToken,但其他请求参数(包括queryString和requestBody)不同甚至url Path不同,则会返回IdempotentParameterMismatch的错误代码。

    clientToken的有效期为24小时,以服务端最后一次收到该clientToken为准。也就是说,如果客户端不断发送同一个clientToken,那么该clientToken将长期有效。

    日期与时间

    日期与时间的表示有多种方式。为统一起见,除非是约定俗成或者有相应规范的,凡是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秒。

    规范化字符串

    通常一个字符串中可以包含任何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

    xxx产品编码要求(分配写作)

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

      • Objectname,其中,Resource做UrlEncode的时候需要忽略“/”。
      • Querystring的Value。
      • x-bce-copy-source(忽略“/”)。
      • 自定义Meta:Meta Value只支持可见的ASCII字符,如果需要其它的字符,推荐使用UrlEncode处理。

    API调用举例(从API参考中独立出来,分配写作)

    服务域名

    区域 服务端点Endpoint 协议
    北京 bcc.bj.baidubce.com HTTP and HTTPS
    广州 bcc.gz.baidubce.com HTTP and HTTPS
    苏州 bcc.su.baidubce.com HTTP and HTTPS

    公共请求头与公共响应头

    公共请求头

    头域 说明 是否必须
    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-if-match 同If-Match语义。 可选
    x-bce-if-none-match 同If-None-Match语义。 可选

    公共响应头

    头域 说明
    Content-Length RFC2616中定义的HTTP请求内容的类型。
    x-bce-request-id 对应请求的requestId。

    错误码

    错误码格式

    当用户访问API出现错误时,会返回给用户相应的错误码和错误信息,便于定位问题,并做出适当的处理。请求发生错误时通过Response Body返回详细错误信息,遵循如下格式:

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

    例如:

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

    公共错误码

    错误码 错误消息 HTTP状态码 描述
    AccessDenied Access denied. 403 Forbidden 无权限访问对应的资源。
    InappropriateJSON The JSON you provided was well-formed and valid, but not appropriate for this operation. 400 Bad Request 请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。出于兼容性考虑,对于所有无法识别的项应直接忽略,不应该返回这个错误。
    InternalError We encountered an internal error. Please try again. 500Internal Server Error 所有未定义的其他错误。在有明确对应的其他类型的错误时(包括通用的和服务自定义的)不应该使用。
    InvalidAccessKeyId The Access Key ID you provided does not exist in our records. 403 Forbidden Access Key ID不存在。
    InvalidHTTPAuthHeader The HTTP authorization header is invalid. Consult the service documentation for details. 400 Bad Request Authorization头域格式错误。
    InvalidHTTPRequest There was an error in the body of your HTTP request. 400 Bad Request HTTP body格式错误。例如不符合指定的Encoding等。
    InvalidURI Could not parse the specified URI. 400 Bad Request URI形式不正确。例如一些服务定义的关键词不匹配等。对于ID不匹配等问题,应定义更加具体的错误码,例如NoSuchKey。
    MalformedJSON The JSON you provided was not well-formed. 400 Bad Request JSON格式不合法。
    InvalidVersion The API version specified was invalid. 404 Not Found URI的版本号不合法。
    OptInRequired A subscription for the service is required. 403 Forbidden 没有开通对应的服务。
    PreconditionFailed The specified If-Match header doesn't match the ETag header. 412 Precondition Failed 详见ETag。
    RequestExpired Request has expired. Timestamp date is XXX. 400 Bad Request 请求超时。XXX要改成x-bce-date的值。如果请求中只有Date,则需要将Date转换为datetime。
    IdempotentParameterMismatch The request uses the same client token as a previous, but non-identical request. 403 Forbidden clientToken对应的API参数不一样。
    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. 400 Bad Request Authorization头域中附带的签名和服务端验证不一致。

    CFS错误码

    错误码 错误消息 HTTP状态码 描述
    InstanceNotFound The specified CFS instance does not exist. 404 指定的CFS实例不存在。
    RealNameAuthenticationRequired You need to pass real-name authentication. 403 当前用户未通过实名认证。
    QuotaExceeded You have exceeded current quota. 413 CFS数量超过用户配额限制。
    InstanceCreationFailed Fail to create CFS instance. 400 创建CFS实例失败,通常是由于资源不足,用户金额不足等。
    MissingParameter A required parameter 'parameterName' is not supplied. 400 该请求缺少必要的参数“parameterName”。
    InvalidParameter The parameter 'parameterName' is invalid. 400 "parameterName"参数不合法。
    RedirectPortNotFound The specified redirect port does not exist. 404 指定的HTTPS监听器不存在。
    CertificateNotFound The specified certificate does not exist. 404 指定的证书不存在。

    Bucket相关接口

    GetSessionToken接口

    
<!-----------请求示例 -->
 
<!-----------响应示例 -->

    接口描述

    列举请求者拥有的所有bucket。

    权限说明

    请求发起人需要具有合法的AccessKeyID和SecretAccessKey才能发起请求,请参考 鉴权认证

    注意事项

    如果请求中没有用户验证信息(即匿名访问),返回403 Forbidden,错误信息:AccessDenied

    请求结构

    OPTIONS /<ObjectKey> HTTP/1.1
    Host: <BucketName>.bj.bcebos.com
    Origin: Origin
    Access-Control-Request-Method: HTTPMethod
    Access-Control-Request-Headers: RequestHeader

    请求头域

    除公共头域外,无其它特殊头域。

    头域 类型 说明 是否必须
    Origin String 请求来源域,用来标识跨域请求,只允许一个方法。类型:字符串。默认值:无。 必须
    Access-Control-Request-Method String 在实际请求中将会用到的方法,只允许一个方法。类型:字符串。取值为“PUT/GET/DELETE/POST/HEAD”,无默认值。 必须
    Access-Control-Request-Headers String 在实际请求中会用到的除了简单头部之外的Headers,多个headers用逗号分割。类型:字符串。默认值:无。 必须

    请求参数

    无。

    名称 类型 描述 是否必须
    storageClass String 指定Bucket的默认存储类型,STANDRAD代表标准存储,STANDARD_IA代表低频存储,COLD代表冷存储。 必须

    响应头域

    除公共头域外,无其它特殊头域。

    头域 类型 说明
    ETag String Object的HTTP协议实体标签

    响应参数

    无。

    名称 类型 描述
    vpc ShowVpcModel VPC实体

    请求示例

    说明:一次请求最多返回100个bucket的信息。

    GET / HTTP/1.1
    Host: bj.bcebos.com
    Date: Wed, 06 Apr 2016 06:34:40 GMT
    Authorization: AuthorizationString

    响应示例

    ```
    HTTP/1.1 200 OK     
     x-bce-request-id: 1214cca7 4ad5 451d 9215 71cb844c0a50     
     Date: Thu, 16 Mar 2017 06:29:48 GMT
     ETag: "1b2cf535f27731c974343645a3985328"       
     Content Type: application/json;charset=UTF 8     
     Server: BWS     
          
    {   
        "vpc": {
            "vpcId': "vpc-IyWRtII7",
            "name": u"\u9ed8\u8ba4\u79c1\u6709\u7f51\u7edc",
            "isDefault": True,
            "cidr": "0.0.0.0/0",
            "description": "default",
            "subnets": [
    	        {
    	          "name": "系统预定义子网",
                	"subnetId": "sbn-IyWRnII7",
                	"zoneName": "cn-bj-a",
                	"cidr": "192.168.0.0/20",
                	"vpcId": "vpc-IyrqYIQ7",
                	"subnetType": "BCC",
                	"description": ""
    	        }
        	]
        }   
    }    
    ```

    数据类型

    Model对象定义

    ShowVpcModel

    参数名称 类型 描述
    vpcId String vpc的id
    name String 名称
    cidr String 网段及子网掩码
    description String 描述
    isDefault Boolean 是否为默认VPC,true:是;false:否
    subnets List<Subnet> VPC中包含的子网

    Subnet

    参数名称 类型 描述
    subnetId String 子网id
    name String 子网名称
    zoneName String 可用区名称
    cidr String 子网cidr
    vpcId String 子网所属vpc的id
    subnetType String 子网类型,"BCC”、”BBC”
    description String 描述

    功能更新记录

    2017-12-27

    • 支持上传下载进度回调接口

      主机创建成功后,系统会分配一套默认的运行环境、参数和配置,您可以直接使用系统默认的环境配置进行网站调测,无需手动配置。

    上一篇
    关于我们