第一章简介 RippleTek 节点配置 Web 服务 API 为开发者提供 HTTP 接口, 即开发者可通过发起包含 JSON 数据的 HTTP POST 请求, 向 RippleTek 节点管理服务器申请特定操作 ( 创建, 删除, 修改和获取节点数据 ) 用户可以使用此套 API 定制开发基于

Size: px

Start display at page:

Download "第一章简介 RippleTek 节点配置 Web 服务 API 为开发者提供 HTTP 接口, 即开发者可通过发起包含 JSON 数据的 HTTP POST 请求, 向 RippleTek 节点管理服务器申请特定操作 ( 创建, 删除, 修改和获取节点数据 ) 用户可以使用此套 API 定制开发基于"

蚁油宁
7 years ago
Views:

1 节点配置接口文档

2 第一章简介 RippleTek 节点配置 Web 服务 API 为开发者提供 HTTP 接口, 即开发者可通过发起包含 JSON 数据的 HTTP POST 请求, 向 RippleTek 节点管理服务器申请特定操作 ( 创建, 删除, 修改和获取节点数据 ) 用户可以使用此套 API 定制开发基于 RippleTek 热点解决方案的云端管理平台

3 第二章创建节点 2.1 适用场景用户可通过该方法创建一个新的节点 2.2 服务地址接口参数输入参数 : 参数名称参数类型参数描述默认值必选或者 api_id 请求创建此节点的用户号只能包含小写英必选文字符及数字, 长度为 16 个字符关于 api_id 和 api_key 的申请, 请参见附录 II api_key 请求创建此节点的用户密钥只能包含小写必选英文字符及数字, 长度为 32 个字符关于 api_id 和 api_key 的申请, 请参见附录 II name 节点名字, 只能包含数字, 大小写英文字符必选及下划线长度为个字符 description 节点描述可支持中文长度为个字 null 符 login_url 认证登陆页面地址, 即主动弹出认证页面必选长度为个字符 success_url 登陆认证成功页面地址长度为个必选字符 probation_url 试用认证成功页面地址如果用户在前端页 null 面调用试用接口, 认证成功后返回该地址长度为个字符 login_timeout 整数登陆认证成功后, 用户在无线网络范围内 1440 (Integer) 可以使用网络的时间该值的范围为 ( 分钟 )

4 probation_timeout 整数 (Integer) 试用认证成功后在无线网络范围内可以使用网络的时间该值的范围为 ( 分钟 ) 0 is_portal 是否开启认证功能,true 为开启,false 为 false 关闭 qq_login 是否开启 QQ 认证功能,true 为开启,false false 为关闭 weibo_login 是否开启新浪微博认证功能,true 为开启, false false 为关闭 weixin_login 是否开启微信认证功能 true 为开启,false false 为关闭 wx_id 绑定的微信号长度为个字符 null 如果 weixin_login 设置为 true, 则此参数必选 ; 否则其为 wx_name 绑定的微信名称长度为个字符 null 如果 weixin_login 设置为 true, 则此参数必选 ; 否则其为 wx_phone_only 是否仅允许有微信终端的手机认证,true 为 false 开启,false 为关闭 wx_unauth_timeout 整数认证未成功之前, 可以使用微信聊天和认证 5 (Integer) 的时间若在此设定时间之前, 用户未完成认证, 则其将被踢出网络此选项仅在 weixin_login 设置为 true 时有意义该值有效范围为 5-999( 分钟 ) wx_reject_timeout 整数用户被踢出网络后, 能重新使用网络的时间 3 (Integer) ( 关于用户何时可能被踢出网络, 请参见 wx_auth_timeout ) 此选项仅在 weixin_login 设置为 true 时才有意义该值有效范围为 ( 分钟 ) white_list 用户自定义的网址白名单名单中网址列表 null 是以, 分割的一组域名或 IP 地址该参数长度为个字符

5 hide_cp 是否开启 ios 不主动弹出弹窗,true 为开启, false false 为关闭 auth2nd 整数是否开启二次免认证,0 为不开启,1 为开 0 (Integer) 启免认证, 且二次无感知上网,2 为开启免认证, 但是二次需要看成功页面注 :1. 如果请求中包含任何上表中未列出的参数, 这些未定义的参数将被 RippleTek 服务器忽略 2. 如果上表中参数未包含在请求中, 或者传入值为 null, 则服务器将该参数值设为默认值 ; 同时必选值不能为 null 3. white_list 参数中白名单地址不应包含 scheme( 例如 ), 也不应包含可能的路径 ( 例如 /abc/def ) 以及任何参数 ( 例如?a=b&c=d ) 输出参数 : 参数名称参数类型参数说明 status 整数 (Integer) 如果创建节点成功, 返回 0; 否则返回一个非零错误代码关于错误代码与错误信息的定义请参看附录 I node 整数 (Integer) 如果创建节点成功, 返回一个合法节点号, 用户可用该节点号对该节点请求其他操作如果创建节点失败, 则回复中不包含此参数 err_msg 如果创建节点失败, 此参数包含关于错误信息的详细描述, 关于错误代码与错误信息的定义请参看附录 I 如果创建节点成功, 则回复中不包含此参数 2.4 接口示例请求示例 1: POST { "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj",

6 } "name":"test", "login_url":" "success_url":" 请求示例 2: POST { "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj", "name":"test", "description":"a description", "login_url":" "success_url":" "probation_url":" "login_timeout":60, "probation_timeout":10, "is_portal":true, "qq_login":fales, "weibo_login":false, "weixin_login":true, "wx_id":"rippletekhelper", "wx_name":"rippletekhelper", "wx_phone_only":true, "wx_unauth_timeout":6, "wx_reject_timeout":2, "white_list":" "hide_cp":false, "auth2nd":0, } 操作成功回复示例 : { "status": 0, "node : }

7 操作失败回复示例 : { "status": -1, "err_msg": "Bad request! Please validate the JSON format of your request." }

8 第三章更新节点 3.1 适用场景用户可通过该方法更新一个已创建节点的参数 3.2 服务地址接口参数输入参数 : 参数名称参数类型参数描述默认值必选或者 api_id 请求更新此节点的用户号只能包含小写英必选文字符及数字, 长度为 16 个字符关于 api_id 和 api_key 的申请, 请参见附录 II api_key 请求更新此节点的用户密钥只能包含小写必选英文字符及数字, 长度为 32 个字符关于 api_id 和 api_key 的申请, 请参见附录 II node 整数需要修改的节点的节点号节点号由服务器必选 (Interger) 在用户创建节点成功时返回 description 节点描述可支持中文长度为个字符 null login_url 认证登陆页面地址, 即主动弹出认证页面 ** 长度为个字符 success_url 登陆认证成功页面地址长度为个字 ** 符 probation_url 试用认证成功页面地址如果用户在前端页 null 面调用试用接口, 认证成功后返回该地址长度为个字符 login_timeout 整数登陆认证成功后, 用户在无线网络范围内可 1440 (Integer) 以使用网络的时间该值的范围为

9 ( 分钟 ) probation_timeout 整数 (Integer) 新试用认证成功后在无线网络范围内可以使用网络的时间该值的范围为 ( 分钟 ) 0 is_portal 是否开启认证功能,true 为开启,false 为关 false 闭 qq_login 是否开启 QQ 认证功能,true 为开启,false false 为关闭 weibo_login 是否开启新浪微博认证功能,true 开启, false false 为关闭 weixin_login 是否开启微信认证功能,true 为开启,false false 为关闭 wx_id 绑定的微信号长度为个字符 null * wx_name 绑定的微信名称长度为个字符 null * wx_phone_only 是否仅允许有微信终端的手机认证,true 为开 false 启,false 为关闭 wx_unauth_timeout 整数认证未成功之前, 可以使用微信聊天和认证 5 (Integer) 的时间若在此设定时间之前, 用户未完成认证, 则其将被踢出网络此选项仅在 weixin_login 设置为 true 时有意义该值有效范围为 5-999( 分钟 ) wx_reject_timeout 整数用户被踢出网络后, 能重新使用网络的时间 3 (Integer) ( 关于用户何时可能被踢出网络, 请参见 wx_auth_timeout ) 此选项仅在 weixin_login 设置为 true 时才有意义该值有效范围为 ( 分钟 ) white_list 用户自定义的网址白名单以, 分割的一组 null 域名或者 IP 地址长度为个字符 hide_cp 是否开启 ios 不主动弹出弹窗,true 为开启, false false 为关闭 auth2nd 整数是否开启二次免认证,0 为不开启,1 为开启 0

10 (Integer) 免认证, 且二次无感知上网,2 为开启免认证, 但是二次需要看成功页面注 :1. 如果请求中包含任何上表中未列出的参数, 这些未定义的参数将被 RippleTek 服务器忽略 2. 必选项不能为 null 若项( 不包含 ** 和 * ) 值为 null, 则该值会被重置为其默认值 3. 在 weixin_login 为 true 时, 若请求设置标记为 * 的参数为 null, 则该修改操作请求将被 RippleTek 服务器忽略 4. 若请求对标记为 ** 的参数修改为 null, 对该修改操作请求将被 RippleTek 服务器忽略 5. white_list 参数中白名单地址不应包含 scheme( 例如 ), 也不应包含可能的路径 ( 例如 /abc/def ) 以及任何参数 ( 例如?a=b&c=d ) 输出参数 : 参数名称参数类型参数说明 status 整数 (Integer) 如果更新节点成功, 返回 0; 否则返回一个非零错误代码关于错误代码与错误信息的定义请参看附录 I node 整数 (Integer) 如果更新节点成功, 并且返回申请修改的节点号如果更新节点失败, 则回复中不包含此参数 err_msg 如果更新节点失败, 此参数包含关于错误信息的详细描述, 关于错误代码与错误信息的定义请参看附录 I 如果更新节点成功, 则回复中不包含此参数 3.4 接口示例请求示例 POST { "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj", "node": 12345, "description":"a description", "login_url":"

11 } "success_url":" "probation_url":" "login_timeout":60, "probation_timeout":10, "is_portal":true, "qq_login":false, "weibo_login":false, "weixin_login":true, "wx_id":"rippletekhelper", "wx_name":"rippletekhelper", "wx_phone_only":true, "wx_unauth_timeout":6, "wx_reject_timeout":2, "white_list":" "hide_cp":true, "auth2nd":1 操作成功回复示例 : { "status": 0, "node : } 操作失败回复示例 : { "status": -1, "err_msg": "Bad request! Please validate the JSON format of your request." }

12 第四章删除节点 4.1 适用场景用户可通过该方法删除一个已经创建的节点 4.2 服务地址接口参数输入参数 : 参数名称参数类型参数描述必选或者 api_id 请求删除此节点的用户号只能包含小写英文字符及数字, 必选长度为 16 个字符关于 api_id 和 api_key 的申请, 请参见附录 II api_key 请求删除此节点的用户密钥只能包含小写英文字符及数字, 长度为 32 个字符关于 api_id 和 api_key 的申请, 请参见附录 II 必选 node 整数 (Interger) 节点号节点号由服务器在用户创建节点成功时返回必选注 : 如果用户请求中包含任何上表中未列出的参数, 这些未定义的参数将被 RippleTek 服务器忽略输出参数 : 参数名称参数类型参数说明 status 整数 (Integer) 如果删除节点成功, 返回 0; 否则返回一个非零错误代码关于错误代码与错误信息的定义请参看附录 I node 整数 (Integer) 如果删除节点成功, 并且返回申请删除的节点号如果删除节点失败, 则回复中不包含此参数 err_msg 如果删除节点失败, 此参数包含关于错误信息的详细描述, 关于错误代码与错误信息的定义请参看附录 I 如果删除节点成功, 则回复中不包含此参数

13 4.4 接口示例请求示例 POST { "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj", "node": } 操作成功回复示例 : { "status": 0, "node : } 操作失败回复示例 : { "status": -1, "err_msg": "Bad request! Please validate the JSON format of your request." }

14 第五章查询节点信息 5.1 适用场景用户可通过该方法查看一个已经创建的节点的参数 5.2 服务地址接口参数输入参数 : 参数名称参数类型参数描述必选或者 api_id 请求查询此节点的用户号只能包含小写英文字符及数字, 必选长度为 16 个字符关于 api_id 和 api_key 的申请, 请参见附录 II api_key 请求查询此节点的用户密钥只能包含小写英文字符及数字, 长度为 32 个字符关于 api_id 和 api_key 的申请, 请参见附录 II 必选 node 整数 (Interger) 节点号节点号由服务器在用户创建节点成功时返回必选注 : 如果用户请求中包含任何上表中未列出的参数, 这些未定义的参数将被 RippleTek 服务器忽略

15 输出参数 : 参数名称参数类型参数描述 status 整数 (Integer) 如果查询节点成功, 返回 0; 否则返回一个非零错误代码关于错误代 node 整数 (Interger) 节点号码与错误信息的定义请参看附录 I name 节点名字 description 或者 null 节点描述 login_url 认证登陆 ( 主动弹出 ) 页面地址, 即主动弹出认证页面 success_url 登陆认证成功页面地址 probation_url 或者 null 试用认证成功页面地址如果用户在前端页面调用试用接口, 认证成功后返回该地址 login_timeout 整数 (Integer) 登陆认证成功后在无线网络范围内可以使用网络的时间单位 : 分钟 probation_timeout 整数 (Integer) 试用认证成功后在无线网络范围内可以使用网络的时间单位 : 分钟 is_portal 是否开启认证功能,true 为开启,false 为关闭 qq_login 是否开启 QQ 认证功能,true 为开启,false 为关闭 weibo_login 是否开启新浪微博认证功能,true 为开启,false 为关闭 weixin_login 是否开启微信认证功能,true 为开启,false 为关闭 wx_id 绑定的微信号或者 null wx_name 绑定的微信名称或者 null wx_phone_only 是否仅允许有微信终端的手机认证,true 为开启,false 为关闭 wx_unauth_timeout 整数 (Integer) 认证未成功之前, 可以使用微信聊天和认证的时间若在此设定时间之前, 用户未完成认证, 则其将被踢出网络此选项仅在 weixin_login 设置为 true 时有意义 wx_reject_timeout 整数 (Integer) 用户被踢出网络后, 能重新使用网络的时间 ( 关于用户何时可能被踢

16 出网络, 请参见 wx_auth_timeout ) 此选项仅在 weixin_login 设置为 true 时才有意义 white_list 或者 null 用户自定义的网址白名单以, 分割的一组域名或者 IP 地址 hide_cp 是否开启 ios 不主动弹出弹窗,true 为开启,false 为关闭 create_time 整数 (Integer) 节点的创建时间,unix time update_time 整数 (Integer) 节点的最近一次更新时间,unix time err_msg 或者 null 仅当节点查询失败时, 返回此参数此参数包含关于错误信息的详细描述, 关于错误代码与错误信息的定义请参看附录 I 5.4 接口示例请求示例 : POST { "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj", "node": } 操作成功回复示例 : { "node": 12345, "name":"test", "description": null, "login_url":" "success_url":" "probation_url": null, "login_timeout":60, "probation_timeout":10,

17 } "is_portal":true, "qq_login":false, "weibo_login":false, "weixin_login":true, "wx_id":"rippletekhelper", "wx_name":"rippletekhelper", "wx_phone_only":1, "wx_unauth_timeout":6, "wx_reject_timeout":2, "white_list":" "hide_cp":1 操作失败回复示例 : { "status": -1, "err_msg": "Bad request! Please validate the JSON format of your request." }

18 第六章查询节点列表 6.1 适用场景用户可通过该方法查看自己已创建的节点列表 6.2 服务地址接口参数输入参数 : 参数名称参数类型参数描述必选或者 api_id 请求查询此节点的用户号只能包含小写英文字符及数字, 必选长度为 16 个字符关于 api_id 和 api_key 的申请, 请参见附录 II api_key 请求查询此节点的用户密钥只能包含小写英文字符及数字, 长度为 32 个字符关于 api_id 和 api_key 的申请, 请参见附录 II 必选注 : 如果用户请求中包含任何上表中未列出的参数, 这些未定义的参数将被 RippleTek 服务器忽略输出参数 : 参数名称参数类型参数描述 status 整数 (Integer) 如果查询节点成功, 返回 0; 否则返回一个非零错误代码关于错误代码与错误信息的定义请参看附录 I node_list 数组 (Array) 该数组的每个元素包含两个字段节点名称 name 和节点编号 node 6.4 接口示例请求示例 : POST

19 { } "api_id":"sjl7ufzuqcblcfdn", "api_key":"7jceafuxrrxi95hz/v2r7jmez3azfdsj", 操作成功回复示例 : { } "status":0, "node_list":[ {"name":"test node", "node":10023}, {"name":"customer node #1", "node":10025} ] 操作失败回复示例 : { "status": -6, "err_msg": "Your api_id or api_key are unauthorized for the operation." }

20 附录 I: 错误代码及相应消息定义错误代码 (status) 错误信息 (err_msg) 错误描述 -1 Bad request! Please validate the JSON format of your request. -2 One or more mandatory fields are missing from the request: <List of missing parameters>. -3 Parameter <parameter-name>'s value <parameter-value> is in erroneous format because it is <error-reason>. -4 An internal error has occurred, please have a try in a moment. -5 The node <node-id> that you have requested cannot be found. -6 Your api_id or api_key are unauthorized for the operation. -7 The node name <node-name> has already existed. Please choose another name for your new node. 用户请求的格式错误导致服务器不能识别用户的请求, 例如传入了非 JSON 格式的数据或者 JSON 格式错误等用户的输入参数中缺少必选的参数用户的输入参数格式没有满足参数列表中对参数的要求, 例如字符长度限制或者数字范围限制等服务器内部错误用户请求修改, 查询或者删除的节点并不存在用户提供的 <api_id, api_key> 不存在, 不匹配或者并无权限对请求的节点进行操作对于同一个用户, 不能创建同名节点, 因此创建重名节点的操作将被服务器被拒绝

22 附录 II: 申请 api_id 和 api_key 请使用您的 RippleTek 云端管理平台的 API 申请进行申请, 管理员会在一个工作日之内把审核结果反馈

第一章简介 RippleTek 微信认证服务 API 为开发者提供 HTTP 接口, 即开发者可通过发起包含 JSON 数据的 HTTP POST 请求, 向 RippleTek 微信认证服务器申请特定操作 ( 认证 URL 上网验证码取消认证和查询用户 OPENID) 开发者可以使用此套 API

微信认证接口文档 v1.1 第一章简介 RippleTek 微信认证服务 API 为开发者提供 HTTP 接口, 即开发者可通过发起包含 JSON 数据的 HTTP POST 请求, 向 RippleTek 微信认证服务器申请特定操作 ( 认证 URL 上网验证码取消认证和查询用户 OPENID) 开发者可以使用此套 API 定制开发基于 RippleTek 热点解决方案的微信认证管理第二章获取认证链接