后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载导读setGameScore是 Telegram Bot API 中用于在游戏消息中更新指定用户分数的核心方法。本文以 aiogram 框架中 set_game_score.rst 文档为基础结合 set_game_score.py、bot.py 与 test_set_game_score.py 等源码完整讲解该方法的所有参数、返回类型、三种调用方式Bot 方法、方法对象、Webhook 处理器返回以及与sendGame、getGameHighScores等游戏 API 的配合用法。读完后你将掌握如何在自己的 aiogram 机器人中正确下发、更新和校验游戏分数。方法概述SetGameScore用于设置指定用户在一条游戏消息中的分数。根据 Telegram Bot API 官方定义该方法在成功时有如下行为如果目标消息是普通聊天消息返回Message对象如果目标消息是内联消息inline message返回True如果新分数不大于该用户在当前聊天中的现有分数且force为False则返回错误。这一行为完整地映射到了 aiogram 的类型定义中在 set_game_score.py 中可以看到class SetGameScore(TelegramMethod[Message | bool]): __returning__ Message | bool __api_method__ setGameScore其中__returning__ Message | bool声明了该方法的返回类型为Message | bool与 Bot API 文档中的Returns: Message | bool完全一致__api_method__ setGameScore声明了实际发给 Telegram 服务器的 API 方法名即 HTTP POST 请求中的method字段。在 文档 中这一返回值被描述为Returns: :obj:Message | bool说明该方法是少数返回类型为联合类型的 Telegram 方法之一。参数详解SetGameScore共包含 7 个参数其中 2 个为必填其余为可选。以下基于 set_game_score.py 的字段定义逐项说明。必填参数参数类型说明user_idint用户标识符即要给哪个用户更新分数scoreint新分数必须是非负整数non-negative可选参数参数类型默认值说明forcebool | NoneNone传入True允许高分被降低。常用于修复错误或封禁作弊者disable_edit_messagebool | NoneNone传入True表示游戏消息不自动编辑以包含当前计分板chat_idint | NoneNone如果未指定inline_message_id则必填。目标聊天的唯一标识符message_idint | NoneNone如果未指定inline_message_id则必填。已发送消息的标识符inline_message_idstr | NoneNone如果未指定chat_id和message_id则必填。内联消息的标识符参数的关键语义从源码注释中可以看到几个值得注意的细节score必须非负传入负数会导致 Telegram 服务器拒绝该请求。force的用途默认情况下 Telegram 不允许降低用户已有的高分。若你的游戏存在计分错误修复、作弊用户清零等场景需要显式传forceTrue。源码注释原文为PassTrueif the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters。目标消息的两种定位方式要么通过chat_id message_id定位普通消息要么通过inline_message_id定位内联消息二者互斥。当指定inline_message_id时chat_id与message_id不可同时使用。与 Bot 方法签名的对应关系在 bot.py 中bot.set_game_score快捷方法拥有完全一致的参数签名并额外增加了request_timeout参数用于控制请求超时async def set_game_score( self, user_id: int, score: int, force: bool | None None, disable_edit_message: bool | None None, chat_id: int | None None, message_id: int | None None, inline_message_id: str | None None, request_timeout: int | None None, ) - Message | bool:该方法的实现本质上是构造一个SetGameScore对象并通过await self(call, request_timeoutrequest_timeout)发起请求因此两种调用方式在行为上完全等价。三种调用方式set_game_score.rst 文档详细列出了 aiogram 特有的三种调用模式下面逐一说明。方式一作为 Bot 方法直接调用这是最常用、最直观的方式通过bot.set_game_score(...)直接调用result: Message | bool await bot.set_game_score(...)一个实际可运行的示例from aiogram import Bot bot Bot(tokenYOUR_BOT_TOKEN) # 更新普通聊天中某条游戏消息的分数 result await bot.set_game_score( user_id123456789, score100500, chat_id-1001234567890, message_id42, )方式二作为方法对象调用aiogram 的每个 Telegram 方法都可以实例化为对象有两种导入途径全路径导入from aiogram.methods.set_game_score import SetGameScore别名导入from aiogram.methods import SetGameScore使用指定 Bot 实例执行result: Message | bool await bot(SetGameScore(...))SetGameScore继承自 TelegramMethod后者在内部挂载 Bot 上下文。该方法对象支持两种执行方式显式传入 Botawait bot(SetGameScore(...))先挂载再直接await在 base.py 中__await__会读取对象挂载的_bot若未挂载则抛出RuntimeError挂载方法为SetGameScore(...).as_(bot)随后可直接await。这一机制来自 context_controller.py 中的as_(bot)方法。方式三在 Webhook 处理器中直接返回在 aiogram 的 Dispatcher/Webhook 架构中方法对象可以直接作为处理器返回值返回由框架自动执行return SetGameScore(...)这种模式常用于处理器即方法构造器的声明式写法尤其适合通过CallbackQuery回调触发游戏计分更新的场景详见下文实战部分。实战场景完整游戏计分流程为了让setGameScore真正可用需要串联 Telegram 游戏 API 的完整链路发游戏 → 用户点击 → 回调 → 更新分数 → 查询排行榜。以下结合仓库源码梳理完整流程。1. 发送游戏消息使用sendGame方法发送游戏消息对应 send_game.py必填参数为chat_id与game_short_namemessage await bot.send_game( chat_idchat_id, game_short_namemy_game, )2. 接收游戏回调游戏消息通常携带Play game按钮。当用户点击时Telegram 会通过CallbackQuery其game_short_name字段标识游戏回调到机器人。aiogram 中可这样注册处理器from aiogram import F, Router from aiogram.types import CallbackQuery router Router() router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): ...3. 更新分数Webhook 返回式在回调处理器中直接返回SetGameScore对象框架会自动执行router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): # 内联游戏消息使用 inline_message_id 定位 return SetGameScore( user_idcallback.from_user.id, score100500, inline_message_idcallback.inline_message_id, forceFalse, disable_edit_messageFalse, )4. 更新分数显式调用式也可以在处理器中显式调用 Bot 方法比如同时配合answer_callback_query回复用户router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): await callback.answer() # 消除客户端等待动画 result await bot.set_game_score( user_idcallback.from_user.id, score100500, inline_message_idcallback.inline_message_id, forceTrue, )需要说明的是CallbackQuery.answer()是 callback_query.py 中定义的快捷方法会自动填充callback_query_id。5. 查询分数榜setGameScore的更新结果可通过getGameHighScores校验或展示对应 get_game_high_scores.py返回list[GameHighScore]scores await bot.get_game_high_scores( user_id123456789, inline_message_idinline message, )测试验证仓库中已有针对该方法的自动化测试见 test_set_game_score.pyclass TestSetGameScore: async def test_bot_method(self, bot: MockedBot): prepare_result bot.add_result_for(SetGameScore, okTrue, resultTrue) response: Message | bool await bot.set_game_score( user_id42, score100500, inline_message_idinline message ) bot.get_request() assert response prepare_result.result该测试用例验证了三点bot.set_game_score(...)快捷方法可以被正常调用返回类型为Message | bool当结果是布尔值True时表示内联消息场景更新成功通过MockedBot可以模拟 Telegram 服务器响应方便在不连接真实网络的情况下编写测试。常见问题与注意事项分数必须单调递增若不传forceTrue新分数必须大于用户当前分数否则 Telegram 返回错误。这符合 Bot API 文档中的约束也是 set_game_score.py 源码注释明确说明的行为。普通消息与内联消息的定位互斥chat_id message_id与inline_message_id二选一同时传参可能导致请求失败。返回类型不确定由于返回类型为Message | bool在编写代码时应先判断实际类型再访问消息属性例如通过isinstance(result, Message)或直接判断布尔值。score非负约束负数分数会导致请求被拒绝务必在业务层校验。小结SetGameScore是 Telegram 游戏生态中衔接发游戏—玩—计分闭环的关键方法。aiogram 为其提供了 Bot 方法快捷调用、方法对象调用与 Webhook 处理器返回值三种等价方式且源码methods/set_game_score.py、Bot 客户端封装client/bot.py与测试tests/test_api/test_methods/test_set_game_score.py三处实现保持一致。开发者可以依据本文的调用示例与参数语义快速在自己的机器人中接入或修复游戏计分功能。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐如何快速使用Steam API获取游戏数据的完整指南如何快速使用Steam API获取游戏数据的完整指南 Steam API是一个专为Laravel框架设计的强大工具包让你能够轻松获取Steam平台上的各种游后端API设计3分钟掌握游戏手柄测试Gamepad API Test 完整使用指南3分钟掌握游戏手柄测试Gamepad API Test 完整使用指南 Gamepad API Test 是一款基于 JavaScript 开发的轻量级游戏手柄XUnity.AutoTranslator游戏翻译工具新手完整使用指南XUnity.AutoTranslator游戏翻译工具新手完整使用指南 XUnity.AutoTranslator是一款功能强大的游戏翻译工具专为帮助玩家消游戏开发本地部署AI 应用上一篇MDX国际化解决方案多语言内容管理和动态翻译下一篇PhotoView实战构建完美图片浏览体验的7个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载导读setGameScore是 Telegram Bot API 中用于在游戏消息中更新指定用户分数的核心方法。本文以 aiogram 框架中 set_game_score.rst 文档为基础结合 set_game_score.py、bot.py 与 test_set_game_score.py 等源码完整讲解该方法的所有参数、返回类型、三种调用方式Bot 方法、方法对象、Webhook 处理器返回以及与sendGame、getGameHighScores等游戏 API 的配合用法。读完后你将掌握如何在自己的 aiogram 机器人中正确下发、更新和校验游戏分数。方法概述SetGameScore用于设置指定用户在一条游戏消息中的分数。根据 Telegram Bot API 官方定义该方法在成功时有如下行为如果目标消息是普通聊天消息返回Message对象如果目标消息是内联消息inline message返回True如果新分数不大于该用户在当前聊天中的现有分数且force为False则返回错误。这一行为完整地映射到了 aiogram 的类型定义中在 set_game_score.py 中可以看到class SetGameScore(TelegramMethod[Message | bool]): __returning__ Message | bool __api_method__ setGameScore其中__returning__ Message | bool声明了该方法的返回类型为Message | bool与 Bot API 文档中的Returns: Message | bool完全一致__api_method__ setGameScore声明了实际发给 Telegram 服务器的 API 方法名即 HTTP POST 请求中的method字段。在 文档 中这一返回值被描述为Returns: :obj:Message | bool说明该方法是少数返回类型为联合类型的 Telegram 方法之一。参数详解SetGameScore共包含 7 个参数其中 2 个为必填其余为可选。以下基于 set_game_score.py 的字段定义逐项说明。必填参数参数类型说明user_idint用户标识符即要给哪个用户更新分数scoreint新分数必须是非负整数non-negative可选参数参数类型默认值说明forcebool | NoneNone传入True允许高分被降低。常用于修复错误或封禁作弊者disable_edit_messagebool | NoneNone传入True表示游戏消息不自动编辑以包含当前计分板chat_idint | NoneNone如果未指定inline_message_id则必填。目标聊天的唯一标识符message_idint | NoneNone如果未指定inline_message_id则必填。已发送消息的标识符inline_message_idstr | NoneNone如果未指定chat_id和message_id则必填。内联消息的标识符参数的关键语义从源码注释中可以看到几个值得注意的细节score必须非负传入负数会导致 Telegram 服务器拒绝该请求。force的用途默认情况下 Telegram 不允许降低用户已有的高分。若你的游戏存在计分错误修复、作弊用户清零等场景需要显式传forceTrue。源码注释原文为PassTrueif the high score is allowed to decrease. This can be useful when fixing mistakes or banning cheaters。目标消息的两种定位方式要么通过chat_id message_id定位普通消息要么通过inline_message_id定位内联消息二者互斥。当指定inline_message_id时chat_id与message_id不可同时使用。与 Bot 方法签名的对应关系在 bot.py 中bot.set_game_score快捷方法拥有完全一致的参数签名并额外增加了request_timeout参数用于控制请求超时async def set_game_score( self, user_id: int, score: int, force: bool | None None, disable_edit_message: bool | None None, chat_id: int | None None, message_id: int | None None, inline_message_id: str | None None, request_timeout: int | None None, ) - Message | bool:该方法的实现本质上是构造一个SetGameScore对象并通过await self(call, request_timeoutrequest_timeout)发起请求因此两种调用方式在行为上完全等价。三种调用方式set_game_score.rst 文档详细列出了 aiogram 特有的三种调用模式下面逐一说明。方式一作为 Bot 方法直接调用这是最常用、最直观的方式通过bot.set_game_score(...)直接调用result: Message | bool await bot.set_game_score(...)一个实际可运行的示例from aiogram import Bot bot Bot(tokenYOUR_BOT_TOKEN) # 更新普通聊天中某条游戏消息的分数 result await bot.set_game_score( user_id123456789, score100500, chat_id-1001234567890, message_id42, )方式二作为方法对象调用aiogram 的每个 Telegram 方法都可以实例化为对象有两种导入途径全路径导入from aiogram.methods.set_game_score import SetGameScore别名导入from aiogram.methods import SetGameScore使用指定 Bot 实例执行result: Message | bool await bot(SetGameScore(...))SetGameScore继承自 TelegramMethod后者在内部挂载 Bot 上下文。该方法对象支持两种执行方式显式传入 Botawait bot(SetGameScore(...))先挂载再直接await在 base.py 中__await__会读取对象挂载的_bot若未挂载则抛出RuntimeError挂载方法为SetGameScore(...).as_(bot)随后可直接await。这一机制来自 context_controller.py 中的as_(bot)方法。方式三在 Webhook 处理器中直接返回在 aiogram 的 Dispatcher/Webhook 架构中方法对象可以直接作为处理器返回值返回由框架自动执行return SetGameScore(...)这种模式常用于处理器即方法构造器的声明式写法尤其适合通过CallbackQuery回调触发游戏计分更新的场景详见下文实战部分。实战场景完整游戏计分流程为了让setGameScore真正可用需要串联 Telegram 游戏 API 的完整链路发游戏 → 用户点击 → 回调 → 更新分数 → 查询排行榜。以下结合仓库源码梳理完整流程。1. 发送游戏消息使用sendGame方法发送游戏消息对应 send_game.py必填参数为chat_id与game_short_namemessage await bot.send_game( chat_idchat_id, game_short_namemy_game, )2. 接收游戏回调游戏消息通常携带Play game按钮。当用户点击时Telegram 会通过CallbackQuery其game_short_name字段标识游戏回调到机器人。aiogram 中可这样注册处理器from aiogram import F, Router from aiogram.types import CallbackQuery router Router() router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): ...3. 更新分数Webhook 返回式在回调处理器中直接返回SetGameScore对象框架会自动执行router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): # 内联游戏消息使用 inline_message_id 定位 return SetGameScore( user_idcallback.from_user.id, score100500, inline_message_idcallback.inline_message_id, forceFalse, disable_edit_messageFalse, )4. 更新分数显式调用式也可以在处理器中显式调用 Bot 方法比如同时配合answer_callback_query回复用户router.callback_query(F.game_short_name my_game) async def on_game_played(callback: CallbackQuery): await callback.answer() # 消除客户端等待动画 result await bot.set_game_score( user_idcallback.from_user.id, score100500, inline_message_idcallback.inline_message_id, forceTrue, )需要说明的是CallbackQuery.answer()是 callback_query.py 中定义的快捷方法会自动填充callback_query_id。5. 查询分数榜setGameScore的更新结果可通过getGameHighScores校验或展示对应 get_game_high_scores.py返回list[GameHighScore]scores await bot.get_game_high_scores( user_id123456789, inline_message_idinline message, )测试验证仓库中已有针对该方法的自动化测试见 test_set_game_score.pyclass TestSetGameScore: async def test_bot_method(self, bot: MockedBot): prepare_result bot.add_result_for(SetGameScore, okTrue, resultTrue) response: Message | bool await bot.set_game_score( user_id42, score100500, inline_message_idinline message ) bot.get_request() assert response prepare_result.result该测试用例验证了三点bot.set_game_score(...)快捷方法可以被正常调用返回类型为Message | bool当结果是布尔值True时表示内联消息场景更新成功通过MockedBot可以模拟 Telegram 服务器响应方便在不连接真实网络的情况下编写测试。常见问题与注意事项分数必须单调递增若不传forceTrue新分数必须大于用户当前分数否则 Telegram 返回错误。这符合 Bot API 文档中的约束也是 set_game_score.py 源码注释明确说明的行为。普通消息与内联消息的定位互斥chat_id message_id与inline_message_id二选一同时传参可能导致请求失败。返回类型不确定由于返回类型为Message | bool在编写代码时应先判断实际类型再访问消息属性例如通过isinstance(result, Message)或直接判断布尔值。score非负约束负数分数会导致请求被拒绝务必在业务层校验。小结SetGameScore是 Telegram 游戏生态中衔接发游戏—玩—计分闭环的关键方法。aiogram 为其提供了 Bot 方法快捷调用、方法对象调用与 Webhook 处理器返回值三种等价方式且源码methods/set_game_score.py、Bot 客户端封装client/bot.py与测试tests/test_api/test_methods/test_set_game_score.py三处实现保持一致。开发者可以依据本文的调用示例与参数语义快速在自己的机器人中接入或修复游戏计分功能。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐如何快速使用Steam API获取游戏数据的完整指南如何快速使用Steam API获取游戏数据的完整指南 Steam API是一个专为Laravel框架设计的强大工具包让你能够轻松获取Steam平台上的各种游后端API设计3分钟掌握游戏手柄测试Gamepad API Test 完整使用指南3分钟掌握游戏手柄测试Gamepad API Test 完整使用指南 Gamepad API Test 是一款基于 JavaScript 开发的轻量级游戏手柄XUnity.AutoTranslator游戏翻译工具新手完整使用指南XUnity.AutoTranslator游戏翻译工具新手完整使用指南 XUnity.AutoTranslator是一款功能强大的游戏翻译工具专为帮助玩家消游戏开发本地部署AI 应用上一篇MDX国际化解决方案多语言内容管理和动态翻译下一篇PhotoView实战构建完美图片浏览体验的7个技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
