适用场景分析

王者荣耀战绩查询API基于王者营地小程序接口封装，适合以下业务场景：

1. 第三方玩家查战绩工具：输入游戏昵称即可展示排位赛、巅峰赛、娱乐模式的近期KDA、胜负场次。
2. 电竞数据平台：批量抓取职业选手或高分段玩家的对局记录，用于赛后复盘或胜率统计。
3. 战队管理后台：自动拉取队员的排位表现，生成周报或段位变动图。
4. 直播弹幕机器人：观众发送“查战绩+昵称”，机器人实时返回该玩家最近战绩摘要。

该接口提供三种操作（action），覆盖从“找玩家”到“看战报”的完整链路，但需注意数据非实时（通常有数分钟延迟）以及单次请求仅支持单个玩家，不适合大规模并发爬取。

接口能力边界

三种操作与依赖关系

性能与延迟约束

• QPS上限：每秒2次，超过会被限流（返回HTTP 429）。
• 数据新鲜度：返回的战绩非实时，可能滞后5-15分钟，不适用于实时对局监控。
• 翻页限制：battles操作通过last_time游标翻页，pages最大为3，即一次最多拉取约90条记录。若需更早数据，需多次请求并拼接。
• 跨区限制：search操作可能无法精确找到指定区服的玩家（如微信区vs QQ区），返回的玩家列表需二次筛选。

请求参数与鉴权

鉴权方式

在HTTP Header中携带X-API-Key，值为从API平台获取的密钥。示例：

X-API-Key: your_actual_api_key

请求体字段说明

请求体为JSON对象，字段如下（所有字段均为字符串或数字，无嵌套对象）：

{ "action": "search | roles | battles", "keyword": "玩家昵称（仅search时需要）", "user_id": "玩家唯一标识（roles/battles时需要）", "role_id": "角色ID（仅battles时需要）", "last_time": 0, // Unix时间戳，0表示获取最新 "option": 0, // 模式筛选：0全部 1排位 2巅峰 3娱乐 "pages": 1 // 拉取页数（1-3） }

注意：last_time、option、pages仅在action为battles时生效，其他操作中传这些字段会被忽略。

curl接入示例

以下三个示例展示完整请求链路，请将$APIZERO_API_KEY替换为真实密钥。

1. 根据昵称搜索玩家

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"search","keyword":"梦之泪伤"}' \ "https://v1.apizero.cn/api/wzry-battle"

2. 获取某个玩家的角色列表（user_id从上一步响应中提取）

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"roles","user_id":"78564321"}' \ "https://v1.apizero.cn/api/wzry-battle"

3. 查询某个角色的排位赛历史战绩（最近10场）

curl -sS -X POST \ -H "X-API-Key: $APIZERO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"action":"battles","user_id":"78564321","role_id":"128903","option":1,"last_time":0,"pages":1}' \ "https://v1.apizero.cn/api/wzry-battle"

Python代码接入

使用requests库封装一个简洁的查询类，便于集成到项目：

import requests class WzryBattleAPI: BASE_URL = "https://v1.apizero.cn/api/wzry-battle" def __init__(self, api_key: str): self.headers = { "X-API-Key": api_key, "Content-Type": "application/json" } def search_player(self, keyword: str) -> dict: """搜索玩家，返回匹配玩家列表""" payload = {"action": "search", "keyword": keyword} resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() def get_roles(self, user_id: str) -> dict: """获取玩家角色列表""" payload = {"action": "roles", "user_id": user_id} resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() def get_battles(self, user_id: str, role_id: str, option: int = 0, last_time: int = 0, pages: int = 1) -> dict: """获取战绩列表""" payload = { "action": "battles", "user_id": user_id, "role_id": role_id, "option": option, "last_time": last_time, "pages": pages } resp = requests.post(self.BASE_URL, headers=self.headers, json=payload) resp.raise_for_status() return resp.json() # 使用示例 if __name__ == "__main__": api = WzryBattleAPI("your_api_key_here") # 第一步：搜索 search_res = api.search_player("花木兰") print("搜索结果:", search_res) # 实际使用时需从data字段中提取user_id

注意：以上代码未处理错误和限流，生产环境需增加重试和退避逻辑。

返回值结构解读

所有操作均返回如下顶层结构：

{ "code": 200, "data": {}, "message": "success" }

• code：200表示成功，非200表示出错（参考错误列表）。
• message：请求状态描述。
• data：具体数据，不同操作字段差异较大。
  • search：data通常包含player_list数组，每个元素含user_id、nickname、avatar_url等。
  • roles：data包含role_list数组，每个元素含role_id、role_name、area（微信/QQ）、platform（安卓/iOS）、level等。
  • battles：data包含battle_list数组和next_time（下次翻页游标），每条记录含英雄名、KDA、胜负、模式、时间戳等。

由于原始文档未提供完整的字段清单，具体键名请以实际响应或官方文档为准。建议先调用一次search获取响应后再解析。

常见错误与排查

若返回code为200但data为空对象，可能是查询无结果或参数组合不匹配，建议先调用search确认玩家存在。

工程化注意事项

1. 缓存设计：同一玩家的角色列表变动极小，可缓存12小时以上；战绩数据可缓存5-10分钟，避免重复请求触发限流。
2. 异步与队列：使用异步框架（如asyncio+aiohttp）或任务队列（Celery），将多个查战绩请求分散到不同时间窗口，确保QPS不超限。
3. 降级策略：当API返回429或500时，从本地缓存返回最近一次成功结果，并记录异常日志。
4. 参数校验：在发起请求前检查keyword非空、user_id/role_id为纯数字（根据实际格式），减少无效请求。
5. 异常处理：捕获网络超时（默认超时设为10秒）、连接错误，做重试（最多3次，指数退避）。
6. 文档同步：API可能升级，定期轮询官方文档更新字段或地址。

参考文档

• 官方文档页：https://apizero.cn/aidocs/wzry-battle
• 原始Markdown文档：https://apizero.cn/aidocs/wzry-battle/raw.md
• 若需了解其他游戏数据接口，可查看同一平台下的分类目录。