天翼云主机类API接口技术规范一、文档说明API详细设计说明文档主要为省公司API对接提供接口的详细功能描述。其中包括对API的功能描述、字段元素描述；调用参数的定义及说明；响应参数的元素说明及响应样例；API调用地址和API交互方式等功能二、基础说明1.返回值状态码说明为简化接口调用的复杂程度，接口仅会返回两种状态码：响应成功返回状态码800，响应失败返回状态码900。针对接口调用参数不正确（如少参数、参数位置不正确或请求方式不正确）时，系统将直接返回400；对于正确的调用但执行错误时，返回值中将包含中文的错误提示。2.名词解释名词说明真实资源ID用于对订购的资源进行管理的唯一标识，如开机、关机等操作虚拟资源ID用于对资源进行订购类操作的唯一标识，如续订、退订等crmBizId省公司用户下单时必须传bizId，且该bizId必须是已经推送成功并已绑定真实邮箱的客户账号3.公共参数说明本文档中所有的API接口在调用时需要提供两类参数：公共参数和业务参数。其中前者用于保证API的调用安全；后者则包含了执行业务所需的数据。下面表格中展示了公共参数的名称及说明，业务参数将在具体的API接口中进行说明。对于调用接口所涉及的算法，请参看附录四（目前只提供了Java版本）。参数说明中，有些值在不明确的情况下，使用了“xxxxxx”代替，调用时需要使用实际的值。当接口的返回值或参数过长时，使用了嵌入式文本进行了说明与注释。测试调用时要去除相关的注释文本。4.传参位置说明接口的调用目前包括两种方式：POST和GET，其中涉及到数据修改的接口一般使用POST方式；涉及到查询的接口一般使用GET方式。对于参数的存放位置包括两种：POST方式，业务参数放至HTTP请求的BODY中；GET方式，业务参数放至HTTP请求的HEADER中。所有的公共参数不管接口的请求方式是POST或是GET，均放置HEADER中。参数名选项参数位置说明accessKey*必填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/v2/order/cancelOrder"）,三部分信息通过“\n”进行连接（要注意连接的顺序）：contentMD5\nrequestDate\nservicePath。platform*必填HEADER平台类型，整数类型，取值范围：2或3,传2表示2.0自营资源，传3表示3.0合营资源，该参数不需要加密。customInfo参数的json串详细信息：此信息的作用包括三个：1）针对分销平台的用户，需要加入资源实际使用人的信息；2）针对省公司CRM客户，用于指定CRM客户（资源的所属人）的BIZID；3）针对CTYUN用户，此处包含了CTYUN客户的账户ID。具体格式请参看说明。custominfo携带了资源所属关系的相关信息。根据其中“type"的不同分为三种关系：1,资源属于分销商客户；2）,资源属于CRM客户；3）资源属于CTYUN客户。可以根据具体需求设置custoninfo中的数据。参数名选项参数位置说明custominfo*非必填接口请求方式为POST:该参数位置为BODY接口请求方式为GET:该参数位置为HEADER■custominfo信息.txt5.调用说明API调用执行后，后台的业务分为两种情况：同步执行和异步执行。其中同步执行的会在调用后返回调用结果；异步执行的业务需要通过“备注”中提供的接口轮询获取调用结果或根据返回的jobId去查询执行状态。三、接口详细说明1.实名信息同步接口类型HTTP接口提父方式POST接口地址URL：apiproxy/v3/account/submitAuthlnfo基础参数参数名选项参数...
