API总述

API描述

名称 描述
主机购买 提交套餐ID、购买时限、bj.bdysite.com二级域名前缀、PHP版本等信息创建新营销云建站主机
主机信息查询 获取主机信息,返回包括:状态,域名,Ftp、数据库及主机账号等主要信息
主机续费 根据续费时长,延长BCH云虚拟主机到期时间
重置FTP密码 重置登录BCH云虚拟主机FTP的登陆密码,如传空参数,则自动生成以小写字母+数字组成的8位随机密码
重置管理账号密码 重置登录BCH云虚拟主机管理账号的登陆密码,如传空参数,则自动生成以小写字母+数字组成的8位随机密码
添加绑定域名 为BCH云虚拟主机绑定域名,使得这个域名在通过备案并CNAME到临时域名后,也可以访问部署网站
解绑单个域名 解绑一个已绑定的域名
主机升级 将一台主机升级到更高级的套餐
验证管理账号 验证一个管理账号是否可用
主机绑定域名查询 获取一台主机已经绑定的非bdysite域名
切换PHP版本 更改主机的PHP运行版本,支持的版本为5.2,5.3, 5.4
批量修改FTP密码 修改一个父用户下的指定子用户的FTP密码
导出过期站点 导出一个父账号下的所有在指定时间段内到期的站点信息

调用方式

概述

建站API的设计采用了Restful风格,每个API功能(也可以称之为资源)都使用URI(Universal Resource Identifier)来唯一确定。对资源的请求方式是通过向资源对应的URI发送标准的 HTTP 请求,比如 GET、PUT、POST等,同时,请求需要遵守签名算法,并包含约定的请求参数

通用约定

  • 所有编码都采用UTF-8
  • 日期格式采用yyyy-MM-dd方式,如2015-08-10
  • 时间格式采用UTC格式:yyyy-MM-ddTHH:mm:ssZ, 如2015-08-20T01:24:32Z
  • Content-type为application/json; charset=UTF-8
    • object类型的key必须使用双引号(")括起来
    • object类型的key必须使用lowerCamelCase表示

公共请求头

头域(Header) 是否必须 说明
Authorization 必须 包含Access Key与请求签名
Host 必须 包含API的域名,例如:bch.bj.baidubce.com
x-bce-date 必须 表示时间的字符串,符合时间格式要求
Content-Type 可选 application/json; charset=utf-8
x-bce-content-sha256 可选 表示内容部分的SHA256签名的十六进制字符串。这里内容指HTTP Request Payload Body。即Content部分在被HTTP encode之前的原始数据

说明:

公共头域将在每个建站API中出现,是必需的头域,其中x-bce-content-sha256头域只出现在POST和PUT请求中。

公共响应头

头域(Header) 说明
Content-Type 只支持JSON格式,application/json; charset=utf-8
x-bce-request-id BCH后端生成,并自动设置到响应头域中

响应状态码

返回的响应状态码遵循RFC 2616 section 6.1.1

  • 1xx: Informational - Request received, continuing process.
  • 2xx: Success - The action was successfully received, understood, and accepted.
  • 3xx: Redirection - Further action must be taken in order to complete the request.
  • 4xx: Client Error - The request contains bad syntax or cannot be fulfilled.
  • 5xx: Server Error - The server failed to fulfill an apparently valid request.

通用错误返回格式

当调用接口出错时,将返回通用的错误格式。Http的返回状态码为4xx或5xx,返回的消息体将包括全局唯一的请求、错误代码以及错误信息。调用方可根据错误码以及错误信息定位问题,当无法定位到错误原因时,可以发工单联系百度技术人员,并提供requestid以便于快速地帮助您解决问题。

消息体定义

参数名 类型 说明
requestId String 请求的唯一标识
code String 错误类型代码
message String 错误的信息说明

错误返回示例

{
    "requestId": "47e0ef1a-9bf2-11e1-9279-0100e8cf109a",
    "code":"NoSuchKey",
    "message":"The resource you requested does not exist"   
}

公共错误码

Code Message HTTP Status Code 说明
BceValidationException [param]:[param]=[Validation criteria] 400 无效的[param]参数
MoneyNotEnough Money not enough to complete the current request 400 余额不足以完成当前的请求操作
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 Authorization头域中附带的签名和服务端验证不一致
InvalidAccessKeyId The Access Key ID you provided does not exist in our records 403 Access Key ID不存在
ServiceInternalError Service internal error occurred 500 内部服务发生错误

签名认证

建站API会对每个访问的请求进行身份认证,以保障用户的安全。安全认证采用Access Key与请求签名机制。Access Key由Access Key ID和Secret Access Key组成,均为字符串,由百度云官方颁发给用户。其中Access Key ID用于标识用户身份,Access Key Secret 是用于加密签名字符串和服务器端验证签名字符串的密钥,必须严格保密。

对于每个HTTP请求,用户需要使用下文所描述的方式生成一个签名字符串,并将认证字符串放在HTTP请求的Authorization头域里。

签名字符串格式

bce-auth-v{version}/{accessKeyId}/{timestamp}/{expireTime}/{signedHeaders}/{signature}

其中:

  • version是正整数,目前取值为1。
  • timestamp是生成签名时的时间。时间格式符合通用约定
  • expireTime表示签名有效期限,单位为秒,从timestamp所指定的时间开始计算。
  • signedHeaders是签名算法中涉及到的头域列表。头域名字之间用分号(;)分隔,如host;x-bce-date。列表按照字典序排列。当signedHeaders为空时表示取默认值。
  • signature是256位签名的十六进制表示,由64个小写字母组成,生成方式由如下签名生成算法给出。

签名生成算法

有关签名生成算法的具体介绍,请参看鉴权认证机制

多区域选择

BCH支持“北京-华北”和“香港”两个区域,两个区域的API地址分别如下:

  • 香港:bch.hk.baidubce.com
  • 北京:bch.bj.baidubce.com

注意

香港区域目前仅提供白名单方式访问,使用前请先提交工单申请。

本文档中涉及的示例均以北京区域为准,如果用户使用的是香港区域的服务,请自行替换API地址。