# GAMEMONITORING > GAMEMONITORING REST API 返回服务器、玩家、帖子、在线历史和投票的 JSON 数据。本页介绍集成基础及第一个请求,参数说明和请求测试位于各接口页面。 - [GAMEMONITORING API](https://gamemonitoring.cn/developers/docs/api.md) - [GAMEMONITORING MCP](https://gamemonitoring.cn/developers/docs/mcp.md) - [添加服务器](https://gamemonitoring.cn/developers/docs/api/servers/__post.md) - [服务器](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/__get.md) - [服务器玩家](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/players/__get.md) - [提及此服务器的帖子](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/posts/__get.md) - [服务器在线玩家数图表](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [服务器投票](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/__get.md) - [服务器投票图表](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [服务器投票排行榜](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/top/__get.md) - [项目在线玩家数图表](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [项目投票](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/__get.md) - [项目投票图表](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [项目投票排行榜](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/top/__get.md) - [投票](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__get.md) - [确认投票已处理](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/claim/__post.md) - [用户资料](https://gamemonitoring.cn/developers/docs/api/users/:id/__get.md) - [验证账号归属](https://gamemonitoring.cn/developers/docs/api/users/verify-code/__post.md) - [Webhook](https://gamemonitoring.cn/developers/docs/webhook.md) - [投票奖励](https://gamemonitoring.cn/developers/docs/webhook/vote.md) - [系统 IP 地址](https://gamemonitoring.cn/developers/docs/ips.md) - [OpenAPI](https://gamemonitoring.cn/developers/docs/openapi.json) - [完整文档](https://gamemonitoring.cn/developers/docs/llms-full.txt) - [GAMEMONITORING MCP](https://api.gamemonitoring.net/mcp) --- # GAMEMONITORING API GAMEMONITORING REST API 返回服务器、玩家、帖子、在线历史和投票的 JSON 数据。本页介绍集成基础及第一个请求,参数说明和请求测试位于各接口页面。 ## 基础地址 https://api.gamemonitoring.cn ## 第一个请求 先获取公开的服务器数据。服务器 ID 位于其 GAMEMONITORING 页面地址的末尾。 ```bash curl --header 'Accept: application/json' 'https://api.gamemonitoring.cn/servers/1' ``` ## 选择接口 - [POST /servers — 添加服务器](https://gamemonitoring.cn/developers/docs/api/servers/__post.md) - [GET /servers/{server_id} — 服务器](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/__get.md) - [GET /servers/{server_id}/players — 服务器玩家](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/players/__get.md) - [GET /servers/{server_id}/posts — 提及此服务器的帖子](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/posts/__get.md) - [GET /servers/{server_id}/stats/players_online — 服务器在线玩家数图表](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/stats/players_online/__get.md) - [GET /servers/{server_id}/votes — 服务器投票](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/__get.md) - [GET /servers/{server_id}/votes/chart — 服务器投票图表](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/chart/__get.md) - [GET /servers/{server_id}/votes/top — 服务器投票排行榜](https://gamemonitoring.cn/developers/docs/api/servers/:server_id/votes/top/__get.md) - [GET /projects/{project_id}/stats/players_online — 项目在线玩家数图表](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/stats/players_online/__get.md) - [GET /projects/{project_id}/votes — 项目投票](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/__get.md) - [GET /projects/{project_id}/votes/chart — 项目投票图表](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/chart/__get.md) - [GET /projects/{project_id}/votes/top — 项目投票排行榜](https://gamemonitoring.cn/developers/docs/api/projects/:project_id/votes/top/__get.md) - [GET /votes/{vote_id} — 投票](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__get.md) - [POST /votes/{vote_id}/claim — 确认投票已处理](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/claim/__post.md) - [GET /users/{id} — 用户资料](https://gamemonitoring.cn/developers/docs/api/users/:id/__get.md) - [POST /users/verify-code — 验证账号归属](https://gamemonitoring.cn/developers/docs/api/users/verify-code/__post.md) ## API 版本 可以通过可选的查询参数 v 指定 API 版本。当前版本为 1.0.0。版本决定可用路径、请求字段和响应格式。 不传 v 时使用最低受支持版本。该版本停用后,下一个最低受支持版本成为默认版本。显式传入 v 可固定接口契约。无效、重复或不受支持的版本返回 HTTP 400;不受支持版本的可用值列表位于 error.data.supported_versions。 ## 传递参数 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 在可用时包含附加信息。错误文本随地区而变化,也可能更新,请不要将文本作为程序判断条件。 先修正参数或权限问题再重试。同时处理网络错误和可能不包含 JSON 的代理响应。 数据反映最近一次服务器查询,且可能被缓存。请检查 last_update,设置合理的刷新间隔,并在集成中缓存结果。频繁调用 API 不会加快游戏服务器的数据更新。 ## 投票与 Webhook 如需响应新投票,请配置项目 Webhook。验证 signature,跳过 is_test=true 的测试事件,并使用 event_id 作为 vote_id 通过 API 获取投票。检查 entity_type 和 entity_id,然后按 event_type + event_id 组合仅处理一次该事件。 测试事件应返回 2xx 响应,且不发放奖励。 ## 集成帮助 报告错误时,请准备 HTTP 方法、路径、参数、请求时间、HTTP 状态码及返回的 error。这些信息有助于重现问题。 ## OpenAPI ```json { "openapi": "3.1.1", "info": { "title": "GAMEMONITORING", "version": "1.0.0" }, "paths": { "/servers": { "post": { "operationId": "createServer", "summary": "添加服务器", "description": "通过连接地址添加服务器,或返回已存在的服务器。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "connect": { "type": "string", "minLength": 1, "example": "198.51.100.24:27015" }, "steam_app_id": { "type": "integer", "minimum": 0, "example": 730 }, "query": { "type": "integer", "minimum": 10, "maximum": 65535, "example": 27016 } }, "required": [ "connect", "steam_app_id" ] }, "example": { "connect": "198.51.100.24:27015", "steam_app_id": 730 } } } }, "responses": { "200": { "description": "Created or existing server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerCreateResult" }, "example": { "response": { "connect": "198.51.100.24:27015", "game": 730, "id": 100001, "name": "Example Arena", "request": "198.51.100.24:27016", "status": true } } } } }, "400": { "description": "Missing game or address, invalid address or offline server" }, "403": { "description": "Blocked address" }, "409": { "description": "Query address is already in use" }, "503": { "description": "Server creation service is unavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}": { "get": { "operationId": "getServer", "summary": "服务器", "description": "返回服务器的公开数据。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerEnvelope" }, "example": { "response": { "steam_id": "90123456789012345", "domain": null, "id": 1, "ip": "198.51.100.24", "port": 27015, "query": 27015, "project_id": 42, "color": 0, "city": "Prague", "description": "[]", "game": 730, "boosts": 3, "last_offline": 1782751200, "last_online": 1783201200, "icon": null, "name": "Example CS2 Server", "connect": "198.51.100.24:27015", "request": "198.51.100.24:27015", "map": "de_mirage", "gamemode": "Counter-Strike 2", "version": "1.41.6.5", "numplayers": 12, "maxplayers": 64, "bots": 0, "secured": true, "private": false, "country": "CZ", "status": true, "votes": 128, "points": 2450, "add_date": 1701541119, "last_update": 1783201200, "ban_reason": null, "banned": false, "wipe": null, "official": null, "wipe_period": null, "next_wipe": null, "pve": null, "pvp": null, "list_hidden": false, "hide_address": false, "hide_query": false, "position_game": 12, "language": "en", "parked": false, "app": { "id": 2, "steam_id": 730, "name": "Counter-Strike 2", "url": "counter-strike-2" }, "mods": [ { "id": 5, "name": "Admin System" }, { "id": 14, "name": "Advertisement" }, { "id": 9, "name": "Admins" }, { "id": 3, "name": "Admin Commands" } ], "disabled_modules": [] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/players": { "get": { "operationId": "getServerPlayers", "summary": "服务器玩家", "description": "返回服务器玩家列表。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "limit", "in": "query", "description": "条目数量为 1 至 100,默认为 50", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Server players", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayersResult" }, "example": { "response": { "items": [ { "avatar": "no.jpg", "created": 1783200000, "last_online": 1783203600, "last_session_time": 0, "name": "NovaPlayer", "user": null, "username": null } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" } } } }, "/servers/{server_id}/posts": { "get": { "operationId": "getServerPosts", "summary": "提及此服务器的帖子", "description": "返回包含对指定服务器的可见提及的公开帖子。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "before_created_at", "in": "query", "description": "获取下一页时,将上一页最后一条帖子的 `created_at`(Unix 秒)和 `id` 分别作为 `before_created_at` 和 `before_id` 传入,并保留其他筛选条件。游标在未指定 `sort` 和 `period` 时生效。指定其中任一参数时,请使用 `offset`。", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "before_id", "in": "query", "description": "游标帖子 ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "conversation_post_id", "in": "query", "description": "讨论帖子 ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "period", "in": "query", "description": "使用 top 选择最佳帖子周期。", "schema": { "type": "string", "const": "top" } }, { "name": "reply_to_post_id", "in": "query", "description": "父帖子 ID", "schema": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, { "name": "root_only", "in": "query", "description": "使用 1 仅返回根帖子", "schema": { "type": "number", "const": 1 } }, { "name": "sort", "in": "query", "description": "帖子排序。最佳帖子使用 helpful-desc。", "schema": { "type": "string" } }, { "name": "visibility", "in": "query", "description": "此操作仅返回公开帖子。", "schema": { "type": "string", "const": "public" } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "limit", "in": "query", "description": "条目数量为 1 至 100,默认为 20", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "example": 5 } }, { "$ref": "#/components/parameters/offset" }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 120, "example": "admin" } } ], "responses": { "200": { "description": "Public posts mentioning the server", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPostsResult" }, "example": { "response": [ { "id": 1001, "comment": "Great server! Thanks to the admin team.", "conversation_post_id": null, "language": "en", "moderation_needed": false, "replays": 0, "reply_to_post_id": null, "views": 25, "updated_at": null, "created_at": 1783200000, "translated_content": null, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user" }, "images": [], "mentions": [ { "type": "server", "meta": { "game": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "icon": null, "id": 1, "name": "Example CS2 Server" } } ], "reactions": [], "replays_items": [], "replays_items_count": 0 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "Server not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/stats/players_online": { "get": { "operationId": "getServerPlayerStats", "summary": "服务器在线玩家数图表", "description": "返回各时间段玩家数量的最小值、平均值和最大值图表。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "统计时间段:day、week 或 month,默认为 month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "maps": [ "de_mirage" ], "max_players": 16, "min_players": 8, "x": 1783200000, "y": 16 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes": { "get": { "operationId": "getServerVotes", "summary": "服务器投票", "description": "返回指定服务器的投票列表。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "用户 ID", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "server", "expires_at": 1783243200, "id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "nickname": "NovaPlayer", "server": { "app": { "id": 2, "name": "Counter-Strike 2", "steam_id": 730, "url": "counter-strike-2" }, "game": 730, "icon": null, "id": 42, "name": "Example CS2 Server" }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/servers/{server_id}/votes/chart": { "get": { "operationId": "getServerVoteChart", "summary": "服务器投票图表", "description": "返回每日投票数量。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/servers/{server_id}/votes/top": { "get": { "operationId": "getServerTopVoters", "summary": "服务器投票排行榜", "description": "返回投票次数最多的用户。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "server_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1783243200, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/projects/{project_id}/stats/players_online": { "get": { "operationId": "getProjectPlayerStats", "summary": "项目在线玩家数图表", "description": "返回每个时间段内项目所有服务器在线玩家总数的最小值、平均值和最大值。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "type", "in": "query", "description": "统计时间段:day、week 或 month,默认为 month", "schema": { "type": "string", "default": "month", "example": "week", "enum": [ "day", "week", "month" ] } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 1 } } ], "responses": { "200": { "description": "Combined project player statistics grouped by time interval", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectPlayerStatsResult" }, "example": { "response": { "items": [ { "avg_players": 12, "date": 1783200000, "max_players": 16, "min_players": 8, "x": 1783200000 } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes": { "get": { "operationId": "getProjectVotes", "summary": "项目投票", "description": "返回项目的投票。未经身份验证只能访问公开项目。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "user_id", "in": "query", "description": "用户 ID", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" }, { "$ref": "#/components/parameters/sort" }, { "$ref": "#/components/parameters/order" }, { "$ref": "#/components/parameters/claimed" }, { "$ref": "#/components/parameters/nickname" }, { "$ref": "#/components/parameters/created" }, { "$ref": "#/components/parameters/created__gt" }, { "$ref": "#/components/parameters/created__gte" }, { "$ref": "#/components/parameters/created__lt" }, { "$ref": "#/components/parameters/created__lte" }, { "$ref": "#/components/parameters/expire" }, { "$ref": "#/components/parameters/expire__gt" }, { "$ref": "#/components/parameters/expire__gte" }, { "$ref": "#/components/parameters/expire__lt" }, { "$ref": "#/components/parameters/expire__lte" } ], "security": [], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/VoteDetails" } } }, "required": [ "response" ] }, "example": { "response": [ { "claimed_at": null, "created_at": 1783200000, "entity_id": 42, "entity_type": "project", "expires_at": 1785792000, "id": "7206f073-2f18-4660-91b8-bd947fbc4be2", "nickname": "NovaPlayer", "project": { "id": 42 }, "user": { "avatar": "no.jpg", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [] } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } } } }, "/projects/{project_id}/votes/chart": { "get": { "operationId": "getProjectVoteChart", "summary": "项目投票图表", "description": "返回项目的每日投票数量。未经身份验证只能访问公开项目。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": [ "integer", "string" ] }, "y": { "type": [ "integer", "string" ] } } } } }, "required": [ "response" ] }, "example": { "response": [ { "x": 1800000000, "y": 10 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/projects/{project_id}/votes/top": { "get": { "operationId": "getProjectTopVoters", "summary": "项目投票排行榜", "description": "返回为项目投票最多的用户。未经身份验证只能访问公开项目。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1, "example": 42 } }, { "$ref": "#/components/parameters/period" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/offset" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "active": { "type": [ "integer", "string" ] }, "total": { "type": [ "integer", "string" ] } } }, "last": { "type": "object", "properties": { "created_at": { "type": "integer" }, "expire_at": { "type": "integer" }, "nickname": { "type": "string" } } }, "user": { "type": "object", "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": "string" } } } } } } }, "required": [ "response" ] }, "example": { "response": [ { "counts": { "active": 2, "total": 10 }, "last": { "created_at": 1783200000, "expire_at": 1785792000, "nickname": "NovaPlayer" }, "user": { "avatar": "no.jpg", "username": "demo_user" } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "description": "Private project is not accessible to the requester" }, "404": { "description": "Project not found" } } } }, "/votes/{vote_id}": { "get": { "operationId": "getVote", "summary": "投票", "description": "按 ID 返回投票信息。", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Vote details response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteDetailsEnvelope" }, "example": { "response": { "created_at": 1783200000, "expires_at": 1783243200, "id": "6f59a4a8-2f0f-4d96-a50a-9d7a21f4b812", "entity_id": 100001, "entity_type": "server", "nickname": "NovaPlayer", "server": { "app": { "id": 2400, "name": "Example Shooter", "steam_id": 111111, "url": "example-shooter" }, "game": 111111, "icon": null, "id": 100001, "name": "Example Arena" }, "user": { "avatar": "8f14e45f-e9a1-4f4d-a9f3-6d7b0d4a2c18.webp", "id": 204801, "username": "demo_user", "uuid": "d4f9c57e-7c8b-49c7-8d7e-b2f1a39f4a25", "connections": [ { "id": "100000000000000001", "name": "demo_user", "type": "discord", "url": "https://discord.com/users/100000000000000001" }, { "id": "76561198000000001", "name": "NovaPlayer", "type": "steam", "url": "https://steamcommunity.com/profiles/76561198000000001" } ] }, "claimed_at": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" }, "504": { "$ref": "#/components/responses/QueryTimeout" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "security": [] } }, "/votes/{vote_id}/claim": { "post": { "operationId": "claimVote", "summary": "确认投票已处理", "description": "将投票标记为已处理。仅服务器或项目所有者可用。", "security": [ { "AccountAPIKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "vote_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoteClaimResult" }, "example": { "response": { "success": true } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "description": "Missing, invalid, expired or revoked credential." }, "403": { "description": "Missing API key scope, restricted account or entity ownership." }, "404": { "description": "Unknown vote or invalid entity association." }, "429": { "description": "Account claim quota exceeded: 12 000 per minute. Honor Retry-After." } } } }, "/users/{id}": { "get": { "operationId": "getPublicUser", "summary": "用户资料", "description": "返回用户资料。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "id", "in": "path", "required": true, "description": "账号 ID。", "schema": { "type": "string", "format": "uuid", "example": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } ], "responses": { "200": { "description": "User profile.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfileResult" }, "example": { "response": { "avatar": "447f9470-325b-4e0a-ada0-f4f1659ef805.png", "id": 1, "username": "GAMEMONITORING", "banner": "469ebf64-206c-4374-a742-7730ea227f95.webp", "connections": [ { "account_id": "76561197960287930", "account_level": 1, "id": 220354, "name": "Rabscuttle", "platform": { "icon": null, "id": 3, "name": "Steam", "url": "steam" } } ], "created": 1435235037, "last_online": 1793734264, "uuid": "ef57cc6f-f068-11ef-a5bf-d00d12c6f2dd" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "description": "User not found." } } } }, "/users/verify-code": { "post": { "operationId": "verifyUserCode", "summary": "验证账号归属", "description": "用户可以在「[集成](/settings/integration)」中获取验证码,以确认 GAMEMONITORING 账号归属。验证码自生成起 5 分钟内有效。验证成功后,API 返回该验证码对应的账号 ID,并将验证码标记为已使用。", "security": [], "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "code" ], "properties": { "code": { "type": "string", "description": "一次性账号验证码。不区分大小写。", "pattern": "^\\s*[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}(?:-[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{4}){2}\\s*$", "example": "7KMD-P9RX-3WHT" } } } } } }, "responses": { "200": { "description": "The stable GAMEMONITORING account ID.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "example": "no-store" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "response" ], "properties": { "response": { "type": "object", "additionalProperties": false, "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid" } } } } }, "example": { "response": { "id": "550e8400-e29b-41d4-a716-446655440000" } } } } }, "400": { "description": "Invalid request or code format." }, "404": { "description": "Unknown, expired or already redeemed code." }, "429": { "description": "Too many requests." }, "503": { "description": "A required service is temporarily unavailable." } } } } }, "components": { "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP 状态码。" }, "message": { "type": "string", "description": "使用 API 语言的错误消息。文字可能变化;请按状态码处理错误。" }, "data": { "description": "可用时提供额外错误详情。" } } } } }, "Server": { "type": "object", "properties": { "add_date": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "app": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "steam_id": { "description": "Steam App ID of the game. Use this as game_steam_id when searching servers.", "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ] }, "url": { "type": "string" } }, "additionalProperties": {} }, { "type": "null" } ] }, "color": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connect": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hide_address": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "hide_query": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "icon": { "type": [ "string", "null" ] }, "id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "ip": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] }, "last_update": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "map": { "type": [ "string", "null" ] }, "maxplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": [ "string", "null" ] }, "numplayers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "official": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "points": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "port": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "private": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "project_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pve": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "pvp": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "request": { "type": [ "string", "null" ] }, "secured": { "anyOf": [ { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "steam_id": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string" } ] }, { "type": "null" } ], "description": "请保持字符串标识符为字符串,避免精度丢失。" }, "version": { "type": [ "string", "null" ] }, "votes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "ban_reason": { "type": [ "string", "null" ] }, "banned": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "boosts": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bots": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "city": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "服务器说明,以 JSON 字符串编码的块列表存储。" }, "disabled_modules": { "type": "array", "items": { "type": "string" } }, "gamemode": { "type": [ "string", "null" ] }, "hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "last_offline": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "last_online": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "list_hidden": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "map_url": { "type": [ "string", "null" ] }, "mods": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} } }, "next_wipe": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Unix 时间戳,单位为秒(UTC)。" }, "parked": { "type": "boolean" }, "position_game": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "wipe_period": { "type": [ "string", "null" ] } }, "required": [ "id", "parked" ], "additionalProperties": {} }, "ServerEnvelope": { "type": "object", "required": [ "response" ], "properties": { "response": { "$ref": "#/components/schemas/Server", "description": "成功响应将结果放在 response 中。列表可能是数组或带 items 的对象;请查看此操作的结构。" } } }, "UserProfileResult": { "type": "object", "required": [ "response" ], "properties": { "response": { "type": "object", "required": [ "id", "uuid", "username", "avatar", "banner", "created", "last_online" ], "properties": { "id": { "type": "integer", "minimum": 1, "description": "Numeric profile ID." }, "uuid": { "type": "string", "format": "uuid", "description": "Account ID." }, "username": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "banner": { "type": [ "string", "null" ] }, "created": { "type": [ "integer", "null" ] }, "last_online": { "type": [ "integer", "null" ] }, "connections": { "type": "array", "items": { "type": "object", "required": [ "id", "account_id", "account_level", "name" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "account_id": { "type": "string" }, "account_level": { "type": [ "number", "null" ] }, "name": { "type": [ "string", "null" ] }, "platform": { "type": [ "object", "null" ], "required": [ "id", "name", "icon", "url" ], "properties": { "id": { "type": "integer", "minimum": 1 }, "name": { "type": "string" }, "icon": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } } } } } } } } }, "ServerCreateResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "connect": { "type": [ "string", "null" ] }, "game": { "type": [ "integer", "null" ] }, "id": { "type": "integer", "minimum": 1 }, "name": { "type": [ "string", "null" ] }, "request": { "type": [ "string", "null" ] }, "status": { "type": [ "boolean", "null" ] } }, "required": [ "connect", "game", "id", "name", "request", "status" ] } }, "required": [ "response" ] }, "ServerPlayersResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "description": "如果会话历史查询未返回玩家,`items` 会包含最近一次服务器查询的完整玩家列表(若可用)。", "type": "array", "items": { "type": "object", "properties": { "avatar": { "type": "string" }, "created": { "type": [ "number", "string", "null" ] }, "last_online": { "type": [ "number", "string", "null" ] }, "last_session_time": { "type": "number" }, "name": { "type": [ "number", "string", "null" ] }, "user": { "type": [ "object", "null" ], "properties": { "avatar": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] } } }, "username": { "type": [ "string", "null" ] } }, "required": [ "avatar", "last_session_time", "username" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ServerPostsResult": { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "response" ] }, "ServerPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "maps": { "type": "array", "items": { "type": "string" } }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "avg_players", "date", "maps", "max_players", "min_players", "x", "y" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "ProjectPlayerStatsResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "avg_players": { "type": "number" }, "date": { "type": "number" }, "max_players": { "type": "number" }, "min_players": { "type": "number" }, "x": { "type": "number" } }, "required": [ "avg_players", "date", "max_players", "min_players", "x" ] } } }, "required": [ "items" ] } }, "required": [ "response" ] }, "VoteDetailsEnvelope": { "type": "object", "properties": { "response": { "$ref": "#/components/schemas/VoteDetails" } } }, "VoteDetails": { "type": "object", "properties": { "id": { "type": "string", "example": "9824cabb-2203-437e-9b6c-aba43dde3e4b" }, "entity_id": { "type": "number", "description": "ID of the entity that received the vote.", "example": 1 }, "entity_type": { "type": "string", "description": "Type of the entity that received the vote.", "enum": [ "server", "project" ], "example": "server" }, "nickname": { "type": [ "string", "null" ], "example": "PlayerName" }, "created_at": { "type": "number", "example": 1710000000 }, "expires_at": { "type": "number", "example": 1710086400 }, "server": { "type": [ "object", "null" ], "description": "Present for `server` votes.", "properties": { "id": { "type": [ "number", "string", "null" ], "example": 1 }, "name": { "type": [ "string", "null" ], "example": "Public Server" }, "icon": { "type": [ "string", "null" ] }, "game": { "type": [ "number", "null" ], "example": 730 } } }, "project": { "type": [ "object", "null" ], "description": "Present for `project` votes.", "properties": { "id": { "type": "number", "example": 1 } } }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "number", "string", "null" ] }, "uuid": { "type": [ "string", "null" ] }, "username": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] } } }, "webhook": { "type": [ "object", "null" ], "description": "Present only when the requester can view webhook delivery details.", "properties": { "attempted_at": { "type": [ "number", "null" ] }, "event_id": { "type": [ "string", "null" ] }, "event_type": { "type": [ "string", "null" ], "enum": [ "server.vote", "project.vote", null ], "example": "project.vote" }, "is_test": { "type": [ "boolean", "null" ] }, "request_body": { "type": [ "object", "null" ] }, "response_body": {}, "response_code": { "type": [ "number", "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "delivered", "failed", "no_result", "pending", null ] }, "url": { "type": [ "string", "null" ] } } }, "claimed_at": { "type": [ "integer", "null" ], "description": "Processing acknowledgement time in Unix seconds; null means unclaimed.", "example": null } } }, "VoteClaimResult": { "type": "object", "properties": { "response": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } }, "required": [ "success" ] } }, "required": [ "response" ] } }, "parameters": { "ApiVersion": { "name": "v", "in": "query", "required": false, "description": "API 版本。不传 v 时使用最低受支持版本。传入 v=1.0.0 可固定文档中的接口契约。无效、重复或不受支持的值返回 HTTP 400。", "schema": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$", "const": "1.0.0" } }, "created": { "name": "created", "in": "query", "description": "按投票的确切创建时间筛选,单位为 Unix 秒。未指定日期筛选条件时,查询涵盖所有保留的投票。", "schema": { "type": "integer", "example": 1800000000 } }, "created__gt": { "name": "created__gt", "in": "query", "description": "创建时间,Unix 秒 >", "schema": { "type": "integer", "example": 1800000000 } }, "created__gte": { "name": "created__gte", "in": "query", "description": "创建时间,Unix 秒 ≥", "schema": { "type": "integer", "example": 1800000000 } }, "created__lt": { "name": "created__lt", "in": "query", "description": "创建时间,Unix 秒 <", "schema": { "type": "integer", "example": 1800000000 } }, "created__lte": { "name": "created__lte", "in": "query", "description": "创建时间,Unix 秒 ≤", "schema": { "type": "integer", "example": 1800000000 } }, "expire": { "name": "expire", "in": "query", "description": "过期时间,Unix 秒", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gt": { "name": "expire__gt", "in": "query", "description": "过期时间,Unix 秒 >", "schema": { "type": "integer", "example": 1800000000 } }, "expire__gte": { "name": "expire__gte", "in": "query", "description": "过期时间,Unix 秒 ≥", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lt": { "name": "expire__lt", "in": "query", "description": "过期时间,Unix 秒 <", "schema": { "type": "integer", "example": 1800000000 } }, "expire__lte": { "name": "expire__lte", "in": "query", "description": "过期时间,Unix 秒 ≤", "schema": { "type": "integer", "example": 1800000000 } }, "claimed": { "name": "claimed", "in": "query", "description": "处理状态:0 未处理,1 已处理;默认包含全部", "schema": { "type": "integer", "enum": [ 0, 1 ], "example": 0 } }, "limit": { "name": "limit", "in": "query", "description": "条目数量为 1 至 1000,默认为 100", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100, "example": 100 } }, "offset": { "name": "offset", "in": "query", "description": "跳过的条目数量,最小为 0,默认为 0", "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 0 } }, "order": { "name": "order", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "example": "asc" } }, "sort": { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "created", "expire" ], "default": "created", "example": "created" } }, "nickname": { "name": "nickname", "in": "query", "description": "按投票者昵称片段搜索,长度为 3 至 255 个字符", "schema": { "type": "string", "minLength": 3, "maxLength": 255, "example": "Player" } }, "server_id": { "name": "server_id", "in": "query", "schema": { "type": "integer", "example": 42 } }, "entity_type": { "name": "entity_type", "in": "query", "schema": { "type": "string", "enum": [ "server", "project" ], "example": "server" } }, "webhook_status": { "name": "webhook_status", "in": "query", "schema": { "type": "string", "enum": [ "delivered", "failed", "no_result", "pending" ], "example": "failed" } }, "period": { "name": "period", "in": "query", "description": "按投票创建时间筛选的时间段,默认包含所有保留的历史记录", "schema": { "type": "string", "enum": [ "24h", "7d", "30d", "90d" ], "example": "30d" } } }, "securitySchemes": { "AccountAPIKey": { "type": "http", "scheme": "bearer", "description": "Account API key: 43 base64url characters without a prefix. Claim requires votes:claim scope plus current ownership. Send only in Authorization: Bearer ." } }, "responses": { "BadRequest": { "description": "参数或 JSON 无效。请检查类型、必填字段及允许范围。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 400, "message": "Invalid request parameters." } } } } }, "Forbidden": { "description": "访问被拒绝:地址被封禁,或项目未公开。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 403, "message": "Access denied." } } } } }, "ServiceUnavailable": { "description": "服务暂时不可用,请稍后重试。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 503, "message": "Service temporarily unavailable." } } } } }, "QueryTimeout": { "description": "查询超时。请稍后重试或缩小请求范围。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 504, "message": "Query timed out." } } } } }, "NotFound": { "description": "请求的资源不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 404, "message": "Resource not found." } } } } }, "UnexpectedError": { "description": "意外的服务器错误。error 对象包含实际状态码。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }, "example": { "error": { "code": 500, "message": "Internal server error." } } } } } } }, "servers": [ { "url": "https://api.gamemonitoring.cn" } ] } ``` https://gamemonitoring.cn/developers/docs/api.md --- # GAMEMONITORING MCP MCP(Model Context Protocol)让智能体能够查询 GAMEMONITORING 的游戏、服务器、在线状态和玩家人数。所有工具均为只读,访问公开数据无需账号或 API 密钥。 ## 连接智能体 手动配置时请选择 Streamable HTTP 并粘贴此地址。Cursor 和 VS Code 支持直接安装,命令行客户端可复制安装命令。 ```text https://api.gamemonitoring.net/mcp ``` ### Codex ```bash codex mcp add gamemonitoring --url 'https://api.gamemonitoring.net/mcp' ``` ### Claude Code ```bash claude mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### Gemini CLI ```bash gemini mcp add --scope user --transport http gamemonitoring 'https://api.gamemonitoring.net/mcp' ``` ### MCP JSON ```json { "mcpServers": { "gamemonitoring": { "url": "https://api.gamemonitoring.net/mcp" } } } ``` ### 发给智能体的示例提示 ```text 通过 GAMEMONITORING 找出在线玩家最多的三台 Rust 服务器,并列出各服务器的地址和在线人数。 ``` ## MCP 工具 先调用 search_games。将返回的 steam_id 作为 game_steam_id,用于搜索、筛选和统计服务器。查看服务器详情时,使用 search_servers 返回的 GAMEMONITORING 服务器 ID。 ### search_games 按名称、网址标识或 Steam App ID 查找游戏,返回 steam_id、名称、网址标识、服务器数和玩家人数。 ```json { "name": "Rust", "limit": 1 } ``` ### get_server_filters 列出地图、版本、国家或地区、语言、游戏模式等筛选项。传入 game_steam_id 可获取指定游戏的筛选项,传入空对象可获取通用筛选项。 ```json { "game_steam_id": 252490 } ``` ### search_servers 按游戏和其他条件筛选服务器,支持排序、limit(1 到 100)和 offset。指定游戏可缩小搜索范围。 ```json { "game_steam_id": 252490, "status": "online", "sort": "numplayers", "limit": 3 } ``` ### get_server 根据数字 server_id 返回服务器的公开详情和当前状态。 ```json { "server_id": 1 } ``` ### get_server_list_metadata 使用与搜索服务器相同的筛选条件,统计匹配的服务器总数、在线服务器数和在线玩家人数。 ```json { "game_steam_id": 252490, "status": "online" } ``` ## 数据格式 tools/call 调用成功时,result.structuredContent 包含结果数据。result.content 包含结果的文本表示和对应 REST 请求的链接。 协议错误位于顶层 error 字段。工具出错时,即使 HTTP 状态为 200,result.isError 也为 true。服务器提供的错误详情位于 result.structuredContent.error。搜索超时后,可按游戏或其他筛选条件缩小范围。 https://gamemonitoring.cn/developers/docs/mcp.md --- # Webhook {#webhook} Webhook 会在平台发生操作后,把 GAMEMONITORING 事件发送到你的系统。它是普通的 `POST` 请求,请求体为 JSON,网站、面板或游戏服务可以据此自动响应。 如果你要配置投票奖励,请先按照本指南连接 Webhook,然后使用单独流程:[投票奖励](https://gamemonitoring.cn/developers/docs/webhook/vote#flow)。 ## 连接 {#connect} 此设置会把 GAMEMONITORING 项目连接到你的处理器,并提供用于验证传入请求的签名 token。 1. 打开 [我的项目](https://gamemonitoring.cn/projects/my),创建项目或选择已有项目,然后进入 Webhook 设置。 2. 创建公开 HTTPS endpoint,接受 `Content-Type: application/json` 的 `POST` 请求,并且不要重定向请求。 3. 在 Webhook 设置中填写完整处理器 URL,例如 `https://panel.example.com/gamemonitoring-webhook`,并保存。 4. 从同一块设置中复制签名 token,并把它写入处理器脚本。 5. 在处理器中验证 `signature`,处理需要的 `event_type`,并且只在事件处理完成后返回成功的 `2xx` 响应。 本地测试时,可以在自己的电脑上运行处理器,并通过公开 HTTPS URL 暴露它。可以使用 [ngrok](https://ngrok.com) 或其他隧道服务,然后在 Webhook 设置中填写生成的公开 URL。 设置完成后,从界面发送测试 Webhook 并检查投递状态。对于示例 URL,服务器必须在 `/gamemonitoring-webhook` 路径接受 `POST`。 如果测试失败,请先查看处理器响应:`401` 表示签名错误,`403` 或 HTML 验证页面通常表示 WAF 或 bot protection,超时表示该 URL 无法从互联网访问或响应太慢。 ## 处理器要求 {#handler-requirements} - URL 必须可以从互联网访问。本地地址、私有网络以及带登录名或密码的 URL 不适用。 - 生产环境建议使用 HTTPS。HTTP 也支持,但传输过程中的数据保护较弱。 - 处理器必须接受 `POST` 方法和 JSON 请求体,且不发生重定向。 - 只有在系统处理完事件后才返回 `2xx`。通常 `204 No Content` 就足够。 - 如果事件无法安全处理,请返回错误码。`3xx`、`4xx`、`5xx`、超时和连接错误都会被视为投递失败。 - 如果使用 firewall、bot protection 或 allowlist,请把 [GAMEMONITORING IP 地址](https://gamemonitoring.cn/developers/docs/ips) 加入例外。 - 不要在响应体中返回 token、stack trace、SQL 错误或其他内部细节。处理器响应会显示在界面中,因此错误文本必须安全且易懂。 ## 事件数据 {#event-data} 每个 Webhook 都会带有 JSON 请求体和基础字段: - `event_type` — 需要处理的事件。 - `event_id` — 唯一事件 ID。请与 `event_type` 一起用于幂等处理和防重复投递。 - `is_test` — 表示来自界面的测试投递。 - `signature` — 事件请求体的签名。 **Webhook 事件示例** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "example.event", "is_test": false, "signature": "0ac4c97a5d934599dbd78985c4bcbb6926e77b4809d2be56333b1b25f638f064" } ``` 示例解读:`event_type` 表示需要处理哪个事件;`event_id` 用于在修改状态前保证幂等;`is_test: true` 表示技术投递检查;`signature` 不是业务数据,只用于验证请求真实性。 处理逻辑取决于 `event_type`。对于 `server.vote` 和 `project.vote`,请使用单独流程:[投票奖励](https://gamemonitoring.cn/developers/docs/webhook/vote#flow)。 如果 `is_test` 为 `true`,请验证签名并返回 `2xx`,但不要修改余额、发放物品或启动生产操作。 ## 处理器响应示例 {#response-example} 每个传入事件都应以一个明确结果结束: - `204 No Content` — 签名正确,事件已处理或已安全跳过。测试投递和已经处理过的事件也返回相同响应。 - `400 Bad Request` — 缺少必填字段。这表示处理器错误或请求体不符合预期,不应执行业务逻辑。 - `401 Unauthorized` — 签名无效。不要发起 API 请求,不要修改数据库,也不要发放奖励。 - `500 Internal Server Error` — 数据库、队列或内部系统暂时不可用。投递会保持失败状态,修复原因后可以重试。 例如,处理器收到事件、验证签名、保存 `event_type` + `event_id` 并处理事件后,可以返回 `204`。如果数据库不可用,事件无法保存,最好返回 `500`,避免投递过早被标记为成功。 ## 签名验证 {#signature} 签名位于 `signature` 字段。请在任何业务逻辑、API 请求或数据库修改之前验证它。 验证时,取事件请求体中除 `signature` 以外的所有字段,按 key 字母顺序排序,并组成用 `&` 连接的 `key=value` 字符串。布尔值写作 `true` 或 `false`。 **签名字符串** ```text event_id=9824cabb-2203-437e-9b6c-aba43dde3e4b&event_type=example.event&is_test=false ``` 对于上面的示例,签名字符串只由 `event_id`、`event_type` 和 `is_test` 组成。然后使用 Webhook 设置中的签名 token 计算 `HMAC-SHA256`,并与请求中的 `signature` 比较。 示例中的预计算签名使用演示 token `paste-webhook-token-here`。在你的处理器中,请使用 Webhook 设置中的 token。 在处理器中: - 用排序后的 key 构建签名字符串; - 使用签名 token 计算 `HMAC-SHA256`; - 用恒定时间比较函数将结果与 `signature` 比较:PHP 使用 `hash_equals`,Node.js 使用 `timingSafeEqual`,Python 使用 `compare_digest`; - 如果签名无效,返回 `401`。 ## 第 1 步:基础处理器 {#minimal-handler} 先实现一个能接受任意 Webhook 的处理器:读取 JSON,验证 `signature`,处理测试投递,检查基础字段,并返回 `204`。在这一步,处理器只确认投递可以被正确接收。请在这个基础路径可用后再添加具体事件的逻辑。 ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Add event-specific logic here. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); // 204 tells GAMEMONITORING that the delivery was accepted successfully. http_response_code(204); ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Add event-specific logic here. console.log('Accepted webhook event ' + eventType + ' #' + eventId) // 204 tells GAMEMONITORING that the delivery was accepted successfully. return res.sendStatus(204) }) app.listen(3000) ``` ### Python ```python import hashlib import hmac from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Add event-specific logic here. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) # 204 tells GAMEMONITORING that the delivery was accepted successfully. return '', 204 ``` ## 第 2 步:添加去重 {#deduplication} Webhook 使用 at-least-once 投递模型:同一个事件可能到达多次。在处理器修改系统状态之前,请按 `event_type` + `event_id` 让该操作具备幂等性。 首先创建一张表,用唯一键保存 `event_type` 和 `event_id` 这一对值。如果记录已经存在,说明事件已经处理过。 **已处理 Webhook 事件表** ```sql CREATE TABLE gamemonitoring_webhooks ( event_type varchar(64) NOT NULL, event_id varchar(100) NOT NULL, created_at timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (event_type, event_id) ); ``` 然后扩展基础处理器:在签名和基础字段验证通过后,保存 `event_type` + `event_id`,并在同一个事务中执行状态变更。 ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // At this point the webhook is trusted. Deduplicate it before event-specific logic. $pdo = null; try { // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // At this point the webhook is trusted. Deduplicate it before event-specific logic. let connection try { connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # At this point the webhook is trusted. Deduplicate it before event-specific logic. connection = None try: connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` 不要把昵称、用户 ID 或服务器 ID 作为去重 key:同一个用户可能触发不同事件,也可能稍后重复一次允许的操作。key 必须是 `event_type` + `event_id`。 示例:处理器已经修改了你的系统状态,但在 GAMEMONITORING 收到 `204` 之前连接中断。稍后投递被重试,同一个事件再次到达。处理器必须找到已经保存的 `event_type` + `event_id`,跳过重复状态变更,并返回 `204`。 如果处理器暂时无法处理事件,请返回错误响应。原因修复后,如果该事件支持重试,可以从界面重新发送投递。 ## 测试和重新发送 {#tests-resend} 测试投递(`is_test: true`)会检查处理器 URL、签名和 HTTP 响应。处理器必须走同一条处理路径:读取 JSON,验证 `signature`,识别 `is_test`,并返回成功的 `2xx` 响应。 测试事件不得修改余额、库存、角色、订阅或其他生产数据。测试只需要技术日志和 `204` 响应。 如果投递失败,界面会显示状态、HTTP 状态码和处理器响应。修复原因后,如果该事件支持重试,可以重新发送失败的投递。 https://gamemonitoring.cn/developers/docs/webhook.md --- # 投票奖励 {#vote-rewards} 投票奖励使用 `server.vote` 和 `project.vote` Webhook 事件:处理器接收事件,通过 API 获取投票数据,并且只发放一次奖励。 请先配置 [项目 Webhook](https://gamemonitoring.cn/developers/docs/webhook#connect) 和 [signature](https://gamemonitoring.cn/developers/docs/webhook#signature) 验证。投票数据通过 [GET /votes/:vote_id](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__GET) 请求。 ## 流程如何工作 {#flow} 1. 接收 Webhook 事件并[验证 signature](https://gamemonitoring.cn/developers/docs/webhook#signature)。如果 [is_test](https://gamemonitoring.cn/developers/docs/webhook#tests-resend) 为 `true`,返回 `204`,不要请求投票数据,也不要发放奖励。 2. 确认 `event_type` 等于 `server.vote` 或 `project.vote`。 3. 将 `event_id` 作为投票 ID 使用。 4. 通过 [GET /votes/:vote_id](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__GET) 获取投票数据,并在你的系统中找到玩家。 5. 在同一个事务中按 `event_type` + `event_id` 应用[防重复处理](https://gamemonitoring.cn/developers/docs/webhook#deduplication),并且只为新事件发放奖励。 6. 如果无法安全发放奖励,请返回错误响应。修复原因后,从界面[重新发送投递](https://gamemonitoring.cn/developers/docs/webhook#tests-resend)。 ## 奖励示例 {#reward-example} 假设玩家 `PlayerName` 为 ID 为 `1` 的服务器投票,而你的系统需要给他增加 `100` 枚金币。 1. GAMEMONITORING 发送 Webhook,包含 `event_type: server.vote` 和 `event_id: 9824cabb-2203-437e-9b6c-aba43dde3e4b`。 2. 处理器[验证 signature](https://gamemonitoring.cn/developers/docs/webhook#signature)。如果签名无效,返回 `401` 并停止。 3. 处理器请求 `GET /votes/9824cabb-2203-437e-9b6c-aba43dde3e4b`,获得昵称、服务器和用户数据,然后找到本地账号。 4. 在事务中,处理器保存 `event_type` + `event_id` 用于[防重复处理](https://gamemonitoring.cn/developers/docs/webhook#deduplication)。 5. 对于新事件,处理器在同一个事务中增加 `100` 枚金币。 6. 重复投递时,处理器找到已经保存的事件,不再次发放奖励,并返回 `204`。 同一流程也适用于物品、角色、VIP 时长、促销码或内部队列中的任务。 ## 投票事件 {#vote-event} 服务器投票会发送 `server.vote`,项目投票会发送 `project.vote`。事件请求体只包含投递数据:`event_type`、`event_id`、`is_test` 和 `signature`。完整投票数据必须单独请求。 **事件示例** ```json { "event_id": "9824cabb-2203-437e-9b6c-aba43dde3e4b", "event_type": "server.vote", "is_test": false, "signature": "ae83b8aba88a3a9ab3b97b1f6d65664da5628a9cb64d56d5132807bca5472e4f" } ``` 在此事件中,`event_id` 是投票 ID。不要把 Webhook 请求体作为昵称、服务器或用户数据来源:这些值来自 API。 ## 获取投票数据 {#fetch-vote} 把 `event_id` 当作 `vote_id` 使用,并通过 [GET /votes/:vote_id](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__GET) 请求投票数据: **投票数据请求** ```bash curl -sS "https://api.gamemonitoring.cn/votes/9824cabb-2203-437e-9b6c-aba43dde3e4b" ``` 发放奖励通常需要 `response.nickname`、`response.server` 和公开的 `response.user` 数据。如果奖励依赖具体服务器,请始终检查 `response.server.id`。 字段使用方式:`response.nickname` 帮助在你的数据库中查找玩家账号,`response.server.id` 选择服务器的奖励规则,`response.user.id` 可以作为投票的 GAMEMONITORING 用户 ID 保存到奖励日志。 如果 API 暂时不可用或返回意外响应,请不要在未验证的情况下发放奖励。返回错误码,修复原因后从界面[重新发送投递](https://gamemonitoring.cn/developers/docs/webhook#tests-resend)。 ## 第 3 步:投票奖励处理器 {#complete-example} 示例延续基础处理器:它会验证签名,获取投票数据,防止事件重复处理,并在同一个事务中发放奖励。请把用户表名、余额字段和玩家查找规则替换为你系统中的结构。 运行示例前,请先配置 [项目 Webhook](https://gamemonitoring.cn/developers/docs/webhook#connect),检查 [GET /votes/:vote_id](https://gamemonitoring.cn/developers/docs/api/votes/:vote_id/__GET),并把 SQL 用户更新语句替换为你的账号模型。 ### PHP ```php $isTest ? 'true' : 'false']); // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. $fields = array_values(array_filter(array_keys($event), fn($field) => $field !== 'signature')); sort($fields, SORT_STRING); // Calculate HMAC-SHA256 with the webhook token from your settings. $signing = implode('&', array_map(fn($field) => $field . '=' . (string) ($signingData[$field] ?? ''), $fields)); $expected = hash_hmac('sha256', $signing, $secret); $actual = (string) ($event['signature'] ?? ''); // Reject the request before doing any work when the signature is invalid. if (!hash_equals($expected, $actual)) { http_response_code(401); exit; } // Test deliveries must not change balance, inventory, roles, or production data. if ($isTest) { http_response_code(204); exit; } // Real deliveries must include an event type and a stable event id. $eventType = (string) ($event['event_type'] ?? ''); $eventId = (string) ($event['event_id'] ?? ''); if ($eventType === '' || $eventId === '') { http_response_code(400); exit; } // This reward handler processes server and project vote events. if (!in_array($eventType, ['server.vote', 'project.vote'], true)) { http_response_code(204); exit; } // At this point the webhook is trusted. Load vote data before opening a database transaction. $pdo = null; try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. $voteUrl = $apiUrl . '/votes/' . rawurlencode($eventId); $voteContext = stream_context_create(['http' => ['timeout' => 5]]); $voteBody = @file_get_contents($voteUrl, false, $voteContext); if ($voteBody === false) { throw new RuntimeException('Vote API request failed'); } $voteResponse = json_decode($voteBody, true) ?: []; $vote = $voteResponse['response'] ?? null; // Do not issue a reward when the vote response is missing a concrete nickname. if (!is_array($vote) || !isset($vote['nickname']) || !is_string($vote['nickname'])) { throw new RuntimeException('Vote API response does not include nickname'); } // Verify that the API entity matches the event before changing the account. $expectedEntityType = $eventType === 'project.vote' ? 'project' : 'server'; if (($vote['entity_type'] ?? '') !== $expectedEntityType) { throw new RuntimeException('Vote entity type does not match event type'); } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. $nickname = trim($vote['nickname']); if ($nickname === '') { throw new RuntimeException('Vote nickname is empty'); } // Add your local database connection for deduplication and event-specific work. $pdo = new PDO('mysql:host=127.0.0.1;dbname=game;charset=utf8mb4', 'game', 'password', [ PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION, ]); // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. $pdo->beginTransaction(); // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. $deduplicate = $pdo->prepare('INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)'); $deduplicate->execute([$eventType, $eventId]); // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if ($deduplicate->rowCount() === 0) { $pdo->commit(); http_response_code(204); exit; } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. $balance = $pdo->prepare('UPDATE users SET balance = balance + ? WHERE nickname = ?'); $balance->execute([$rewardAmount, $nickname]); // Commit only after deduplication and event-specific work both succeed. $pdo->commit(); // Log only newly processed real events after the transaction succeeds. syslog(LOG_INFO, 'Accepted webhook event ' . $eventType . ' #' . $eventId); http_response_code(204); } catch (Throwable $error) { // Roll back partial database work so the event can be retried safely. if ($pdo instanceof PDO && $pdo->inTransaction()) { $pdo->rollBack(); } // 500 keeps the delivery failed instead of marking unfinished work as done. http_response_code(500); } ``` ### JavaScript ```javascript const crypto = require('node:crypto') const express = require('express') const mysql = require('mysql2/promise') const app = express() // Replace this token with the signing token from your GAMEMONITORING webhook settings. const secret = 'paste-webhook-token-here' // Add the GAMEMONITORING API URL and reward settings for vote events. const apiUrl = 'https://api.gamemonitoring.cn' const rewardAmount = '1.00' // Add your local database connection for deduplication and event-specific work. const db = mysql.createPool({ database: 'game', host: '127.0.0.1', password: 'password', user: 'game', }) // GAMEMONITORING sends JSON with Content-Type: application/json. app.use(express.json()) function isValidSignature(event) { // Build the exact signing string: all body fields except signature, // sorted by key and joined as key=value pairs with &. const fields = Object.keys(event).filter((field) => field !== 'signature').sort() const signing = fields.map((field) => field + '=' + String(event[field] ?? '')).join('&') // Calculate HMAC-SHA256 with the webhook token from your settings. const expected = crypto.createHmac('sha256', secret).update(signing).digest('hex') const actual = String(event.signature || '') // timingSafeEqual requires buffers with the same length. const expectedBuffer = Buffer.from(expected) const actualBuffer = Buffer.from(actual) return expectedBuffer.length === actualBuffer.length && crypto.timingSafeEqual(expectedBuffer, actualBuffer) } app.post('/gamemonitoring-webhook', async (req, res) => { // Read the webhook payload parsed by express.json(). const event = req.body || {} // Reject the request before doing any work when the signature is invalid. if (!isValidSignature(event)) { return res.sendStatus(401) } // Test deliveries must not change balance, inventory, roles, or production data. if (event.is_test === true) { return res.sendStatus(204) } // Real deliveries must include an event type and a stable event id. const eventType = String(event.event_type || '') const eventId = String(event.event_id || '') if (!eventType || !eventId) { return res.sendStatus(400) } // This reward handler processes server and project vote events. if (!['server.vote', 'project.vote'].includes(eventType)) { return res.sendStatus(204) } // At this point the webhook is trusted. Load vote data before opening a database transaction. let connection try { // Load full vote data by event_id. Nickname, entity, and user data are not // in the webhook body. Return 500 if the API cannot confirm the vote. const voteUrl = apiUrl + '/votes/' + encodeURIComponent(eventId) const voteResponse = await fetch(voteUrl, { signal: AbortSignal.timeout(5000) }) if (!voteResponse.ok) { throw new Error('Vote API request failed') } const voteBody = await voteResponse.json() const vote = voteBody.response // Do not issue a reward when the vote response is missing a concrete nickname. if (!vote || typeof vote.nickname !== 'string') { throw new Error('Vote API response does not include nickname') } // Verify that the API entity matches the event before changing the account. const expectedEntityType = eventType === 'project.vote' ? 'project' : 'server' if (vote.entity_type !== expectedEntityType) { throw new Error('Vote entity type does not match event type') } // Use vote nickname to update the local account. The entity id is available in // vote.entity_id and in either vote.server.id or vote.project.id. const nickname = vote.nickname.trim() if (!nickname) { throw new Error('Vote nickname is empty') } connection = await db.getConnection() // Keep deduplication and the real state change in one transaction. // If any step fails, return 500 so the delivery can be retried. await connection.beginTransaction() // Store the event once. This requires the table to have a unique key on // (event_type, event_id). Duplicate deliveries affect zero rows. const [deduplicate] = await connection.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (?, ?)', [eventType, eventId], ) // The event was already processed earlier. Return success without changing // state again, because duplicate delivery is expected. if (deduplicate.affectedRows === 0) { await connection.commit() return res.sendStatus(204) } // Add event-specific database changes here. Keep them after the // deduplication insert and inside this same transaction. await connection.execute('UPDATE users SET balance = balance + ? WHERE nickname = ?', [rewardAmount, nickname]) // Commit only after deduplication and event-specific work both succeed. await connection.commit() // Log only newly processed real events after the transaction succeeds. console.log('Accepted webhook event ' + eventType + ' #' + eventId) return res.sendStatus(204) } catch (error) { // Roll back partial database work so the event can be retried safely. if (connection) { await connection.rollback() } // 500 keeps the delivery failed instead of marking unfinished work as done. return res.sendStatus(500) } finally { // Return the connection to the pool. if (connection) { connection.release() } } }) app.listen(3000) ``` ### Python ```python import hashlib import hmac import pymysql import requests from flask import Flask, abort, request app = Flask(__name__) # Replace this token with the signing token from your GAMEMONITORING webhook settings. secret = b'paste-webhook-token-here' # Add the GAMEMONITORING API URL and reward settings for vote events. api_url = 'https://api.gamemonitoring.cn' reward_amount = '1.00' # Add your local database connection for deduplication and event-specific work. db_config = { 'database': 'game', 'host': '127.0.0.1', 'password': 'password', 'user': 'game', } def stringify(value): # GAMEMONITORING signs booleans as lowercase true/false strings. if isinstance(value, bool): return 'true' if value else 'false' return '' if value is None else str(value) def is_valid_signature(event): # Build the exact signing string: all body fields except signature, # sorted by key and joined as key=value pairs with &. fields = sorted(field for field in event.keys() if field != 'signature') signing = '&'.join(f'{field}={stringify(event.get(field))}' for field in fields) # Calculate HMAC-SHA256 with the webhook token from your settings. expected = hmac.new(secret, signing.encode(), hashlib.sha256).hexdigest() actual = str(event.get('signature') or '') return hmac.compare_digest(expected, actual) @app.post('/gamemonitoring-webhook') def gamemonitoring_webhook(): # Read and decode the JSON body sent by GAMEMONITORING. event = request.get_json(silent=True) or {} # Reject the request before doing any work when the signature is invalid. if not is_valid_signature(event): abort(401) # Test deliveries must not change balance, inventory, roles, or production data. if event.get('is_test') is True: return '', 204 # Real deliveries must include an event type and a stable event id. event_type = str(event.get('event_type') or '') event_id = str(event.get('event_id') or '') if not event_type or not event_id: abort(400) # This reward handler processes server and project vote events. if event_type not in ('server.vote', 'project.vote'): return '', 204 # At this point the webhook is trusted. Load vote data before opening a database transaction. connection = None try: # Load full vote data by event_id. Nickname, entity, and user data # are not in the webhook body. Return 500 if the API cannot confirm the vote. vote_url = f"{api_url}/votes/{event_id}" response = requests.get(vote_url, timeout=5) if not response.ok: raise RuntimeError('Vote API request failed') vote = response.json().get('response') # Do not issue a reward when the vote response is missing a concrete nickname. if not isinstance(vote, dict) or not isinstance(vote.get('nickname'), str): raise RuntimeError('Vote API response does not include nickname') # Verify that the API entity matches the event before changing the account. expected_entity_type = 'project' if event_type == 'project.vote' else 'server' if vote.get('entity_type') != expected_entity_type: raise RuntimeError('Vote entity type does not match event type') # Use vote nickname to update the local account. The entity id is available in # vote.entity_id and in either vote.server.id or vote.project.id. nickname = vote['nickname'].strip() if not nickname: raise RuntimeError('Vote nickname is empty') connection = pymysql.connect(**db_config) connection.begin() # Keep deduplication and the real state change in one transaction. # If any step fails, return 500 so the delivery can be retried. with connection.cursor() as cursor: # Store the event once. This requires the table to have a unique key # on (event_type, event_id). Duplicate deliveries affect zero rows. cursor.execute( 'INSERT IGNORE INTO gamemonitoring_webhooks (event_type, event_id) VALUES (%s, %s)', (event_type, event_id), ) # The event was already processed earlier. Return success without # changing state again, because duplicate delivery is expected. if cursor.rowcount == 0: connection.commit() return '', 204 # Add event-specific database changes here. Keep them after the # deduplication insert and inside this same transaction. cursor.execute('UPDATE users SET balance = balance + %s WHERE nickname = %s', (reward_amount, nickname)) # Commit only after deduplication and event-specific work both succeed. connection.commit() # Log only newly processed real events after the transaction succeeds. app.logger.info('Accepted webhook event %s #%s', event_type, event_id) return '', 204 except Exception: # Roll back partial database work so the event can be retried safely. if connection: connection.rollback() # 500 keeps the delivery failed instead of marking unfinished work as done. abort(500) finally: # Close the database connection. if connection: connection.close() ``` https://gamemonitoring.cn/developers/docs/webhook/vote.md --- # 系统 IP 地址 GAMEMONITORING 使用这些 IP 地址检查游戏服务器,并把 [Webhook 请求](https://gamemonitoring.cn/developers/docs/webhook#connect)投递到你的系统。 如果你的服务器、网站、WAF、CDN 或 bot protection 限制进入请求,请把它们加入 allowlist。 ## 何时需要添加 {#when-needed} - 游戏服务器只接受允许地址的请求; - [Webhook 处理器](https://gamemonitoring.cn/developers/docs/webhook#handler-requirements)受 firewall、WAF 或 Cloudflare 保护; - bot protection 会拦截自动请求; - 主机服务商要求提供网络规则使用的 IP 列表。 ## 使用示例 {#usage-example} Webhook 示例:处理器地址是 `https://panel.example.com/gamemonitoring-webhook`,域名受 Cloudflare 保护。请把 GAMEMONITORING IP 地址加入该域名或精确路径的 allowlist,避免 Cloudflare 显示 challenge 或拦截 [Webhook `POST` 请求](https://gamemonitoring.cn/developers/docs/webhook#handler-requirements)。 游戏服务器示例:firewall 只允许可信地址访问 query 端口。请把 GAMEMONITORING IP 地址加入 query 端口规则,否则监控无法稳定检查在线状态和服务器状态。 ## 配置允许列表 {#allowlist} 把上方列表中的 IP 地址交给系统管理员或主机服务商。规则必须允许这些地址向你的游戏服务器或 Webhook 处理器发送进入请求。 如果规则按路径配置,请限制到所需 endpoint,例如 `/gamemonitoring-webhook`。如果规则按端口配置,请只指定游戏 query 端口或接收 Webhook 的 web-server 端口。 ## 配置后验证 {#verification} 修改规则后,发送测试请求或[测试 Webhook](https://gamemonitoring.cn/developers/docs/webhook#tests-resend),并确认请求不再被拦截。 如果验证失败,请查看 firewall、WAF 或 Cloudflare 日志。日志中应包含源 IP、请求路径和拦截原因。通过这些信息可以判断域名、路径、端口或规则顺序是否遗漏。 ## Cloudflare 配置 {#cloudflare} 如果 Webhook 处理器在 Cloudflare 后面,请把 GAMEMONITORING IP 地址加入一个跳过 WAF 检查的规则: 1. 登录 Cloudflare dashboard。 2. 选择需要的域名。 3. 打开 **Security**。 4. 选择 **WAF**。 5. 打开 **Custom rules**。 6. 点击 **Create rule**。 7. 设置清晰名称,例如 **Allow GAMEMONITORING**。 8. 在 **Field** 中选择 **IP Source Address**。 9. 在 **Operator** 中选择 **is in**。 10. 在 **Value** 中添加上方列表中的 IP 地址。 11. 在 **Choose action** 中选择 **Skip**。 12. 在 **WAF components to skip** 中选择会拦截处理器请求的检查。 13. 在 **Select order** 中选择 **First**。 14. 点击 **Deploy**。 如果配置后请求仍被拦截,请检查 firewall 或 Cloudflare 日志,并确认规则应用到了正确域名和处理器路径。 ```http GET https://api.gamemonitoring.cn/pages/system/ips ``` https://gamemonitoring.cn/developers/docs/ips.md