接口文档

[BIGKnight]

https://docs.google.com/document/d/11qvBfmiGegBdJCs1Q-iLme4oX5Bo7FAj8CkbIpK4SaE/edit

[Luodian]

1.面向slave客户端的功能 本章中给出面向slave节点的粗粒度功能概览，详细流程见第四章

1. 注册： 检查邮箱是否存在 注册
2. 登陆： 登录
3. 找回密码
4. 修改个人信息： 修改昵称，主机名，机器的用户名，机器昵称，头像
5. 查看信息： 查看个人信息 , 算时，积分 查看本机信息 获取与自己任务相关的活跃结点信息(展示网络结点)

2.面向master客户端的功能 本章中给出面向master节点的粗粒度功能概览，详细流程见第四章

1. 写入任务信息
2. 获取在线机器信息
3. 写入任务分配记录
4. 更新任务分配记录状态
5. 更新任务信息状态
6. 添加/修改机器信息

3.接口 以下为对接口的描述，需要注意的是，接口没有考虑安全性问题 目前接口的地址前缀皆为http://cn.yuhong-zhong.com:8080/higher_compute 3.1 登录 请求地址：/login 请求方式：POST 请求参数： user_id：用户ID user_email：用户邮箱 注：用户ID与邮箱二选一即可，都提供时使用ID passwd：登录密码的MD5哈希值 响应参数： 登陆成功： HTTP状态码：200 HTTP内容： { authorized: 1 email: #用户邮箱# user_id: #用户ID# port1:#SSH端口1# port2:#SSH端口2# } 登录失败： HTTP状态码：200 HTTP内容： {authorized: 0}

3.2 检查邮箱是否存在 请求地址：/check_email_exist 请求方式：GET 请求参数： email_addr：邮箱 响应参数： 存在： HTTP状态码：200 HTTP内容： { email_exists: 1 } 不存在： HTTP状态码：200 HTTP内容： { email_exists: 0 }

3.3 注册 请求地址：/Register 请求方式：POST 请求参数： email_addr：登陆邮箱 nick_name：昵称 pwd：密码MD5哈希 响应参数： 注册成功： HTTP状态码：200 HTTP内容： { register_status: 1 user_id：xxx } 注册失败： HTTP状态码：200 HTTP内容： { register_status: 0 }

3.4 重置密码邮箱验证 请求地址：/PwdResetVal 请求方式：GET 请求参数： email_addr：用户邮箱 user_id：用户ID 注：用户ID与邮箱二选一即可，都提供时使用ID 响应参数： 验证正确，发送邮件： HTTP状态码：200 HTTP内容： { email_sent: 1 user_id：用户ID } 验证失败（邮箱不存在）： HTTP状态码：200 HTTP内容： { email_sent: 0 }

3.5 修改个人信息 请求地址：/modify_user_info 请求方式：POST 请求参数： user_id：用户ID (OPT)user_nickname：新的用户昵称 (OPT)host_name：新的主机名 (OPT)machine_username：新的机器用户名 (OPT)machine_nickname：新的机器昵称 (OPT)machine_id：要修改信息的机器ID 响应参数： 修改成功： HTTP状态码：200 HTTP内容： { modify_status: 1 } 权限验证通过，但修改失败： HTTP状态码：200 HTTP内容： { modify_status: 0, error_description: #错误描述# } 权限验证失败： HTTP状态码：401

3.6 机器下线 请求地址：/machine_offline 请求方式：POST 请求参数： machine_id：主机ID 响应参数： 正常下线： HTTP状态码：200 HTTP内容： { status:1 } 权限验证通过，但下线异常： HTTP状态码：200 HTTP内容： { status:0 } 权限验证失败： HTTP状态码：401

3.7 查看个人信息 请求地址：/GetUserInfo 请求方式：GET 请求参数： user_id：用户ID 响应参数: 权限验证通过： HTTP状态码：200 HTTP内容： { nick_name: #昵称#, credit: #积分#, online_time: #在线时长#, user_id: #用户ID#, machine_list: #用户的机器列表# } machine_list为列表，并且列表中每一项为描述属于该用户的机器的对象： { host_name: #机器主机名#, ip: #机器IP地址#, nickname: #机器昵称#, machine_status: #机器状态#, machine_username: #机器用户名#, compute_ability: #总算力#, remain_compute_ablity: #剩余算力# } 权限验证失败： HTTP状态码：401 3.8 查看本机信息 请求地址：/get_machine_info 请求方式：GET 请求参数： machine_id：本机ID 响应参数： 权限验证通过： HTTP状态码：200 HTTP内容： { machine_id: #机器ID#, host_name: #机器主机名#, ip: #机器IP地址#, machine_status: #机器的状态# task_status: #任务分配的状态# nickname: #机器昵称#, machine_username: #机器用户名#, compute_ability: #总算力#, remain_compute_ablity: #剩余的算力# } 权限验证失败： HTTP状态码：401

3.9 获取相关节点信息 请求地址：/get_machine_info_with_task 请求方式：GET 请求参数： task_id：任务ID 响应参数： 权限验证通过： HTTP状态码：200 HTTP内容： [#MACHINE#, ...] 列表中每一项为描述机器的对象： { machine_id: #机器ID#, host_name: #机器主机名#, ip: #机器IP地址#, machine_status: #机器的状态# task_status: #任务分配的状态# nickname: #机器昵称#, machine_username: #机器用户名#, compute_ability: #总算力#, remain_compute_ablity: #剩余的算力#, user_id: #机器所属用户的ID# } 权限验证失败： HTTP状态码：401

3.10 邮箱激活及验证 请求地址：## 请求方式：POST 请求参数： verification_code：验证码 user_id：用户ID 响应参数： 激活/验证成功： HTTP状态码：200 HTTP内容： { email_verification: 1 } 激活/验证失败： HTTP状态码：200 HTTP内容： { email_verification: 0 }

3.11 上传头像 请求地址：/ImgUpload 请求方式：POST 请求参数： img：头像文件 user_id：用户ID 响应参数： 上传成功： HTTP状态码：200 HTTP内容： { img_save: 1 } 权限验证通过，但上传失败： HTTP状态码：200 HTTP内容： { img_save: 0 } 权限验证失败： HTTP状态码：401 备注：图片上传后，默认在portrait文件夹下，文件名为user_id.jpg e.g.http://localhost:8080/higher_compute/portrait/12.jpg

3.12 公钥发送 请求地址：/UploadPK 请求方式：POST 请求参数： machine_id：机器ID public_key：公钥 响应参数： 权限验证通过，公钥上传出错： HTTP状态码：200 HTTP内容： { PK_save: 0 } 权限验证通过，公钥成功上传： HTTP状态码：200 HTTP内容： { PK_save: 1 } 权限验证失败： HTTP状态码：401

3.13 获取所有上线节点信息 请求地址：/get_online_machine_info 请求方式：GET 响应参数： 权限验证通过： HTTP状态码：200 HTTP内容： [#MACHINE#, ...] 列表中每一项为描述机器的对象： { machine_id: #机器ID# host_name: #机器主机名#, ip: #机器IP地址#, nickname: #机器昵称#, machine_username: #机器用户名#, compute_ability: #总算力#, remain_compute_ablity: #剩余的算力#, machine_status: #机器状态# } 权限验证失败： HTTP状态码：401

3.14 IP发送 请求地址：/UploadIP 请求方式：POST 请求参数： machine_id：机器ID ip：当前IP 响应参数： 权限验证通过，IP上传出错： HTTP状态码：200 HTTP内容：

{ ip_save: 0 } 权限验证通过，成功上传IP： HTTP内容： { ip_save: 1 } 权限验证失败： HTTP状态码：401 3.15 任务发布 请求地址：/SubmitTask 请求方式：POST 请求参数： machine_id：机器ID user_id：用户ID task_name：任务名称 public_key：机器公钥 machine_id_list=[#id1#,#id2#,...]：选中的机器的ID的列表 响应参数： 权限验证通过，任务发布失败： HTTP状态码：200 HTTP内容： { task_pub: 0 task_id：xxx } 权限验证通过，任务发布成功： HTTP状态码：200 HTTP内容： { task_pub: 1 } 权限验证失败： HTTP状态码：401

3.16 任务结束(master/slave) 请求地址：/TaskFinish 请求方式：POST 请求参数： machine_id：机器ID user_id：用户ID task_id：任务ID actor：担任的角色（“master”/”slave“） 响应参数： 权限验证通过，任务结束成功： HTTP状态码：200 HTTP内容： { task_fin: 1 } 权限验证通过，任务结束失败： HTTP状态码：200 HTTP内容： { task_fin: 0 } 权限验证失败： HTTP状态码：401 3.17 slave就绪情况 请求地址：/get_slave_status 请求方式：GET 请求参数： task_id：机器ID 响应参数： 权限验证通过，slave全部准备就绪： HTTP状态码：200 HTTP内容： { slave_ready: 1 machine_list: #slave机器列表# } 列表中每一项为描述机器的对象： { host_name: #机器主机名#, ip: #机器IP地址#, nickname: #机器昵称#, machine_user_name: #机器用户名#, } 权限验证通过，slave未完全就绪： HTTP状态码：200 HTTP内容： { slave_ready: 0 } 权限验证失败： HTTP状态码：401 3.18 更新算时 请求地址：/update_online_time 请求方式：POST 请求参数： machine_id：机器ID user_id：用户ID delta：算时增量 响应参数： 权限验证通过： HTTP状态码：200 权限验证失败： HTTP状态码：401

3.19 重置密码 请求地址：/ResetPwd 请求方式：POST 请求参数： user_id：用户ID pwd：新密码 响应参数： 重置密码成功： HTTP状态码：200 HTTP内容： { pwd_reset: 1 } 重置密码失败： HTTP状态码：200 HTTP内容： { pwd_reset: 0 }

注释信息 机器剩余

注：编码方式均采用UTF8 注：请求类型错误均为403

接收ip，上线 提供slave ip 用户名 主机名

4.操作流程

4.1 登录流程 客户端：用户填写登录信息 客户端：向服务器通过”登录接口”发送登录信息(用户ID/邮箱，密码) 服务器：验证登录信息，更新数据库中机器状态，按照”登录接口”格式返回登录状态信息 客户端：显示登录后的界面 客户端：向服务器通过”公钥发送接口”发送自己的公钥 服务器：验证请求，将客户端公钥写入数据库 客户端：向服务器通过”IP发送接口”发送自己的IP地址 服务器：验证请求，将IP地址写入数据库 客户端：向服务器通过”获取所有上线节点信息接口”发送获取信息请求 服务器：验证请求，按照”获取所有上线节点信息接口”格式返回所有上线节点信息 客户端：显示所有上线节点信息

4.2 注册流程 客户端：用户填写注册信息 客户端：向服务器通过”注册接口”发送注册信息(邮箱，密码) 服务器：验证用户的注册信息，按照”注册接口”格式返回注册状态信息及用户ID 客户端：提示用户是否注册成功，若成功，需额外提示用户查看邮箱 客户端：用户填写激活邮箱中的验证码 服务器：验证激活信息，修改数据库，返回提示信息

4.3 修改个人信息流程 客户端：用户填写要修改的信息 客户端：向服务器通过”修改个人信息接口”发送用户填写的信息 服务器：验证要修改的信息，修改数据库，按照”修改个人信息接口”格式返回修改状态 客户端：根据修改状态显示提示信息

4.4 查看个人信息流程 客户端：用户选择查看个人信息 客户端：向服务器通过”查看个人信息接口”发送查看个人信息请求 服务器：验证查看个人信息请求，按照”查看个人信息接口”格式返回个人信息 客户端：显示相应信息

4.5 更新所有上线节点信息流程 客户端：定时器计时结束，或用户选择刷新所有上线节点 客户端：向服务器通过”获取所有上线节点信息接口”发送请求 服务器：验证请求，按照”获取所有上线节点信息接口”格式返回信息 客户端：更新相应信息

4.6 提交任务流程 master客户端：向服务器通过”任务发布接口”向服务器发送任务名称，自己的用户ID，自己的公钥，自己的机器ID，以及选中的机器的ID的列表 服务器：验证请求，在数据库中添加新的任务，存储master客户端公钥，向master客户端返回新建的任务ID 服务器：向被选中的机器通过SSH发送任务(包括任务名称，任务ID，master客户端公钥) slave客户端：接收服务器的任务，记录master客户端公钥，通过SSH向服务器返回自身状态 master客户端：定时向服务器发送请求查询slave是否准备就绪 服务器：响应master请求，若slave准备就绪，返回slave机器列表 master客户端：接收任务ID，以及参与该任务的机器ID的列表 注：由于存在机器掉线的情况，因此最后服务器返回的参与该任务的机器ID列表只保证是一开始master发送的选中机器ID列表的子集，不一定相同

4.7 结束任务流程 master客户端：通过”任务结束接口”向服务器发送任务ID等信息 服务器：验证请求，更新数据库中任务的状态

4.8 上传头像 客户端：用户选择要上传的头像 客户端：向服务器通过”上传头像接口”发送要上传的头像以及用户ID 服务器：验证请求，更新数据库，按照该”上传头像接口”格式返回上传状态 客户端：根据状态显示相应提示

4.9 更新算时 客户端：master发起新的任务，或者客户端下线时，向服务器通过”更新算时”接口发送自己的用户ID，以及增加的在线时长 服务器：验证请求，更新数据库中相应用户的时长信息

4.10 找回密码 客户端：用户选择忘记密码 客户端：用户输入用户ID或者邮箱 客户端：向服务器通过”找回密码”接口发送请求 服务器：验证请求，向客户的邮箱发送重置密码的邮件 用户：检查邮箱，获取重置邮件中的验证码 客户端：用户输入验证码，向服务器发送验证码 服务器：验证请求，返回邮箱验证是否成功 客户端：用户提交新密码，经哈希后上传服务器 服务器：验证请求，修改数据库中用户的密码，返回相应提示界面

4.11 机器下线 客户端：没有正在进行的任务，并且用户选择下线 客户端：向服务器通过”机器下线”接口向服务器发送包含机器ID的下线请求 服务器：验证请求，修改数据库中机器状态，并按照”机器下线”接口格式返回状态修改结果 客户端：根据修改结果显示相应信息 5.接口完成状态

登录 检查邮箱是否存在 注册 找回密码 修改个人信息 机器下线 查看个人信息 查看本机信息 获取相关节点信息 邮箱激活 上传头像 公钥发送 获取所有上线节点信息 IP发送 任务发布 任务结束 slave就绪情况 更新算时

■：已完成 ■：未完成 ■：未计划完成