简介

概述

百度区块链引擎BBE(Baidu Blockchain Engine)是为企业或开发者快速搭建区块链网络的BaaS(Blockchain as a Service)平台,目前完美兼容Ethereum、Fabric、百度自研超级链三种主流框架。

接口使用规范

规范化字符串

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

编码规范

  • 可解析内容,所有request/response body内容目前均使用UTF-8编码,后续会支持更多encoding类型。
  • 在请求时,需要对以下做UrlEncode:
    • Objectname,其中,Resource做UrlEncode的时候需要忽略“/”。
    • Querystring的Value。
    • x-bce-copy-source(忽略“/”)。
    • 自定义Meta:Meta Value只支持可见的ASCII字符,如果需要其它的字符,推荐使用UrlEncode处理。

日期与时间

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

请求响应格式标准

  • 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-*的形式定义。

  • 所有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>
    

服务域名

BBE API的服务域名为:

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

说明:BBE API支持HTTP和HTTPS两种调用方式。为了提升数据的安全性,建议通过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。

错误码

错误信息除了HTTP状态码以外,应同时在HTTP body中包含下表的参数,内容如下:

参数名 类型 说明
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" 
}

公共错误码

错误码 消息 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头域中附带的签名和服务端验证不一致。

BBE错误码

错误码 消息 HTTP状态码 语义
WrongNetworkType wrong network type 400 Bad Request 错误的网络类型
IllegalArguments Illegal arguments, check your input 400 Bad Request 参数错误
NetworkNotExist network not exist 404 Not Found 网络不存在
OperationFailed network is in status: {}, operation failed 403 Forbidden 网络处于禁止删除的状态
IllegalSubServiceType Illegal subServiceType 400 Bad Request 不合法的配置类型
IllegalNodeNum nodeNum must be a multiple of logical zone size 400 Bad Request 不合法的节点数
LogicalZoneNotExist logical zone is not exist 400 Bad Request 不合法的节点数
IllegalXChainArguments Illegal xuperchain arguments, check your input 400 Bad Request 不合法的xchain配置参数