天翼云主机类API接口技术规范.doc

天翼云主机类API接口技术规范文档说明API详细设计说明文档主要为省公司API对接提供接口的详细功能描述。其中包括对API的功能描述、字段元素描述;调用参数的定义及说明;响应参数的元素说明及响应样例;API调用地址和API交互方式等功能。基础说明返回值状态码说明为简化接口调用的复杂程度,接口仅会返回两种状态码:响应成功返回状态码800,响应失败返回状态码900。针对接口调用参数不正确(如少参数、参数位置不正确或请求方式不正确)时,系统将直接返回400;对于正确的调用但执行错误时,返回值中将包含中文的错误提示。名词解释名词说明真实资源ID用于对订购的资源进行管理的唯一标识,如开机、关机等操作虚拟资源ID用于对资源进行订购类操作的唯一标识,如续订、退订等crmBizId省公司用户下单时必须传bizId,且该bizId必须是已经推送成功并已绑定真实邮箱的客户账号公共参数说明本文档中所有的API接口在调用时需要提供两类参数:公共参数和业务参数。其中前者用于保证API的调用安全;后者则包含了执行业务所需的数据。下面表格中展示了公共参数的名称及说明,业务参数将在具体的API接口中进行说明。对于调用接口所涉及的算法,请参看附录四(目前只提供了Java版本)。参数说明中,有些值在不明确的情况下,使用了“xxxxxx”代替,调用时需要使用实际的值。当接口的返回值或参数过长时,使用了嵌入式文本进行了说明与注释。测试调用时要去除相关的注释文本。传参位置说明接口的调用目前包括两种方式:POST和GET,其中涉及到数据修改的接口一般使用POST方式;涉及到查询的接口一般使用GET方式。对于参数的存放位置包括两种:POST方式,业务参数放至HTTP请求的BODY中;GET方式,业务参数放至HTTP请求的HEADER中。所有的公共参数不管接口的请求方式是POST或是GET,均放置HEADER中。essKey*必填HEADER天翼云分配给用户的公钥contentMD5*必填HEADER业务参数值的MD5摘要:para1\npara2\n...paraN-1\nparaNcontentMD5的加密方式:contentMD5内容为业务参数的MD5信息摘要,构成MD5原始信息格式为(参数的拼接顺序以API签名为准,错误的顺序将导致验证失败):para1\npara2\n...paraN-1\nparaN,即将每个业务参数通过字符“\n”进行连接。若所调用的接口没有参数直接传空字符串“”进行转换为md5requestDate*必填HEADER“EEE,dMMMyyyyHH:mm:ssz”格式的请求日期(只接收英文格式)hmac*必填HEADER使用HMAC算法生成的信息摘要。HMAC原始信息中需要的字段:使用HMAC加密码时需要密钥和待加密的消息两部分内容。所以,系统中使用secretKey(用户密钥)作为加密密钥,待加密的消息由下面三部分构成:contentMD5,requestDate,servicePath(REST服务名称,例如“/apiproxy/v3/order/cancelOrder”),三部分信息通过“\n”进行连接(要注意连接的顺序):contentMD5\nrequestDate\nservicePath。platform*必填HEADER平台类型,整数类型,取值范围:2或3,,,该参数不需要加密。customInfo参数的json串详细信息:此信息的作用包括三个:1)针对分销平台的用户,需要加入资源实际使用人的信息;2)针对省公司CRM客户,用于指定CRM客户(资源的所属人)的BIZID;3)针对CTYUN用户,此处包含了CTYUN客户的账户ID。具体格式请参看说明。customInfo携带了资源所属关系的相关信息。根据其中“type”的不同分为三种关系:1,资源属于分销商客户;2),资源属于CRM客户;3)资源属于CTYUN客户。可以根据具体需求设置custonInfo中的数据。参数名选项参数位置说明customInfo*非必填接口请求方式为POST:该参数位置为BODY接口请求方式为GET:该参数位置为HEADER调用说明API调用执行后,后台的业务分为两种情况:同步执行和异步执行。其中同步执行的会在调用后返回调用结果;异步执行的业务需要通过“备注”中提供的接口轮询获取调用结果或根据返回的jobId去查询执行状态。接口详细说明实名信息同步接口类型HTTP接口提交方式POST接口地址URL:apiproxy/v3/account/ountType*必填Int账户类型:取值1或21普通用户2企业用户customInfo非必填String{"type":1,"identity":{"crmBizId":