文件存储CFS

    API调用须知

    API调用遵循HTTP协议,各Region采用不同的域名,具体域名为cfs.{region}.baidubce.com。 数据交换格式为JSON,所有request/response body内容均采用UTF-8编码。URL参数中所使用的fsId为文件系统唯一资源标识

    注意: 1.使用API接口前,请根据用户实际情况进入“实名认证”页面进行“企业认证”或者“个人认证”,详细的操作步骤请参见实名认证。 2.region信息请参见服务域名

    API认证机制

    所有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和同样的认证机制生成认证字符串,并与用户请求中包含的认证字符串进行比对。如果认证字符串相同,系统认为用户拥有指定的操作权限,并执行相关操作;如果认证字符串不同,系统将忽略该操作并返回错误码。

    鉴权认证机制的详细内容请参见鉴权认证机制

    幂等性

    当调用某些接口时如果遇到了请求超时或服务器内部错误,用户可能会尝试重发请求,这时用户通过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将长期有效。

    日期与时间规范

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

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

    请求参数

    请求参数包括如下4种:

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

    返回值说明

    返回值分为两种形式:

    返回内容 说明
    HTTP Status Code 如200,400,403,404等
    Response Body JSON格式组织的响应数据体

    公共请求头

    下表列出了所有CFS API所携带的公共头域。HTTP协议的标准头域不在此处列出

    头域(HEADER) 是否必须 说明
    Authorization 签名字符串,生成签名字符串的方法请参考鉴权认证机制
    Content-Type application/json; charset=utf-8
    x-bce-date 可选 签名日期

    公共响应头

    下表列出了所有CFS API的公共响应头域。HTTP协议的标准响应头域不在此处列出

    头域(HEADER) 说明
    Content-Type application/json; charset=utf-8
    x-bce-request-id 本次请求的requestId

    错误码

    请求发生错误时通过Response Body返回详细错误信息,遵循如下格式:

    参数名 类型 说明
    code String 错误码
    message String 错误描述
    requestId String 本次请求的requestId

    示例:

    {
        "requestId" : "ae2225f7-1c2e-427a-a1ad-5413b762957d",
        "code" : "NoSuchKey",
        "message" : "The resource you requested does not exist"
    }

    BCE公共错误码

    下表列出了所有API的公共错误码。各服务应该在此基础上自定义错误码。

    Code Message HTTP Status Code 说明
    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 Not Found 指定的CFS实例不存在
    InvalidFSType The FS TYPE is invalid. 400 Bad Request 文件系统的类型错误
    InvalidFSName The FS NAME is invalid. 400 Bad Request 文件系统的名称不符合要求
    InvalidFSProtocol The FS PROTOCOL is invalid. 400 Bad Request 文件系统不支持该协议
    AvailabilityZoneNotFound The specified availability zone does not exist. 400 Bad Request 用户设置的分区(zone) 不存在
    InvalidVpcId The vpc id is invalid. 400 Bad Request vpc id 错误
    CreateOrderFail We encountered an internal error. Please try again. 500 Internal Server Error 创建订单失败,请稍候重试
    DuplicateRequest The request is duplicate. 400 Bad Request 重复的创建文件系统实例请求
    FsNumQuotaExceeded The number of CFS exceeded current quota. 413 Request Entity Too Large CFS数量超过用户配额限制
    DropCreatingFS The fs is in creating, can not drop. 400 Bad Request 不能删除正在创建的文件系统实例
    DropMountedFS The fs has mount target , please drop before clear mount target. 400 Bad Request 不能删除有挂载点的文件系统实例
    FSNotInService The fs is not in service, not allow this operation. 400 Bad Request 文件系统服务不可用
    InvalidSubnetId The subnet id is invalid. 400 Bad Request 用户提供的 subnet id 不可用
    InvalidVpcOrSubnet Invalid VPC ID or Subnet ID. 400 Bad Request 创建挂载点时,提供的 vpc id 或者 subnet id 不正确
    AlreadyMounted The fs already has mount target in the same subnet. 400 Bad Request 文件系统已经被挂载到目标子网络
    DropCreatingMount The mount target is in creating, can not drop. 400 Bad Request 不能删除正在创建的挂载点
    MountTargetNotFound The request mount target id is not found. 404 Not Found 没有找到目标挂载点
    MissingParameter A required parameter 'parameterName' is not supplied. 400 Bad Request 该请求缺少必要的参数“parameterName”
    InvalidParameter The parameter 'parameterName' is invalid. 400 Bad Request "parameterName"参数不合法
    ResourceNotExists The resource does not exist. 404 Not Found 请求的host未在网关对应的region中配置
    EOFException Unexpected EOF read on the socket. 400 Bad Request 读取request 中inputstream异常,通常为eof
    RequestTimeTooSkewed The difference between the request time and the server's time is too large. 403 Forbidden Authorization中timestamp无效
    ServiceError the dependency service is unavailable, host is {host} 424 Failed Dependency 服务处于熔断状态
    UnsupportedProtocol The protocol '{http}' is not supported. 403 Forbidden 协议校验不支持http或者https请求
    QualifyNotPass The User has not pass qualify. 403 Forbidden 未通过实名认证
    RateLimit There are too many connections. The host is {host} 421 Misdirected Request 请求被限速
    IllegalRequestUri The request URI contains some forbidden characters. 400 Bad Request url合法性校验失败
    RequestUriForbidden The request URI is forbidden or not included. 400 Bad Request 请求的uri不在服务允许的uri
    RequestEntityTooLargeException Request entity is too large, should not exceed 50M. 413 Request Entity Too Large multipart/ 类型的请求,文件大小大于50M
    RequestEntityEmptyException Request entity is empty. 400 Bad Request multipart/ 类型的请求,文件字节流为0
    ParseBodyException Parsing request body exception 500 Internal Server Error 如果有映射文件,在映射body时异常
    ServiceUnavailable Service or dependent service is unavailable. 503 Service Unavailable 与后端请求连接异常或超时等网络错误
    InvalidClientToken The client token is invalid, client token must be a ascii string of no longer than 64 bits. 400 Bad Request 幂等请求的clientToken的值错误
    MultiRequestConflict The request is refused because of a previous is in progress. 409 Conflict 幂等请求时,前一个请求正在处理中,又收到其它请求
    上一篇
    概述
    下一篇
    服务域名