接口规范

请求响应格式标准

  • HTTP请求,Querystring中参数的Key,为首字母小写的驼峰方式。如 upLoadId,partNumber等。

  • 所有用户自定义Meta,以x-bce-meta-*的形式放Header中,自定义Meta总大小不得超过2K。x-bce-meta-*的Key会被Server端统一按照小写进行处理。

例如:用户使用PutObject接口上传了x-bce-meta-DeMo:value,Server端会统一按照小写x-bce-meta-demo:value进行处理,用户在使用GetObject接口时,Sever端的返回值为x-bce-meta-demo:value

  • 除RFC2616规定的标准Header外,其他Header以x-bce-*的形式定义。

  • BOS的RESTful API支持仅支持JSON形式。

  • 所有JSON中,Key均为首字母小写的驼峰方式。

  • 每个请求响应中均带有x-bce-request-idx-bce-debug-id这两个Header。

  • Header中Date、Content-MD5、Content-Type、Content-Length等相关字段遵守RFC 2616约束。

  • 依据HTTP协议的规定,Content-MD5既要做MD5也要进行Base64编码,其计算方法如下:

    Content-MD5 = "Content-MD5" ":" md5-digest
    md5-digest   = <base64 of 128 bit MD5 digest as per RFC 1864>
    

公共请求头

名字 类型 描述
Authorization String 用于验证请求合法性的认证信息。更多参见鉴权认证
Content-Length String RFC2616中定义的HTTP请求内容的长度
Content-Type String RFC2616中定义的HTTP请求内容的类型
Content-MD5 String RFC2616定义的HTTP请求内容的MD5摘要,可以通过携带该字段来验证保存在BOS侧的文件和用户预期的文件是否一致。
Date String HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT
Host String 访问Host值,取值为BucketName.bj.baidubce.com
x-bce-date String 当前时间,遵循ISO8601规范,格式如2016-04-06T08:23:49Z

公共返回头

名字 类型 描述
Content-Length String RFC2616中定义的HTTP请求内容长度。
Content-Type String RFC2616中定义的HTTP请求内容的类型。
Connection String 服务器是否断开连接,取值为close或者keep-alive
Date String HTTP 1.1协议中规定的GMT时间,如Wed, 06 Apr 2016 06:34:40 GMT
ETag String Object的HTTP协议实体标签。ETag (entity tag) 在每个Object生成的时候被创建,用于标识一个Object的内容,ETag值可以用于检查Object内容是否发生变化。
Server String 服务器的名字,取值为BceBos
x-bce-request-id String 由BCE BOS创建,是请求BceBos的唯一标识,
x-bce-debug-id String 由BCE BOS创建,用于帮助排除故障的标识ID,如果在使用BOS过程中遇到问题,可以在工单中提供该字段便于快速定位问题。

低频/冷存储和标准存储API接口的差异

文件的存储类型是基于object实现的,低频存储和冷存储API实现时通过给object增加一个storage class属性来实现。storage class属性值为STANDARD、STANDARD_IA (infrequent access)和COLD,分别代表标准存储、低频存储和冷存储。

以下低频/冷存储API接口增加storage class属性:

  • PutObject、InitiateMultipartUpload、CopyObject、AppendObject、PostObject接口在请求头域中设置storage class属性参数x-bce-storage-class。

    请求头域

    名称 类型 描述 是否必需
    x-bce-storage-class String 指定BOS的对象的存储类型,目前支持STANDARDSTANDARD_IACOLD 否,默认为STANDARD
  • GetObject和GetObjectMeta在响应头域中返回x-bce-storage-class。

    响应头域

    名称 类型 描述
    x-bce-storage-class String BOS的对象的存储类型,目前支持STANDARDSTANDARD_IACOLD
  • ListObjects、ListMultipartUploads和ListParts在响应元素中返回storageClass。

    响应元素

    名称 类型 描述
    storageClass String BOS的对象的存储类型,目前支持STANDARDSTANDARD_IACOLD

错误信息格式

当用户访问BOS出现错误时,BOS会返回给用户相应的错误码和错误信息,便于用户定位问题,并做出适当的处理。

系统返回错误信息格式如下:

{
    "code":"NoSuchKey",
    "message":"The resource you requested does not exist",
    "requestId":" 4db2b34d-654d-4d8a-b49b-3049ca786409"
}

其中Code字段定义如下:

错误码(code) 消息(message) 描述 HTTP状态码
AccessDenied Access denied. 拒绝访问 403 Forbidden
AccountOverdue Your request is denied because there is an overdue bill of your account. 用户欠费 403 Forbidden
BadDigest The Content-MD5 you specified did not match what we received. 错误的Content-MD5字段,与实际上传的数据MD5不符 400 Bad Request
BucketAlreadyExists The requested bucket name is not available. The bucket namespace is shared by all users of the system. Please select a different name and try again. Bucket已经存在 409 Conflict
BucketNotEmpty The bucket you tried to delete is not empty. 试图删除一个不为空的bucket 409 Conflict
EntityTooLarge Your proposed upload exceeds the maximum allowed object size. 上传的数据大于限制 400 Bad Request
EntityTooSmall Your proposed upload is smaller than the minimum allowed object size. 上传的数据小于限制 400 Bad Request
InappropriateJSON The JSON you provided was well-formed and valid, but not appropriate for this operation. 请求中的JSON格式正确,但语义上不符合要求。如缺少某个必需项,或者值类型不匹配等。出于兼容性考虑,对于所有无法识别的项应直接忽略,不应该返回这个错误。 400 Bad Request
InappropriateXML The XML you provided was well-formed and valid, but not appropriate for this operation. 适用场景同InappropriateJSON 400 Bad Request
InternalError We encountered an internal error. Please try again. 所有未定义的其他错误。在有明确对应的其他类型的错误时(包括通用的和服务自定义的)不应该使用。 500 Internal Server Error
InvalidAccessKeyId The Access Key ID you provided does not exist in our records. Access Key ID不存在 403 Forbidden
InvalidArgument Invalid Argument. 无效参数 400 Bad Request
InvalidBucketName The specified bucket is not valid. BucketName不合法 400 Bad Request
InvalidEncryptionAlgorithm The specified encryption algorithm is invalid. 指定的加密算法无效。 400 Bad Request
InvalidHTTPAuthHeader The HTTP authorization header is invalid. Consult the service documentation for details. Authorization头域格式错误 400 Bad Request
InvalidHTTPRequest There was an error in the body of your HTTP request. HTTP body格式错误。例如不符合指定的Encoding等 400 Bad Request
InvalidObjectName Your object key is too long. Object Key过长 400 Bad Request
InvalidPart One or more of the specified parts could not be found. The part might not have been uploaded, or the specified entity tag might not have matched the part's entity tag. 无效的Part,在三步上传的第三步,发现有一些part不存在,或者part ETag不匹配 400 Bad Request
InvalidPartOrder The list of parts was not in ascending order.Parts list must specified in order by part number. 上传的Part必须按照PartNumber升序排列进行上传的第三步 400 Bad Request
InvalidPolicyDocument The content of the form does not meet the conditions specified in the policy document. Policy格式错误 400 Bad Request
InvalidRange The requested range cannot be satisfied. 请求的Range不合法 416 Requested Range Not Satisfiable
InvalidURI Could not parse the specified URI. URI形式不正确 400 Bad Request
MalformedJSON The JSON you provided was not well-formed. JSON格式不合法 400 Bad Request
MalformedXML The XML you provided was not well-formed or did not validate against our published schema. XML格式不合法 400 Bad Request
MaxMessageLengthExceeded Your request was too big. 超出消息长度的限制 400 Bad Request
MetadataTooLarge Your metadata headers exceed the maximum allowed metadata size. Meta数据超过限制 400 Bad Request
MethodNotAllowed he specified method is not allowed against this resource. 请求的方法不允许 405 Method Not Allowed
MissingContentLength You must provide the Content-Length HTTP header. 缺少Content-Length字段 411 Length Required
MissingDateHeader Request must have a "date" or "x-bce-date" header. 请求中找不到Date和x-bce-date两者之一 400 Bad Request
NoReplicationConfiguration The Replication configuration does not exist. 未配置跨区域复制 404 Not Found
NoSuchBucket The specified bucket does not exist. 不存在该Bucket 404 Not Found
NoSuchBucketEncryption The bucket is not encrypted. 该Bucket未加密。 404 Not Found
NoSuchKey The specified key does not exist. 不存在该Object 404 Not Found
NoSuchUpload The specified multipart upload does not exist. The upload ID might be invalid, or the multipart upload might have been aborted or completed. 该uploadId所对应的三步上传不存在 404 Not Found
NotImplemented A header you provided implies functionality that is not implemented. 系统未实现 501 Not Implemented
ObjectUnappendable The object can not be append 对非Appendable的Object做AppendObject操作 403 Forbidden
OffsetIncorrect Offset not equal to current object length 追加Appendable Object时,<OffsetSize>值不等于已上传的Object的大小或者<OffsetSize>值不为0但Object不存在 409 Conflict
PreconditionFailed The specified If-Match header doesn't match the ETag header. 预处理错误 412 Precondition Failed
ReplicationNotEnabled The Bucket Replication is not enabled. 跨区域同步未开启错误 404 Not Found
ReplicationStatusError The Bucket Replication Status is not correct. Please make sure both the source and dest bucket have no enabled replication conf and both are not the dest replication bucket of other bucket. 跨区域复制源Bucket或目标Bucket已经在另一条跨区域复制规则中被指定。 409 Conflict
ReplicationStatusNotEmpty The bucket you tried to delete has an enabled replication conf or is a dest replication bucket of other bucket. 待删除的Bucket开启了跨区域复制功能。 409 Conflict
RequestExpired Request has expired. Timestamp date is XXX. 请求的时间戳过期。请求超时,XXX要改成x-bce-date的值。如果请求中只有Date,则需要将Date转换为本规范指定的格式。 403 Forbidden
RequestTimeout Your socket connection to the server was not read from or written to within the timeout period. 请求超时。 408 Request Timeout
ServiceUnavailable Please reduce your request rate. 服务不可用 503 Service Unavailable
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 Forbidden
SlowDown Please reduce your request rate. 请求过于频繁 503 Slow Down
TooManyBuckets You have attempted to create more buckets than allowed. 创建的Bucket数目超过了限制 400 Bad Request
InvalidStaticWebSiteFormat The format of index file or 404 file are not allowed. 不允许的index或者404文件名或格式。 比如:文件格式不允许,或者index与404文件同名。 400
NoSuchBucketStaticWebSiteConfig The static web site configuration does not exist. Bucket 没有开启静态托管。 404
StaticWebSiteIsDisable Static web site is disabled or not implemented. 静态网站托管功能被禁止。 如:即BOS不允许此region的bucket 开启静态网站托管功能,或者静态网站托管功能未上线。 501