ESI专业研究理论
ESI概述
ESI,全称EVE Swagger Interface(EVE史瓦格接口)
ESI,是一种以Open API为规范的API接口
ESI简单来说,是一种不用登录游戏,就能对EVE世界进行探索与改变的一种途径,即:
- 探索:获取游戏状态、玩家、NPC的各种情况,以及部分游戏机制
- 改变:简单的设置与修改(例如:邮件的发送删除、导航地址的设定)
国服网易的ESI官网(开发文档)网址为https://ali-esi.evepc.163.com/,您也可以在茄盟官网顶栏“外部链接”中找到该链接
注:本文重点对需要授权的ESI进行讨论
注:快速查看结论请跳转至ESI常见问答
注:实名参数问题请跳转至ESI实名参数认证失败解决方案
ESI类型
类型介绍
ESI主要有2种,公开查询型、认证查询型:
- 公开型:EVE服务器情况(是否在维护、在线人数)、游戏内容数据(萨沙入侵、地点安等)、市场数据、舰船装备属性、NPC属性等;
- 玩家在游戏中能共享查看的信息,例如:右键属性
- 玩家不容易查询到的游戏机制,例如:怪的转火机制、NPC火力防御属性
- 认证型:玩家钱包、军团建筑解锚、联系人、邮件收发、驾驶船只、玩家所在地点等;
- 只有玩家自己能看到,别人不一定能看到的信息,是机密的;
- 认证型需要玩家授权特定权限之后,才能在游戏外查询,例如:KB网、3V联盟ESI绑定、茄盟ESI授权等。
- 本文将重点讲述“认证型ESI”
认证型的ESI由约66种权限构成,玩家在授权时可以选择是否提供这些权限,就像手机APP索要权限需要你确认一样,所以这里应该把:
- “ESI绑了就是底裤被看光”
这种盖棺定论,改成:
- “绑了授权过多的ESI底裤才会被看光”
才是合理的,具体会在后文的“ESI授权认证”处会详细解释,下面将介绍如何区分“公开型”与“认证型”的ESI项目。
类型区分
- 如图,打开ESI开发文档网站,“军团”列表处,右边尾部,绿灯旁边,带有锁头的,是“认证型”;其余则是“公开型”
- 两种类型的ESI在EVE服务器维护时(一般为北京时间早上11点),将无法获取信息
- 认证型ESI和公开型ESI的根本区别是,认证型需要多一个参数“access_token”,才能进行查询,这个是个关键的参数,ESI网站是否会给你返回数据,取决于你是否提供了正确的“access_token”,所以这是授权成功的关键,这些下文将会细讲
ESI授权
ESI授权也称ESI绑定,方式采用Oauth 2.0认证方式,想要挖掘出网易ESI的秘密,请读者重点阅读Oauth 2.0的4种认证方式:
- authorization(授权码模式)
- implicit(简化模式)
- password(密码模式)
- client(客户端模式)
本文不再赘述认证的具体流程与原理,请读者自行研究,特别是认证的流程图,请务必完全理解透彻。
注意:本小节内容对计算机网络知识要求较高,非专业者请多方查阅资料辅助阅读(编者为师范专业,所以我相信各位读者有能力解决这个问题的 ( •̀ ω •́ )✧)
经过调查,国服常用的几个网站的对ESI授权的方式汇总如下:
- KB网:authorization,授权码模式,能长期认证
- 3V的ESI:同上
- 茄盟新ESI:同上
- 网易ESI官网:implicit,简化模式,只有20分钟期限(如下图)
- 茄盟旧技能奖励ESI:同上
password(密码模式)和client(客户端模式)经检验,网易没有开放,故本文只讨论authorization(授权码模式)与implicit(简化模式),两者的本质都是获取认证最需要的access_token,有了正确且未过期的access_token,服务器才会返回给你想查询的数据。
- 同时注意,网易的没有给详细的认证开发文档,很多参数需要自行摸索,下文将展示茄盟研究出的参数情况,仅供参考。
Implicit模式
认证总览:直接获取access_token 步骤:
- 向服务器发起GET请求,表述请求权限内容与类型,地址如下:
-
- response_type:表示授权类型,必选项,此处的值固定为“token”
- client_id:表示客户端的ID,必选项
- redirect_uri:表示重定向URI,必选项
- state:表示客户端的当前状态,可以指定任意值,必选项
- scope:表示申请的权限范围,不可超过4项,例如:esi-skills.read_skillqueue.v1
-
- 在返回的页面,完成网易的邮箱账号认证后,将会在浏览器地址栏返回一串网址,内容如下:
- access_token:权限令牌,有了它,你可以读取你游戏人物对应的私密内容
- expires_in:过期时间,单位为秒,一般为20分钟
- state:服务端原封不动返回的值
缺点:access_token时间较短,且获取流程需要人工操作,不适合大规模长期使用;
优点:安全性极高,20分钟后,access_token失效,想要权限就得再次认证,属于阅后即焚,无后顾之忧。
Authorization模式
认证总览:获取code,用code获取access_token和refresh_token,再利用refresh_token获取新的access_token 步骤:
- 向服务器发起GET请求,表述请求权限内容与类型,地址如下:
-
- response_type:表示授权类型,必选项,此处的值固定为“code”
- client_id:表示客户端的ID,必选项
- redirect_uri:表示重定向URI,必选项
- state:表示客户端的当前状态,可以指定任意值,必选项
- scope:表示申请的权限范围,不可超过4项,例如:esi-skills.read_skillqueue.v1
-
- 在返回的页面,完成网易的邮箱账号认证后,将会在浏览器地址栏返回一串网址,内容如下:
- code:表示授权码、有效期应该很短,通常为10分钟,且只能使用该码一次
- state:服务端原封不动返回的值
- 获取refresh_token,向服务器发起POST请求,表述请求权限内容与类型,地址如下:
-
- grant_type:表示获取类型,必选项,此处的值固定为“authorization_code”
- client_id:表示客户端的ID,必选项
- redirect_uri:表示重定向URI,必选项
- code:刚刚获取的授权码
-
- 会返回一串内容,具体如下:
- access_token:权限令牌,有了它,你可以读取你游戏人物对应的私密内容
- expires_in:过期时间,单位为秒,一般为20分钟
- refresh_token:刷新access_token用的,没有时间限制,永久有效(除非长期不使用)
- 利用refresh_token获取新的access_token,向服务器发起POST请求,表述请求权限内容与类型,地址如下:
-
- grant_type:表示获取类型,必选项,此处的值固定为“refresh_token”
- refresh_token:上一步或之前获取的刷新密令
- client_id:表示客户端的ID,必选项
-
- 会返回一串内容,同4
缺点:认证流程很复杂难懂,和正则表达式一样苦涩,且refresh_token泄露等于泄露银行卡密码一样;
优点:可持续性,生生不息,维护难度小,学会之后如正则表达式一样非常爽,魔法和奇迹都是有代价的!
详细的参数由于介质因素不作具体介绍,如想得知,请在文末参考链接寻找线索,或联系本文作者-茄盟著名研究员mc
ESI绑定ID的查询
很多情况下,我们需要使用玩家的ID才能完成认证型ESI的信息查询
但我们只有玩家给予的access_token,再去问玩家的游戏ID就显得很繁琐,那怎么才能获取到这个access_token的主人的ID呢?
Oauth2.0常用的check_token或者introspect获取绑定信息的办法,在网易的EVE服务器认证中并没有开通,所以我们只能另找办法。这里提供其中的2种方法供参考:
方法一:网易ESI验证
- 请求方式:GET
- 参数:
- token:这里只接受access_token
返回的参数如下:
- 格式为JSON
- CharacterID:人物ID
- CharacterName:人物名字
- ExpiresOn:过期时间(冰岛时间)
- TokenType:token类型
- CharacterOwnerHash:人物的哈希值
- ClientID:绑定在的中间服务器ID
参考地址:
https://ali-esi.evepc.163.com/ui/?version=meta#/Meta/get_verify
方法二:JWT令牌解码
仔细观察access_token,是被2个“.”分成了3部分,这其实是一个JWT令牌:
- Header(头)
- Payload(负载)
- Signature(签名)
第二部分的Payload(负载)可经过base64解码,得到一个json数据,里面的“name”属性即为对应玩家的名字。
参考地址:
https://auth0.com/docs/secure/tokens/access-tokens/validate-access-tokens
https://zhuanlan.zhihu.com/p/370670759
ESI解绑
方法A:进入网易EVE官网,右上角“ESI解除授权”处,可以使上文中所有的“access_token”与“refresh_token”全部失效
方法B:参考Oauth2.0的“revoke”用法,可以选择性使得上文中的“access_token”与“refresh_token”失效
- 如果出现解绑界面无法登录,可能为网易对cookie的管理有bug,请试试使用浏览器的“无痕登录”模式,或点击https://login.evepc.163.com/account/logoff(无视报错),即可清除cookie
- 非必要情况下不建议解绑ESI,这会导致KB网登录失效,同时也会影响茄盟刷怪计税的统计,3v联盟马甲的查询(当然,请具体情况具体分析,别乱扣帽子和盖棺定论,这篇文章以学术为主,不代表联盟或个人立场)
- 至于必要情况,例如:建筑团总监ESI泄露,其他人能看到具体的解锚时间,这个就必须得解绑了
方法C:refresh_token理论上,约1.5个月不使用,会被服务器清理,具体时间待验证
ESI使用注意事项
- 只有在access_token未过期的情况下,查询才不会报错
- GET和POST请求时注意转换成url格式
- 接收到的数据一般为UTF-8格式、Unicode(UCS-2)编码
- 注意ESI更新的时间间隔限制(可以用SSAA超采技术解决)
- refresh_token不会过期也不会被顶掉,请勿泄露(但长期不使用,也会被服务器清除导致失效)
- code只有10分钟期限,且只能用一次
- 每日维护时间(上午11点),大部分ESI无法正常使用
- ESI只是一项技术,如何使用,看各家情况
- 由于网易对cookie的管理有BUG,建议使用“无痕模式”进行ESI操作或访问EVE Logoff,无视报错,关闭页面即可退出登录
- 或者采用“https://login.evepc.163.com/account/logoff?returnUrl=”+“【重定向地址的url编码格式】”可以实现清除cookie
- 返回的时间为冰岛时间(0时区),换算成北京时间请+8h
- ESI里面的图片服务器有误,应该为 https://image.evepc.163.com/Home
ESI范围概述
为了消除玩家对ESI的恐惧与误解,以下将介绍一些ESI的误区与能授权直接看到的东西:
- 钱包:包括转账记录、交易记录(没错,就是空间站右键交易)、余额、市场买卖、忠诚点等
- 授权项目例子:esi-wallet.read_character_wallet.v1、esi-wallet.read_character_wallet.v1、esi-characters.read_loyalty.v1
- 无法读取的有:
LP消费记录、LP收益来源(可以通过消息列表间接查询到2022.11.4注)
- 玩家实况:包括驾驶的船只、所在地点、登录情况等
- 授权项目例子:esi-location.read_location.v1、esi-location.read_ship_type.v1、esi-corporations.track_members.v1
- 无法读取的有:开火记录、货柜内容、拾取记录
- 建筑:包括建筑地点、燃料耗尽时间、增强情况、增强时间、服务类型与上线情况、解锚时间(精确到秒)等
- 授权项目例子:esi-corporations.read_structures.v1(需要军团对应权限)
- 无法读取的有:精确的燃料剩余数目、装备情况、建筑内人数、移动式仓库
- 私人机密:包括邮件(收、发、具体内容)、个人位标、资产、克隆、合同、联系人、种菜地址、工业制造情况等
- 授权项目例子:esi-bookmarks.read_character_bookmarks.v1、esi-assets.read_assets.v1
- 无法读取的有:聊天框、笔记本
- 舰队:包括舰队拉人、踢人、增减中队、设置舰队广告、舰队人员移动
- 授权项目例子:esi-fleets.write_fleet.v1、esi-fleets.read_fleet
- 无法实现的有:创建舰队、解散舰队(当然,踢走所有人也不是不可以)
以上为常见的一些ESI授权与直接应用,但并不是代表全部的应用,因为有些ESI不提供的数据,可以根据另外的已提供的数据,分析推导间接得出来,这个就要看各家代码工程师或数学家的各显神通了(就像柯南一样)。
ESI实名参数报错解决方案
由于大环境因素,实名认证有时会出现BUG,有3种解决方案,详情如下:
- 游戏内申述:F12,点击“创建新申诉”,向GM进行反馈;
- 实名认证检查:进入网易账号安全中心,点击“实名防沉迷”,查看实名认证情况(姓名证件号是否匹配,是否为本人等);
- 人工反馈:在网易游戏客服中心提交申诉。
- 如果以上3个方案依旧无法解决,尝试在网易帮助中心,或者拨打EVE端游客服电话95163995咨询;
- 实名认证情况有误,可以在客服中心反馈咨询;
- 申诉解决周期约为1-3个工作日;
- 本条目暂时只针对“邮箱账号”,可能手机账号不适用
重要提醒:任何需要输入账号密码与个人身份信息的网站,请确认其顶级域名是否为163.com!
ESI常见问答
1.问:ESI会看我的一切信息吗?
1.答:不一定。这取决于你允许的授权项目数量;在你输入完你的账号密码,点击“授权”之前,会提示你授权的项目,请核实好后,三思而授权。 此外,IP地址、角色数量、账号密码等信息ESI是无法查看的。
2.问:ESI能解绑吗?
2.答:能。无痕模式访问https://evepc.163.com/,右上角“ESI解除绑定”。
3.问:ESI绑定会不会泄露密码?
3.答:不会。ESI绑定采用先进的Oauth 2.0认证,绑定网站(联盟或军团)没有办法获取你的账号密码,并请留意输入账号密码的页面是否为网易的域名(163.com)。任何直接索要你账号密码的联盟或军团行为请留意,自行判断。
4.问:ESI绑定后会过期吗?
4.答:不一定。看各联盟军团采用的绑定方式,code是10分钟、access_token是20分钟,refresh_token是长期不使用才会失效。详情可以阅读仔细完上文。
5.问:ESI技术成熟吗?
5.答:成熟。KB网、EVE市场、合同助手、pyfa、船老板等著名EVE工具都应用了ESI技术。
6.问:茄盟ESI技术是谁研究出来的?
6.答:“千秋燎原”主体导入,“Mcstuffins”关键突破。
7.问:茄盟ESI如何绑定?
7.答:访问http://lms.wdnmd.biz/,联系军团总监询问注册方式。
8.问:为什么要绑茄盟ESI?
8.答:茄盟为PVP联盟,为鼓励PVP成员,需要识别出非PVP成员,极大体现再分配优势,精准扶贫,促进联盟税收合理分配。