后端即时通讯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 官方 API 文档docs/api/types/business_opening_hours.rst及其配套类型 BusinessOpeningHoursInterval 为核心系统讲解 Telegram Bot API 中企业账号Business Account营业时间的数据模型两个字段的含义与取值边界、基于周一 0 点起的分钟序号的时间换算规则、该类型在getChat返回的ChatFullInfo中的实际获取方式并结合仓库源码给出可直接运行的解析与展示代码。读完本文你将能够从任意一次getChat响应中正确提取、换算并以人类可读格式输出企业账号的每周营业时间。一、类型定位营业时间在企业账号信息中的地位Telegram 企业账号Business Account可以配置多项公开资料包括简介BusinessIntro、地理位置BusinessLocation以及本文的主角——营业时间BusinessOpeningHours。在 aiogram 的 ChatFullInfo 类型中三者并列出现business_intro: BusinessIntro | None None *Optional*. For private chats with business accounts, the intro of the business business_location: BusinessLocation | None None *Optional*. For private chats with business accounts, the location of the business business_opening_hours: BusinessOpeningHours | None None *Optional*. For private chats with business accounts, the opening hours of the businessbusiness_opening_hours是可选字段只有当目标私聊属于配置了营业时间的企业账号时getChat才会返回该对象普通用户、群组或未配置营业时间的企业账号该字段为None。因此在使用时务必要做空值判断。二、BusinessOpeningHours 字段详解aiogram 的BusinessOpeningHours类定义在 aiogram/types/business_opening_hours.py 中继承自所有 Telegram 对象的公共基类TelegramObjectaiogram/types/base.py。它仅包含两个字段字段类型必填说明time_zone_namestr是定义营业时间所用时区的唯一名称IANA 时区标识符opening_hourslist[BusinessOpeningHoursInterval]是描述营业时间的时间区间列表源码中的完整定义与 docstringclass BusinessOpeningHours(TelegramObject): Describes the opening hours of a business. Source: https://core.telegram.org/bots/api#businessopeninghours time_zone_name: str Unique name of the time zone for which the opening hours are defined opening_hours: list[BusinessOpeningHoursInterval] List of time intervals describing business opening hours1. time_zone_name时区标识是换算的前提time_zone_name使用 IANA 时区数据库的标准名称例如Europe/Moscow、Asia/Shanghai、America/New_York。它表示区间中所有分钟序号都是相对该时区的本地时间计算的而不是 UTC。解读营业时间时必须结合该时区将分钟序号还原为当地时间否则会得出错误的星期与时刻。若业务上需要做跨时区展示如把莫斯科时间转换为用户本地时间应使用zoneinfo或pytz配合该字段做转换。2. opening_hours区间列表的语义opening_hours是一个BusinessOpeningHoursInterval对象的列表描述一周内企业营业的全部时间段。多个区间之间可能存在间隙对应休息时段也可能存在跨周区间。列表中的每个元素都遵循统一的分钟序号编码规则见下节。三、BusinessOpeningHoursInterval以分钟序号表达周内时刻BusinessOpeningHoursInterval定义在 aiogram/types/business_opening_hours_interval.py 中同样继承TelegramObject只包含两个整数字段class BusinessOpeningHoursInterval(TelegramObject): Describes an interval of time during which a business is open. Source: https://core.telegram.org/bots/api#businessopeninghoursinterval opening_minute: int The minutes sequence number in a week, starting on Monday, marking the start of the time interval during which the business is open; 0 - 7 * 24 * 60 closing_minute: int The minutes sequence number in a week, starting on Monday, marking the end of the time interval during which the business is open; 0 - 8 * 24 * 601. 编码规则周一 0 点起算的分钟序号这是整个数据模型最核心的约定一周以周一为起点从周一 00:00 开始按分钟累计编号。一周共有7 × 24 × 60 10080分钟opening_minute合法范围为0到7 * 24 * 60即0–10080标记营业区间的起始时刻closing_minute合法范围为0到8 * 24 * 60即0–11520标记营业区间的结束时刻允许超出 10080用于表达营业时段跨越到下周周一的凌晨。分钟序号与星期 时刻的换算公式如下minute_of_week weekday_index(Monday0, ..., Sunday6) * 1440 hour * 60 minute几个典型换算示例实际时刻time_zone_name 指定的时区内weekday 索引分钟序号周一 09:0000 × 1440 9 × 60 540周一 17:0000 × 1440 17 × 60 1020周五 18:0044 × 1440 18 × 60 6840周日 23:5966 × 1440 23 × 60 59 10019下周一 00:00跨周关门点—100802. 一个完整区间示例例如周一至周五 09:00–18:00 营业Telegram API 会将其表示为如下 JSON{ time_zone_name: Europe/Moscow, opening_hours: [ { opening_minute: 540, closing_minute: 1020 }, { opening_minute: 1980, closing_minute: 2460 }, { opening_minute: 3420, closing_minute: 3900 }, { opening_minute: 4860, closing_minute: 5340 }, { opening_minute: 6300, closing_minute: 6780 } ] }其中6300 4 × 1440 540周五 09:006780 4 × 1440 1020周五 18:00其余区间依次对应周二、周三、周四。四、数据从哪来getChat 与 ChatFullInfo 的调用链营业时间只能通过getChat方法获得。aiogram 中对应的方法类是 GetChat__api_method__ getChat其返回值类型为ChatFullInfoclass GetChat(TelegramMethod[ChatFullInfo]): Use this method to get up-to-date information about the chat. Returns a :class:aiogram.types.chat_full_info.ChatFullInfo object on success. __returning__ ChatFullInfo __api_method__ getChat chat_id: ChatIdUnion Unique identifier for the target chat or username of the target supergroup or channel in the format :code:username在异步调用链上bot.get_chat(chat_id...)会向 Telegram Bot API 发出getChat请求返回的 JSON 经 pydantic 校验后构建为ChatFullInfo实例其business_opening_hours字段即被解析为BusinessOpeningHours对象。仓库测试 tests/test_api/test_methods/test_get_chat.py 验证了这一调用约定class TestGetChat: async def test_bot_method(self, bot: MockedBot): prepare_result bot.add_result_for( GetChat, okTrue, resultChatFullInfo( id-42, typechannel, titlechat, accent_color_id0, max_reaction_count0, accepted_gift_typesAcceptedGiftTypes(...), ), ) response: ChatFullInfo await bot.get_chat(chat_id-42) bot.get_request() assert response prepare_result.result需要特别说明的是版本差异旧版 aiogram 中Chat类型aiogram/types/chat.py#L122-L128也曾包含business_opening_hours字段但自 Telegram Bot API 7.3 起已被标记为deprecated注释中注明Returned only in getChat并指向 API 变更日志。当前版本应统一从ChatFullInfogetChat的返回类型中读取该字段。五、实战从 getChat 响应中解析并展示营业时间以下代码展示了完整的端到端用法调用getChat、判空、将分钟序号还原为星期几 时刻格式。基于仓库中 BusinessOpeningHours 与 BusinessOpeningHoursInterval 的类型定义可以直接访问hours.time_zone_name与interval.opening_minute/interval.closing_minuteimport asyncio from datetime import datetime, timedelta from aiogram import Bot, Dispatcher WEEKDAYS [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday] def fmt_minute(minute: int) - str: Convert week-minute sequence number (Monday 00:00 based) to Weekday HH:MM. day_idx, rem divmod(minute, 1440) hour, m divmod(rem, 60) return f{WEEKDAYS[day_idx % 7]} {hour:02d}:{m:02d} async def show_opening_hours(bot: Bot, chat_id: int) - None: chat: ChatFullInfo await bot.get_chat(chat_idchat_id) hours chat.business_opening_hours if hours is None: print(fChat {chat_id} has no business opening hours configured.) return print(fTime zone: {hours.time_zone_name}) for interval in hours.opening_hours: print(f {fmt_minute(interval.opening_minute)} - {fmt_minute(interval.closing_minute)}) async def main() - None: bot Bot(tokenBOT_TOKEN) dp Dispatcher() await show_opening_hours(bot, chat_id123456789) # a business account chat id await bot.session.close() if __name__ __main__: asyncio.run(main())关于跨周区间的处理由于closing_minute允许取到11520即下一周周一的 00:00 之前对于类似周日至周一凌晨 02:00 关门的排班closing_minute会大于10080。上面的fmt_minute通过day_idx % 7取模可将超出的序号正确折叠回一周内的星期名称避免出现第 8 天这类非法输出。在实际业务中还应结合time_zone_name做时区确认确保换算的是企业所在时区的本地时间。直接构造对象的场景除了从getChat响应中解析开发者在编写测试或构建演示数据时也可以直接用关键字参数构造BusinessOpeningHours其__init__签名由 butcher 自动生成仅用于类型检查与 IDE 提示如下BusinessOpeningHours( time_zone_nameEurope/Moscow, opening_hours[ BusinessOpeningHoursInterval(opening_minute540, closing_minute1020), BusinessOpeningHoursInterval(opening_minute6300, closing_minute6780), ], )由于 TelegramObject 基于 pydantic 并配置了extraallow、validate_assignmentTrue与frozenTrue字段赋值会经过校验且实例不可变反序列化时未知的额外字段会被宽容保留这保证了与 Telegram API 新字段的前向兼容。六、模块导出与文档索引BusinessOpeningHours与BusinessOpeningHoursInterval已从 aiogram/types/init.py 中公开导出因此可以直接使用from aiogram.types import BusinessOpeningHours, BusinessOpeningHoursInterval两份 API 文档页面均以automodule指令渲染源码 docstringbusiness_opening_hours.rst、business_opening_hours_interval.rst并已登记在 docs/api/types/index.rst 的类型索引中读者可在官方文档站点的 Types 目录下直接查阅这两类的最新字段说明。七、要点小结BusinessOpeningHours由time_zone_nameIANA 时区标识与opening_hours区间列表两个必填字段构成仅出现在企业账号的私聊信息中区间时刻一律使用周一 00:00 起算的分钟序号编码opening_minute范围0–10080closing_minute范围0–11520换算公式为weekday_index × 1440 hour × 60 minute该对象只能通过getChat返回ChatFullInfo获取旧版Chat中的同名字段已废弃读取前务必判空解读时务必结合time_zone_name对应的时区并注意跨周区间的分钟序号会超过10080。相关源码与测试BusinessOpeningHours 源码、BusinessOpeningHoursInterval 源码、ChatFullInfo 字段定义、GetChat 方法、get_chat 测试用例。赞分享后端即时通讯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 实战指南使用 setBusinessAccountProfilePhoto 管理企业账号头像aiogram 实战指南使用 setBusinessAccountProfilePhoto 管理企业账号头像 导读 本文围绕 aiogram 中 setBus后端即时通讯API设计aiogram 中 setBusinessAccountUsername 方法详解修改托管企业账号用户名的完整实战指南aiogram 中 setBusinessAccountUsername 方法详解修改托管企业账号用户名的完整实战指南 导读 setBusinessAccou后端即时通讯API设计aiogram deleteStory 方法详解删除企业账号 Story 的三种调用方式与底层实现aiogram deleteStory 方法详解删除企业账号 Story 的三种调用方式与底层实现 deleteStory 是 Telegram Bot AP后端即时通讯API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考