火山云引擎API接口开发文档

索引
1 概述
　1.1 文档说明
　1.2 API接口作用
　1.3 更新历史

2 开发说明
　2.1 API接口方式
　2.2 环境及要求
　2.3 命令返回格式要求
　2.4 必要的参数及加密
　2.5 约定的错误返回格式

3 API命令参数及返回格式
　3.1 检查接口连接 checkConnect
　3.2 用户登录认证 checkUser
　3.3 自动登录认证 checkLogin
　3.4 查询帐户余额 queryFund
　3.5 扣除帐户费用 addFund
　3.6 发送用户通知 addNotice 本接口只用于v0.*版本的主控
　3.7 发送用户通知 sendNotice 本接口只用于v1.00.*及以上版本的主控
　3.8 扣除帐户费用 subtractFund 本接口只用于v1.00.*及以上版本的主控


1 概述

  • 1.1 文档说明
    本文档描述了火山云引擎API接口协议，供开发者参考。本文档定义了基本的数据交换标准，其中包括数据格式，数据定义，以及一些相关约定。

    本文档中的约定简称：
    • “云引擎主控”或“主控”是指火山互联提供的云引擎管理控制平台，在服务器上为一个加密的、独立运行的云主机。包括管理员使用的“主控中心”，会员使用的“用户管理中心”，以及管理产品用的“控制面板”。
    • “会员平台”是指用户用来管理会员及财务的业务系统，可以是用户自己的业务网站，如果没有业务网站，可以使用云引擎自带的简易会员平台（在服务器上为一个开源的云主机）。
    • “API接口”是指火山互联“云引擎主控”与用户的“会员平台”进行数据交换的接口，用来实现对会员身份的认证和对财务的处理等操作。
    • “API密码”是指用户设置在主控中的“会员平台API密码”，用于API接口的加密认证。

  • 1.2 API接口作用
    由于火山互联云引擎主控不提供会员及财务管理，使用者需要使用原有的业务平台或云引擎自带的简易会员平台来实现会员注册、会员管理、用户付款及财务管理等业务相关操作。

    用户在购买产品和管理产品时，可以直接登录云引擎主控。主控通过API接口对用户的身份进行验证和处理财务扣款等。

  • 1.3 API接口更新历史
    • 2011-10-18 发布API（V1.0）


2 开发说明

  • 2.1 API接口方式
    由于云主机的按需弹性配置购买流程和关联关系比较复杂，在会员平台实现的话，对编程及业务流程处理要求太高，并且API接口会比较多，因此，云引擎主控并不提供API接口供会员平台读取，而是由会员平台提供API接口供主控读取，实现用户身份验证、余额查询、扣款、发送通知等简单的数据交换。API接口使用HTTP方式进行访问。

  • 2.2 环境及要求
    由于主控是通过API读取会员平台的一个HTTP页面，与环境无关，会员平台可以是PHP、ASP、.NET、JSP等等任意环境。
    API接口数据传输使用32位MD5加密，需要用户的接口编程支持MD5即可。

  • 2.3 请求参数及加密说明
    主控使用POST方式向用户在主控中设置的API接口地址发送请求，包括三个必要参数：
    action : 请求类型
    sign : 操作流水号，每次请求会不同，重复的可不认，以防止抓包方式发送重复请求。
    encode : MD5加密的验证码，根据action不同加密值不同，详见下文说明。
    其它参数：根据action不同会有不同参数，详见下文说明。

    开发时，请使用MD5加密方式加密123456，如果得到的值为e10adc3949ba59abbe56e057f20f883e，则表示加密方式与云引擎主控是一致的。如果不一致，则说明加密方式与云引擎主控不匹配，需要更换配置的MD5加密方式。

  • 2.4 命令返回格式要求
    返回数据采用XML格式，正确时返回

    错误时返回

    注：##处为多个其它标签

  • 2.5 约定的错误返回格式
    return值分别对应：
    0 : 请求正常
    1 : 密码验证失败
    2 : sign错误或重复
    3 : 账号不存在
    4 : 余额不足
    9 : 非1-4的错误，错误信息写到msg标签中。

3 API命令参数及返回格式

  • 3.1 检查接口连接 checkConnect
    ○命令作用：
    　用于主控检查API接口是否能正常连接，正常时会在主控[API接口设置]下显示“接口正常”字样。
    ○接口所需要操作：
    　验证encode值，正确则返回正确。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 checkConnect
    sign 流水号 24位随机数字 每次请求会不同
    encode 验证码 字符串，值：md5(API密码 + action + sign)
    　※注：深红色文字表示在使用时必须原样使用的字符串，下同。
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误


  • 3.2 用户登录认证 checkUser
    ○命令作用：
    　用于验证用户身份。用户在主控“用户管理中心”输入用户账号及密码时登录时，主控通过此接口验证用户身份。
    ○接口所需要操作：
    　验证encode值；验证check值。通过验证后，返回用户部分资料。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 checkUser
    username 登录账号 字符串 此值为用户在会员平台的账号名称
    sign 流水号 24位随机数字 每次请求会不同
    encode 验证码 字符串，值：md5(API密码 + action + sign + username)
    check 密码加密字符串 字符串，值：md5(API密码 + sign + 用户密码) “用户密码”是用户平台会员表中的密码字段保存的记录值。如果保存的是MD5，那么这里也使用MD5值。
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误
    • userid: 会员编号，必须的值。用此值查询用户在主控中的产品，在购买时也会记录产品所属会员编号，以便于管理。
    • username: 登录账号，必须的值，将显示在主控的“用户管理中心”页面上端欢迎内容中。
    • userlimit: 用户权限，为空时表示无限制。其它值含义如下：
      A 禁止收费新购买 B 禁止收费续期 C 禁止收费升级
      F 禁止免费申请 G 禁止免费续期，H 禁止免费升级
      V 通过身份认证
      注：由于缓存原因，增加或降低用户折扣率时，主控并不一定立即生效，可能需要一会才会更新（不会超过1分钟）。
    • fund: 用户余额


  • 3.3 自动登录认证 checkLogin
    ○命令作用：
    　用于验证用户身份。用户从会员平台登录后点击相应的自动登录链接跳转到主控时，主控通过此接口验证用户身份。
    ○自动登录实现过程：
    　由于会员平台与主控属于两个独立的网站，是需要分别进行登录才能操作的。用户登录会员平台后，再进入云主机管理，如果还需要输入账号密码，那么用户体验就很不好了。因此，主控允许实现登录会员平台后，再转到主控可以不用登录。这个功能必须会员平台程序配置合才能实现。流程如下：
    　1 用户登录会员平台后，记录Session
    　2 会员中心页面有云主机管理链接(在PHP会员平台例程为/members/admin.php)，这个链接是会员中心本地的一个程序，作用有以下：
    　　(1) 用户到云主机管理页面，链接为/members/admin.php?action=admin
    　　(2) 用户到云主机购买列表页面(主控自带)，链接为/members/admin.php?action=buy
    　　(3) 用户指定购买云主机某个推荐配置，链接为/members/admin.php?action=buy&prodid=####;
    　3 用户点击这些链接时，这个程序需要以下处理：为用户生成一个临时密码（保存到数据库），并将API接口密码和临时密码MD5加密，然后跳转到主控页面（需要将加密后的值作为参数），所需要参数如下：
    　　(1) action: 即admin.php?action=的值，必须值
    　　(2) u: 会员编号（10位及以内数字），必须值
    　　(3) v: 临时密码（临时密码为YYYYMMDDHHIISS+10位随机数字），必须值
    　　(4) pw: 校验码，用于校验请求是否合法，值为md5(API密码+u+v)，必须值
    　　(5) prodid: 推荐配置ID，可为空
    　　注：以上即为/members/admin.php需要实现的代码。实现后跳转到类似页面：
    　　https://主控IP或域名/user/index.php?action=#&u=#&v=#&pw=#&prodid=#
    　4 主控接收到请求后，会向会员平台发送checkLogin请求，验证此链接是否有效，checkLogin验证包括：
    　　(1) encode是否有效
    　　(2) userid是否有效
    　　(3) 临时密码是存在，或是否过期
    　　(4) check是否有效
    　　(5) 通过验证后，清除保存到数据库中的临时密码（为保障帐户安全），并返回本文档下面指定的数据
    　　主控若得到API返回正确信息，则则自动登录用户管理中心，不需要再输入密码。

    　　详细流程请参考会员平台中的代码。
    ○接口所需要操作：
    　验证encode值；验证check值。通过验证后，清空临时密码，返回用户部分资料。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 checkLogin
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    encode 验证码 字符串，值：md5(API密码 + action + sign + userid)
    check 密码加密字符串 字符串，值：md5(API密码 + sign + 临时密码) 返回正确之后需要将数据表中临时密码清空，以保证此链接只能登录一次
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误
    • userid: 会员编号，必须的值。用此值查询用户在主控中的产品，在购买时也会记录产品所属会员编号，以便于管理。
    • username: 登录账号，必须的值，将显示在主控的“用户管理中心”页面上端欢迎内容中。
    • userlimit 用户权限，为空时表示无限制。
    • fund: 用户余额


  • 3.4 查询帐户余额 queryFund
    ○命令作用：
    　查询会员余额。用户在主控中执行购买、续费，升级之前，主控通过此接口查询用户余额，以检查用户是否有足够款项执行相应操作。
    ○接口所需要操作：
    　验证encode值。通过验证后，查询用户余额并返回。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 queryFund
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    encode 验证码 字符串，值：md5(API密码 +action + sign + userid)
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误
    • fund: 用户余额
    • userlimit 用户权限，为空时表示无限制。


  • 3.5 扣除帐户费用 addFund
    ○命令作用：
    　扣除用户费用。接口在收到此命令时，自行扣除用户对应费用。用户在主控中执行购买、续费、升级操作时，主控会通过此命令要求会员平台扣除费用，若扣费不成功，则不会执行用户的操作。
    ○接口所需要操作：
    　验证encode值；验证余额是否够用。通过验证后，向扣款记录中写入值，然后返回。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 addFund
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    fund 会员金额 数字
    fundtype 类型 数字 有三种值，分别代表：1 购买 2 续费 3 升级 5 增值服务，如绑定IP
    orderid 订单号 数字 在主控中的订单号
    encode 验证码 字符串，值：md5(API密码 +action + sign + userid + fund + fundtype + orderid)
    remark 备注 扣费的相关说明
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误，余额不足时返回4
    • fund: 用户余额


  • 3.6 发送用户通知 addNotice
    ○命令作用：
    　向用户发送通知。主控在订单到期前会自动向此接口发送通过请求；在管理员暂停或关闭订单、域名白名单、端口时，可选择让主控发送通知请求。
    ○接口所需要操作：
    　验证encode值。通过验证后，根据情况向用户发送站内通知、短信通知或邮件通知。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 addNotice
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    orderid 订单号 数字 相关联的订单号
    sentmail 邮件通知 数字 0或1 是否同时发送邮件通知：0不发送邮件通知; 1 同时发送邮件通知
    title 通知标题 字符串 通知标题为在主控中设置的
    msg 通知内容 字符串 通知内容为在主控中设置的字符串
    encode 验证码 字符串，值：md5(API密码 +action + sign + userid + orderid + title + msg)
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误


  • 3.7 发送用户通知 sendNotice
    ○命令作用：
    　向用户发送通知。主控在订单到期前会自动向此接口发送通过请求；在管理员暂停或关闭订单、域名白名单、端口时，可选择让主控发送通知请求。
    ○接口所需要操作：
    　验证encode值。通过验证后，根据情况向用户发送站内通知、短信通知或邮件通知。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 sendNotice
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    orderid 订单号 数字 相关联的订单号
    tag 主控标识 字母和数字组合 区分是哪个主控发送的消息
    prodlist 产品列表 字符串 用于通知到期的产品
    sentmail 邮件通知 数字 0或1 是否同时发送邮件通知：0不发送邮件通知; 1 同时发送邮件通知
    sentsms 发送类型 数字 默认14 14：调用云主机到期通知
    code 最近到期日期 字符串 通知标题为在主控中设置的
    title 通知标题 字符串 通知标题为在主控中设置的
    msg 通知内容 字符串 通知内容为在主控中设置的字符串
    encode 验证码 字符串，值：md5(API密码 +action + sign + userid)
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误


  • 3.8 扣除帐户费用 subtractFund
    ○命令作用：
    　扣除用户费用。接口在收到此命令时，自行扣除用户对应费用。用户在主控中执行购买、续费、升级操作时，主控会通过此命令要求会员平台扣除费用，若扣费不成功，则不会执行用户的操作。
    ○接口所需要操作：
    　验证encode值；验证余额是否够用。通过验证后，向扣款记录中写入值，然后返回。
    ○请求参数：
    参数名 中文名称 值或值说明 备注
    action 请求类型 subtractFund
    userid 会员编号 数字 此为用户平台会员表中的用户编号值
    sign 流水号 24位随机数字 每次请求会不同
    fundtype 类型 数字 有三种值，分别代表：1 购买 2 续费 3 升级 5 增值服务，如绑定IP
    tag 主控标识 字母和数字组合 区分是哪个主控发送的消息
    orderjson 产品列表 json 可传多个订单信息，以JSON数据传送，每个订单需要的参数如下：
    {orderid:"订单号",fund:"实扣金额",initfund:"原价",daynum:"时长天",ordertime:'购买时使用当前时间,续期时为订单续费前的到期时间',remark:'备注'}
    ispoints 是否使用积分 数字 0或1 需要会员平台支持，默认为0
    codestr 优惠码 随即机数字和字母 需要会员平台支持，默认为空
    encode 验证码 字符串，值：md5(API密码 +action + sign + userid + fundtype + orderjson + tag + ispoints + codestr)
    ○正确时返回格式：

    ○返回值说明：
    • return: 命令执行状态，0为正常，大于0为错误

    [完] 返回顶部