ESI专业研究理论

ESI，全称EVE Swagger Interface（EVE史瓦格接口）
ESI，是一种以Open API为规范的API接口
ESI简单来说，是一种不用登录游戏，就能对EVE世界进行探索与改变的一种途径，即：

• 探索：获取游戏状态、玩家、NPC的各种情况，以及部分游戏机制
• 改变：简单的设置与修改（例如：邮件的发送删除、导航地址的设定）

国服网易的ESI官网（开发文档）网址为https://ali-esi.evepc.163.com/，您也可以在茄盟官网顶栏“外部链接”中找到该链接
注：本文重点对需要授权的ESI进行讨论
注：快速查看结论请跳转至ESI常见问答
注：实名参数问题请跳转至ESI实名参数认证失败解决方案

ESI主要有2种，公开查询型、认证查询型：

1. 公开型：EVE服务器情况（是否在维护、在线人数）、游戏内容数据（萨沙入侵、地点安等）、市场数据、舰船装备属性、NPC属性等；
   1. 玩家在游戏中能共享查看的信息，例如：右键属性
   2. 这种信息每个人都能轻易获取，例如：舰船保险价格、工业指数、军团介绍等。
   3. 玩家不容易查询到的游戏机制，例如：怪的转火机制、NPC火力防御属性
2. 认证型：玩家钱包、军团建筑解锚、联系人、邮件收发、驾驶船只、玩家所在地点等；
   1. 只有玩家自己能看到，别人不一定能看到的信息，是机密的；
   2. 认证型需要玩家授权特定权限之后，才能在游戏外查询，例如：KB网、3V联盟ESI绑定、茄盟ESI授权等。
   3. 本文将重点讲述“认证型ESI”

认证型的ESI由约66种权限构成，玩家在授权时可以选择是否提供这些权限，就像手机APP索要权限需要你确认一样，所以这里应该把：

• “ESI绑了就是底裤被看光”
  

这种盖棺定论，改成：

• “绑了授权过多的ESI底裤才会被看光”
  

才是合理的，具体会在后文的“ESI授权认证”处会详细解释，下面将介绍如何区分“公开型”与“认证型”的ESI项目。

• 如图，打开ESI开发文档网站，“军团”列表处，右边尾部，绿灯旁边，带有锁头的，是“认证型”；其余则是“公开型”
  

• 两种类型的ESI在EVE服务器维护时（一般为北京时间早上11点），将无法获取信息
  
• 认证型ESI和公开型ESI的根本区别是，认证型需要多一个参数“access_token”，才能进行查询，这个是个关键的参数，ESI网站是否会给你返回数据，取决于你是否提供了正确的“access_token”，所以这是授权成功的关键，这些下文将会细讲

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，服务器才会返回给你想查询的数据。

• 同时注意，网易的没有给详细的认证开发文档，很多参数需要自行摸索，下文将展示茄盟研究出的参数情况，仅供参考。

认证总览：直接获取access_token 步骤：

1. 向服务器发起GET请求，表述请求权限内容与类型，地址如下：
   1. 地址：https://login.evepc.163.com/v2/oauth/authorize，参数如下：
      1. response_type：表示授权类型，必选项，此处的值固定为“token”
      2. client_id：表示客户端的ID，必选项
      3. redirect_uri：表示重定向URI，必选项
      4. state：表示客户端的当前状态，可以指定任意值，必选项
      5. scope：表示申请的权限范围，不可超过4项，例如：esi-skills.read_skillqueue.v1
2. 在返回的页面，完成网易的邮箱账号认证后，将会在浏览器地址栏返回一串网址，内容如下：
   1. access_token：权限令牌，有了它，你可以读取你游戏人物对应的私密内容
   2. expires_in：过期时间，单位为秒，一般为20分钟
   3. state：服务端原封不动返回的值

缺点：access_token时间较短，且获取流程需要人工操作，不适合大规模长期使用；
优点：安全性极高，20分钟后，access_token失效，想要权限就得再次认证，属于阅后即焚，无后顾之忧。

认证总览：获取code，用code获取access_token和refresh_token，再利用refresh_token获取新的access_token 步骤：

1. 向服务器发起GET请求，表述请求权限内容与类型，地址如下：
   1. 地址：https://login.evepc.163.com/v2/oauth/authorize，参数如下：
      1. response_type：表示授权类型，必选项，此处的值固定为“code”
      2. client_id：表示客户端的ID，必选项
      3. redirect_uri：表示重定向URI，必选项
      4. state：表示客户端的当前状态，可以指定任意值，必选项
      5. scope：表示申请的权限范围，不可超过4项，例如：esi-skills.read_skillqueue.v1
2. 在返回的页面，完成网易的邮箱账号认证后，将会在浏览器地址栏返回一串网址，内容如下：
   1. code：表示授权码、有效期应该很短，通常为10分钟，且只能使用该码一次
   2. state：服务端原封不动返回的值
3. 获取refresh_token，向服务器发起POST请求，表述请求权限内容与类型，地址如下：
   1. 地址：https://login.evepc.163.com/v2/oauth/token，参数如下：
      1. grant_type：表示获取类型，必选项，此处的值固定为“authorization_code”
      2. client_id：表示客户端的ID，必选项
      3. redirect_uri：表示重定向URI，必选项
      4. code：刚刚获取的授权码
4. 会返回一串内容，具体如下：
   1. access_token：权限令牌，有了它，你可以读取你游戏人物对应的私密内容
   2. expires_in：过期时间，单位为秒，一般为20分钟
   3. refresh_token：刷新access_token用的，没有时间限制，永久有效（除非长期不使用）
5. 利用refresh_token获取新的access_token，向服务器发起POST请求，表述请求权限内容与类型，地址如下：
   1. 地址：https://login.evepc.163.com/v2/oauth/token，参数如下：
      1. grant_type：表示获取类型，必选项，此处的值固定为“refresh_token”
      2. refresh_token：上一步或之前获取的刷新密令
      3. client_id：表示客户端的ID，必选项
6. 会返回一串内容，同4

缺点：认证流程很复杂难懂，和正则表达式一样苦涩，且refresh_token泄露等于泄露银行卡密码一样；
优点：可持续性，生生不息，维护难度小，学会之后如正则表达式一样非常爽，魔法和奇迹都是有代价的！

很多情况下，我们需要使用玩家的ID才能完成认证型ESI的信息查询

但我们只有玩家给予的access_token，再去问玩家的游戏ID就显得很繁琐，那怎么才能获取到这个access_token的主人的ID呢？

Oauth2.0常用的check_token或者introspect获取绑定信息的办法，在网易的EVE服务器认证中并没有开通，所以我们只能另找办法。这里提供其中的2种方法供参考：

• 请求方式：GET
• 地址：https://ali-esi.evepc.163.com/verify
• 参数：
  • 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

仔细观察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

方法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个月不使用，会被服务器清理，具体时间待验证

1. 只有在access_token未过期的情况下，查询才不会报错
2. GET和POST请求时注意转换成url格式
3. 接收到的数据一般为UTF-8格式、Unicode（UCS-2）编码
4. 注意ESI更新的时间间隔限制（可以用SSAA超采技术解决）
5. refresh_token不会过期也不会被顶掉，请勿泄露（但长期不使用，也会被服务器清除导致失效）
6. code只有10分钟期限，且只能用一次
7. 每日维护时间（上午11点），大部分ESI无法正常使用
8. ESI只是一项技术，如何使用，看各家情况
9. 由于网易对cookie的管理有BUG，建议使用“无痕模式”进行ESI操作或访问EVE Logoff，无视报错，关闭页面即可退出登录
   1. 或者采用“https://login.evepc.163.com/account/logoff?returnUrl=”+“【重定向地址的url编码格式】”可以实现清除cookie
10. 返回的时间为冰岛时间（0时区），换算成北京时间请+8h
11. ESI里面的图片服务器有误，应该为 https://image.evepc.163.com/Home

为了消除玩家对ESI的恐惧与误解，以下将介绍一些ESI的误区与能授权直接看到的东西：

1. 钱包：包括转账记录、交易记录（没错，就是空间站右键交易）、余额、市场买卖、忠诚点等
   1. 授权项目例子：esi-wallet.read_character_wallet.v1、esi-wallet.read_character_wallet.v1、esi-characters.read_loyalty.v1
   2. 无法读取的有：LP消费记录、LP收益来源（可以通过消息列表间接查询到2022.11.4注）
2. 玩家实况：包括驾驶的船只、所在地点、登录情况等
   1. 授权项目例子：esi-location.read_location.v1、esi-location.read_ship_type.v1、esi-corporations.track_members.v1
   2. 无法读取的有：开火记录、货柜内容、拾取记录
3. 建筑：包括建筑地点、燃料耗尽时间、增强情况、增强时间、服务类型与上线情况、解锚时间（精确到秒）等
   1. 授权项目例子：esi-corporations.read_structures.v1（需要军团对应权限）
   2. 无法读取的有：精确的燃料剩余数目、装备情况、建筑内人数、移动式仓库
4. 私人机密：包括邮件（收、发、具体内容）、个人位标、资产、克隆、合同、联系人、种菜地址、工业制造情况等
   1. 授权项目例子：esi-bookmarks.read_character_bookmarks.v1、esi-assets.read_assets.v1
   2. 无法读取的有：聊天框、笔记本
5. 舰队：包括舰队拉人、踢人、增减中队、设置舰队广告、舰队人员移动
   1. 授权项目例子：esi-fleets.write_fleet.v1、esi-fleets.read_fleet
   2. 无法实现的有：创建舰队、解散舰队（当然，踢走所有人也不是不可以）

以上为常见的一些ESI授权与直接应用，但并不是代表全部的应用，因为有些ESI不提供的数据，可以根据另外的已提供的数据，分析推导间接得出来，这个就要看各家代码工程师或数学家的各显神通了（就像柯南一样）。

由于大环境因素，实名认证有时会出现BUG，有3种解决方案，详情如下：

1. 游戏内申述：F12，点击“创建新申诉”，向GM进行反馈；
2. 实名认证检查：进入网易账号安全中心，点击“实名防沉迷”，查看实名认证情况（姓名证件号是否匹配，是否为本人等）；
3. 人工反馈：在网易游戏客服中心提交申诉。

• 如果以上3个方案依旧无法解决，尝试在网易帮助中心，或者拨打EVE端游客服电话95163995咨询；
• 实名认证情况有误，可以在客服中心反馈咨询；
• 申诉解决周期约为1-3个工作日；
• 本条目暂时只针对“邮箱账号”，可能手机账号不适用

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成员，极大体现再分配优势，精准扶贫，促进联盟税收合理分配。  

网易ESI官网

网易EVE官网

贴吧ESI科普（启发我最大的一个帖子之一）

欧服ESI简介

欧服ESI官网

欧服ESI文档

欧服ESI早期个人博客

欧服SDE

实名认证公告1

实名认证公告2

https://developers.eveonline.com/blog/article/sso-endpoint-deprecations-2

— Mcstuffins [SR] 2022/10/16