GAMEMONITORING API
GAMEMONITORING REST API 返回服务器、玩家、帖子、在线历史和投票的 JSON 数据。本页介绍集成基础及第一个请求,参数说明和请求测试位于各接口页面。
API 版本
可以通过可选的查询参数 v 指定 API 版本。当前版本为 1.0.0。版本决定可用路径、请求字段和响应格式。
不传 v 时使用最低受支持版本。该版本停用后,下一个最低受支持版本成为默认版本。显式传入 v 可固定接口契约。无效、重复或不受支持的版本返回 HTTP 400;不受支持版本的可用值列表位于 error.data.supported_versions。
选择接口
打开接口页面即可查看必填参数、响应结构、不同语言的示例,并测试请求。添加服务器会执行实际操作,公开的读取接口仅返回数据。
通过连接地址添加服务器,或返回已存在的服务器。
返回服务器的公开数据。
返回服务器玩家列表。
返回包含对指定服务器的可见提及的公开帖子。
返回各时间段玩家数量的最小值、平均值和最大值图表。
返回指定服务器的投票列表。
返回每日投票数量。
返回投票次数最多的用户。
返回每个时间段内项目所有服务器在线玩家总数的最小值、平均值和最大值。
返回项目的投票。未经身份验证只能访问公开项目。
返回项目的每日投票数量。未经身份验证只能访问公开项目。
返回为项目投票最多的用户。未经身份验证只能访问公开项目。
按 ID 返回投票信息。
将投票标记为已处理。仅服务器或项目所有者可用。
返回用户资料。
用户可以在「集成」中获取验证码,以确认 GAMEMONITORING 账号归属。验证码自生成起 5 分钟内有效。验证成功后,API 返回该验证码对应的账号 ID,并将验证码标记为已使用。
传递参数
- URL 参数
- ID 位于请求路径中:server_id 和 project_id 是 GAMEMONITORING 的数字 ID,vote_id 是投票标识。请用实际值替换花括号中的参数。
- 查询参数
- 筛选条件、时间范围和分页参数放在 URL 的 ? 后面。使用 URLSearchParams 或所用库的同等功能编码参数值,尤其是昵称和搜索文本。
- 请求体参数
- 添加服务器时发送 JSON,并设置 Content-Type: application/json。connect 是公开的 host:port,steam_app_id 是游戏的 Steam App ID。查询端口与连接端口不同时使用 query。
数据格式
HTTP 200 将结果放在 response 中,具体接口可能返回对象、数组或包含 items 的对象。请查看对应接口的结构;空列表本身不是错误。
部分字段可能为 null 或缺失。这与 0、false 和空字符串不同,请单独处理缺失的数据。
created_at、expires_at 和 last_update 使用以秒为单位的 Unix 时间戳。构造 JavaScript Date 时乘以 1000;设置筛选条件时将 Date.now() 除以 1000 并向下取整。
请将 64 位 Steam 标识保存为字符串,转换为 JavaScript Number 可能损失精度。GAMEMONITORING 服务器 ID 与游戏的 Steam App ID 是不同的标识。
错误与重试
请检查 HTTP 状态码和 error 对象:code 是状态码,message 是说明,data 在可用时包含附加信息。错误文本随地区而变化,也可能更新,请不要将文本作为程序判断条件。
- 400
- 参数或 JSON 无效。请检查类型、必填字段及允许范围。
- 403
- 访问被拒绝:地址被封禁,或项目未公开。
- 404
- 请求的资源不存在。
- 405
- 请检查 HTTP 方法与请求路径,该操作不受支持。
- 429
- 请暂停请求,并在能读取时遵循 Retry-After 请求头。立即重复相同请求无法解除限制。
- 500 / 503 / 504
- 对于暂时性的读取错误,限制重试次数并逐步增加等待时间。添加服务器超时后,请先检查结果,请求可能已执行完成。
先修正参数或权限问题再重试。同时处理网络错误和可能不包含 JSON 的代理响应。
数据反映最近一次服务器查询,且可能被缓存。请检查 last_update,设置合理的刷新间隔,并在集成中缓存结果。频繁调用 API 不会加快游戏服务器的数据更新。
投票与 Webhook
如需响应新投票,请配置项目 Webhook。验证 signature,跳过 is_test=true 的测试事件,并使用 event_id 作为 vote_id 通过 API 获取投票。检查 entity_type 和 entity_id,然后按 event_type + event_id 组合仅处理一次该事件。 测试事件应返回 2xx 响应,且不发放奖励。