后端即时通讯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点击查看免费下载本篇技术指南围绕 aiogram 框架中的GiveawayCreated类型展开讲解其在 Telegram Bot API 中代表的消息语义定时抽奖创建的服务消息、唯一字段prize_star_count的含义与取值约束并给出在 aiogram 的 Message、Dispatcher 与过滤器体系中识别与处理该事件的最佳实践帮助读者在基于 asyncio 的全异步机器人中完整实现抽奖活动从创建到开奖的监控链路。一、GiveawayCreated 是什么GiveawayCreated是 aiogram 中对应 Telegram Bot APIGiveawayCreated对象的类型官方语义为This object represents a service message about the creation of a scheduled giveaway即关于已排定的抽奖活动创建的服务消息。从源码结构看它定义于 aiogram/types/giveaway_created.pyclass GiveawayCreated(TelegramObject): This object represents a service message about the creation of a scheduled giveaway. Source: https://core.telegram.org/bots/api#giveawaycreated prize_star_count: int | None None *Optional*. The number of Telegram Stars to be split between giveaway winners; for Telegram Star giveaways only if TYPE_CHECKING: # DO NOT EDIT MANUALLY!!! # This section was auto-generated via butcher # Is needed only for type checking and IDE support without any additional plugins def __init__( __pydantic__self__, *, prize_star_count: int | None None, **__pydantic_kwargs: Any ) - None: # DO NOT EDIT MANUALLY!!! # This method was auto-generated via butcher # Is needed only for type checking and IDE support without any additional plugins super().__init__(prize_star_countprize_star_count, **__pydantic_kwargs)几点关键结论它继承自 aiogram/types/base.py 中的TelegramObject即 PydanticBaseModel的子类因此具备model_config中配置的行为frozenTrue实例不可变、extraallow容忍额外字段、populate_by_nameTrue、validate_assignmentTrue等。当 Telegram 服务端未来在对象中追加新字段时extraallow可以保证兼容性不会因未知字段抛错。prize_star_count是int | None默认None。它仅在Telegram Star 抽奖以 Telegram Stars 作为奖品的抽奖中出现表示将在中奖者之间分配的通告Stars总数。普通实物/礼物类抽奖中该字段为None。TYPE_CHECKING分支中的__init__由butcher自动生成仅服务于类型检查与 IDE 提示运行时 Pydantic 会以默认方式完成实例化与校验。二、prize_star_count 字段详解字段类型默认值说明prize_star_countint \| NoneNone仅在 Telegram Star 抽奖中出现表示分配给抽奖获胜者的 Telegram Stars 总数量使用注意条件性字段只有奖品为 Telegram Stars 的抽奖Star giveaway才会携带该字段普通抽奖实物奖品、Telegram Premium 订阅等不携带此时值为None。与 ChatBoostSourceGiveaway 联动在 aiogram/types/chat_boost_source_giveaway.py 中同样存在prize_star_count注释指出 Telegram Star 抽奖带来的加成boost次数约为prize_star_count / 500次、持续一年。这说明抽奖创建事件与频道加成机制直接关联——若你的机器人需要统计群组加成来源可以据此关联处理。历史版本根据 CHANGES.rstprize_star_count字段是在 3.13.02024-09-08版本中随 Telegram Bot API 的更新一并加入到GiveawayCreated、Giveaway、GiveawayWinners与ChatBoostSourceGiveaway的。如果你的部署环境使用更早的 aiogram 版本需要先升级才能读取该字段。三、GiveawayCreated 在 Message 中的位置GiveawayCreated不是独立事件而是作为Message对象上的一个可选字段存在。在 aiogram/types/message.py 中giveaway_created: GiveawayCreated | None None *Optional*. Service message: a scheduled giveaway was created也就是说当频道/群组管理员在 Telegram 客户端中创建一个定时抽奖时机器人收到的Message的giveaway_created字段即被填充同时该消息没有普通文本内容text为Nonefrom_user通常也为空服务消息。content_type 识别aiogram 为每种消息内容定义了枚举见 aiogram/enums/content_type.pyGIVEAWAY_CREATED giveaway_created GIVEAWAY giveaway GIVEAWAY_WINNERS giveaway_winners GIVEAWAY_COMPLETED giveaway_completedMessage.content_type属性aiogram/types/message.py按顺序检查各字段并返回对应枚举值if self.giveaway_created: return ContentType.GIVEAWAY_CREATED if self.giveaway: return ContentType.GIVEAWAY if self.giveaway_completed: return ContentType.GIVEAWAY_COMPLETED if self.giveaway_winners: return ContentType.GIVEAWAY_WINNERS因此判断这条消息是不是抽奖创建通知既可以直接检查message.giveaway_created is not None也可以用message.content_type ContentType.GIVEAWAY_CREATED。测试用例 tests/test_api/test_types/test_message.py 与 tests/test_api/test_types/test_message.py 构造了带GiveawayCreated(prize_star_count42)的 Message 并断言其content_type为ContentType.GIVEAWAY_CREATED验证了上述行为。四、在 Dispatcher 中注册处理函数aiogram 3.x 的典型用法是使用Router.message()装饰器配合内容类型过滤。Message字段名与ContentType枚举值一致giveaway_created可以直接作为过滤参数from aiogram import Router, types from aiogram.enums import ContentType router Router() router.message(ContentType.GIVEAWAY_CREATED) async def on_giveaway_created(message: types.Message) - None: giveaway_created message.giveaway_created # 此时 giveaway_created 一定非 None if giveaway_created.prize_star_count is not None: print(fStar 抽奖已创建奖品总量 {giveaway_created.prize_star_count} Stars) else: print(普通抽奖已创建无 Star 奖品)也可以不依赖ContentType直接对Message的字段做过滤router.message(lambda message: message.giveaway_created is not None) async def on_giveaway_created_v2(message: types.Message) - None: ...两种方式均可工作前者由框架在分发时根据message.content_type与过滤值匹配后者则是自定义过滤器。参考 aiogram/filters/command.py 中Command过滤器的实现风格aiogram 的过滤器体系会按注册顺序依次调用并支持组合and_f、or_f、invert_f见 aiogram/filters/init.py。五、抽奖事件全链路GiveawayCreated 与相关类型仅处理创建事件往往不够。一个完整的抽奖监控机器人通常会同时关注以下四个阶段阶段aiogram 类型Message 字段说明抽奖被创建定时GiveawayCreatedmessage.giveaway_created服务消息标记定时抽奖已排定抽奖消息本身Giveawaymessage.giveaway展示奖品、参与条件等具体信息的消息见 aiogram/types/giveaway.py开奖公开中奖者GiveawayWinnersmessage.giveaway_winners公布中奖用户列表开奖未公开中奖者GiveawayCompletedmessage.giveaway_completed无公开名单的完成通知Giveaway类型还包含chats需加入才能参与的聊天列表、winners_selection_date开奖时间戳、winner_count中奖人数、only_new_members、has_public_winners、prize_description、country_codes、prize_star_count、premium_subscription_month_count等字段是理解抽奖规则细节的关键对象可与GiveawayCreated配合使用。一个覆盖四类事件的示例from aiogram import Router, types from aiogram.enums import ContentType router Router() router.message(ContentType.GIVEAWAY_CREATED) async def giveaway_created(message: types.Message) - None: print(抽奖已排定, message.giveaway_created) router.message(ContentType.GIVEAWAY) async def giveaway_announced(message: types.Message) - None: giveaway message.giveaway print(f开奖时间: {giveaway.winners_selection_date}, 中奖人数: {giveaway.winner_count}) router.message(ContentType.GIVEAWAY_WINNERS) async def giveaway_winners(message: types.Message) - None: print(抽奖已开奖, message.giveaway_winners) router.message(ContentType.GIVEAWAY_COMPLETED) async def giveaway_completed(message: types.Message) - None: print(抽奖已完成, message.giveaway_completed)注意copy_message/copy_messages方法明确禁止复制服务消息与抽奖类消息见 aiogram/methods/copy_message.py 与 aiogram/methods/copy_messages.py 的文档说明Service messages, paid media messages, giveaway messages, giveaway winners messages, and invoice messages cant be copied。因此不要尝试转发或复制这类事件消息收到后直接读取字段做业务处理即可。六、实战Star 抽奖创建后的自动化通知结合以上内容一个典型的实战场景是当频道创建了以 Stars 为奖品的抽奖时机器人立即向运营群发送摘要。完整代码示例import asyncio from aiogram import Bot, Dispatcher, Router, types from aiogram.enums import ContentType from aiogram.filters import CommandStart BOT_TOKEN YOUR_BOT_TOKEN ADMIN_CHAT_ID -1001234567890 router Router() router.message(ContentType.GIVEAWAY_CREATED) async def notify_star_giveaway(message: types.Message, bot: Bot) - None: giveaway_created message.giveaway_created if giveaway_created is None or giveaway_created.prize_star_count is None: return # 非 Star 抽奖忽略或另行处理 chat_title message.chat.title or str(message.chat.id) text ( f 频道 {chat_title} 创建了 Star 抽奖\n f奖品总额: {giveaway_created.prize_star_count} ⭐ ) await bot.send_message(ADMIN_CHAT_ID, text) router.message(CommandStart()) async def start(message: types.Message) - None: await message.answer(抽奖监控机器人已启动) async def main() - None: bot Bot(BOT_TOKEN) dp Dispatcher() dp.include_router(router) await dp.start_polling(bot) if __name__ __main__: asyncio.run(main())代码要点通过ContentType.GIVEAWAY_CREATED过滤避免对普通消息做无谓解析用prize_star_count is not None区分 Star 抽奖与普通抽奖message.chat为Chat对象可直接读取title等信息见 aiogram/types/chat.py整体保持异步风格与 aiogram fully asynchronous framework ... using asyncio 的设计一致。七、小结GiveawayCreated表示定时抽奖已被创建的服务消息位于Message.giveaway_created字段唯一字段prize_star_count仅存在于 Telegram Star 抽奖中值为int否则为None可用message.content_type ContentType.GIVEAWAY_CREATED或message.giveaway_created is not None识别该事件抽奖监控应同时关注Giveaway、GiveawayWinners、GiveawayCompleted三类相关消息形成完整的事件链路服务消息与抽奖消息不可复制/转发copy_message、copy_messages的限制处理时直接读取字段即可。更深入的内容可继续阅读仓库中的以下文件GiveawayCreated 源码Message 类型定义与 content_type 实现ContentType 枚举Giveaway 类型抽奖详情对应测试用例赞分享后端即时通讯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点击查看免费下载相关推荐aiogram SuggestedPostApproved 类型深度解析处理 Telegram「建议帖子已批准」服务消息aiogram SuggestedPostApproved 类型深度解析处理 Telegram「建议帖子已批准」服务消息 SuggestedPostAppro后端即时通讯API设计aiogram 中 SuggestedPostRefunded 类型详解处理频道建议帖退款服务消息aiogram 中 SuggestedPostRefunded 类型详解处理频道建议帖退款服务消息 本文围绕 aiogram基于 asyncio 的全异步后端即时通讯API设计aiogram 中 DiceEmoji 枚举详解Telegram 骰子消息的类型安全实践aiogram 中 DiceEmoji 枚举详解Telegram 骰子消息的类型安全实践 aiogram.enums.dice_emoji 是 aiogram后端即时通讯API设计上一篇告别单调对话Chatpad AI如何重新定义ChatGPT用户体验下一篇如何使用html5lib-pythonPython中最强大的HTML解析库完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
