ecapi-sdk 0.1.2

ECAPI SDK for Python

ecapi-sdk (Python)

ECAPI 的 Python SDK，封装了常用接口，并内置两种鉴权方式：

• X-API-Key（IAM API Key）
• X-App-Session-Token（App Session Token）

安装

pip install ecapi-sdk

快速开始

from ecapi_sdk import ECAPIClient

client = ECAPIClient(
    base_url="https://your-ecapi-host",
    auth={"type": "apiKey", "apiKey": "ec_xxx"},
)

me = client.user.get_me()
player = client.player.get_info({"name": "player123"})
wallet = client.player.get_wallet(ecid="player-ecid")

切换为 App Session Token：

client.set_app_session_token("your_app_session_token")

客户端能力

• 统一请求入口：client.request(method, path, ...)
• 默认超时：15 秒（timeout_seconds 可覆盖）
• 支持 per-request 覆盖鉴权：auth=...
• 非 2xx 响应抛出 ECAPIError（包含 status、payload、url）

参数传递（必填/可选）

• 所有带查询参数的接口都支持两种写法：
  • 推荐：关键字参数（更直观）client.player.get_wallet(ecid="...")
  • 兼容：字典参数 client.player.get_wallet({"ecid": "..."})
• 哪些字段必填、哪些可选，请直接看完整参考文档：API_REFERENCE.md
• 该参考文档由后端 OpenAPI 自动生成，和服务端校验保持一致

IDE 强类型提示

• 包内提供 client.pyi，IDE 会在悬停和参数填写时显示方法级必填/可选信息
• 查询参数支持两种输入方式：
  • query 结构化参数（会有 TypedDict 提示）
  • 关键字参数（例如 ecid=...）

API 覆盖

SDK 已封装主要高频接口；其余接口可用 client.request(...) 直调。

用户

• client.user.get_me() → GET /user/me
• client.user.login_by_password(payload) → POST /user/auth
• client.user.login_by_oauth2(payload) → POST /user/oauth2
• client.user.refresh_token(payload) → POST /user/refresh
• client.user.get_openid() → GET /user/openid
• client.user.list_all() → GET /user/all
• client.user.update_permissions(payload) → PUT /user/permissions
• client.user.get_by_id(id) → GET /user/:id

玩家

• client.player.get_info() / search_ecid() / get_user_data() / query_netease()
• client.player.set_rank_level(payload) / clear_respack_cache()
• client.player.get_wallet() / list_gaming_tags() / operate_gaming_tag(payload)
• client.player.get_last_played() / get_stage_record()
• client.player.get_headicon() / get_skin()（返回 bytes）
• client.player.batch_netease_nicknames(payload)
• client.player.get_binding() / reset_binding(payload) / update_binding(payload)
• client.player.update_user_data(nick, payload)
• client.player.update_password(ecid, payload) / get_password_hash(ecid)

玩家子模块

• client.player.score.* → /player/score*
• client.player.tasks.* → /player/:ecid/tasks*
• client.player.merchandise.* → /player/:ecid/merchandise*
• client.player.year_summary.* → /player/year-summary/*
• client.player.vote.process_rewards() → GET /player/vote

管理与处罚

• client.admin.* → /admin/*
• client.punish.* → /punish/*
• client.ban.* → /ban/*
• client.permission.* → /permission

日志与审计

• client.log.* → /log/*
• client.audit.* → /audit/*

配置与内容

• client.stage.*（含 stage.logs.*）→ /stage/*
• client.item.get_commodity() → /item/commodity
• client.cfglang.* → /cfglang*
• client.globalkv.* → /globalkv*
• client.broadcast.* → /broadcast*
• client.pull_config.pull() → /pull-config

运营与系统

• client.order.* → /order/*
• client.count.* → /count/*
• client.servers.* → /servers*
• client.lobby.list() → /lobby/list
• client.easechat.* → /easechat/*
• client.monitor.spam_detector.* → /monitor/spam-detector/*
• client.system.get_health() → /health

完整 API 参考

• API_REFERENCE.md

更新命令（在 easecation-api 根目录执行）：

python3 sdk/generate_sdk_api_reference.py