Интеграция
Календари Microsoft 365 через Graph и без ловушки часовых поясов
Microsoft Graph позволяет Telegram-боту записи читать занятость и создавать приёмы в календарях Outlook по всему тенанту Microsoft 365. Обычно требуется согласие администратора, троттлинг агрессивен и подробно нигде не описан, а обращение Graph с часовыми поясами порождает больше ошибочных записей, чем любая другая отдельная причина.
Outlook Calendar — интеграция: доступ, лимиты и доступность
- Модель доступа
- OAuth 2.0
- Троттлинг
- На приложение и на почтовый ящик; 429 с заголовком Retry-After
- Доступность в Заливе
- У самого Graph ограничений нет; решает политика тенанта
- Поток данных
- 5 переходов, всё через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
Профессиональные сервисные фирмы, клиники в составе крупных групп и вообще все, у кого есть собственный отдел ИТ, чаще сидят на Microsoft 365, а не на Google. Задача с календарём та же самая — персонал уже живёт в нём, поэтому бот с собственным графиком порождает вторую версию правды, — но окружающая механика отличается существенно, и именно на этих отличиях проекты теряют время.
Первое отличие — согласие. Google нередко позволяет человеку самому выдать доступ к собственному календарю; тенанты Microsoft обычно настроены так, что права уровня приложения требует утвердить администратор, а администратор — это отдел ИТ со своим процессом изменений. Это зависимость в календарном плане проекта, а не шаг, который разработчик закрывает сам, и обратное отношение к ней превращает трёхнедельную работу в семинедельную.
Второе отличие — время. Graph возвращает и принимает дату со временем с явно указанным часовым поясом, причём у тенанта, у почтового ящика и у самого запроса пояс может быть разный. Классический симптом — запись, которая полгода уезжает на час, и она легко переживает тестирование, потому что все тестирующие сидят в одном поясе в одну половину года. Поэтому каждая дата со временем, пересекающая эту границу, несёт свой пояс явно и проверяется в тестах против пояса с переходом на летнее время: в Заливе перехода нет, и локальный тест такую ошибку просто не увидит.
Как на самом деле движутся данные
Graph работает по OAuth 2.0, и для компании правильная форма — права уровня приложения с согласием администратора, а не делегированный доступ от имени конкретного пользователя. Права приложения принадлежат тенанту и переживают кадровые перемены; делегированный доступ принадлежит тому, кто вошёл, и исчезает вместе с ним. Токены кэшируются в воркере и обновляются до истечения срока.
Модель доступа: OAuth 2.0
Их лимиты и что они означают для вас
Graph ограничивает частоту обращений на приложение и на почтовый ящик, отвечая кодом 429 и заголовком Retry-After.
Значение из Retry-After соблюдается, а не подменяется собственной паузой. Microsoft описывает пороги лишь в общих чертах, поэтому заголовок остаётся единственным надёжным сигналом о том, сколько ждать.
Подписки на уведомления об изменениях истекают за считаные дни и требуют продления.
Продление идёт по расписанию сильно заранее, а неудача поднимает оповещение. Протухшая подписка означает, что бот перестал видеть ручные правки календаря, и это молча вырождается в неверную доступность.
Дата со временем несёт явный часовой пояс, и пояса тенанта, почтового ящика и запроса могут различаться все три.
Каждая дата со временем, пересекающая границу интеграции, явно указывает свой пояс. Это самая частая причина приёмов, записанных на час не туда, и в тестировании она прячется отлично.
Права уровня приложения на календари в большинстве конфигураций тенанта требуют согласия администратора.
Это зависимость от чужого процесса изменений. Ей место в плане отдельным пунктом со сроком, а не в списке задач, которые разработчик отмечает галочкой.
Как это ломается и что происходит потом
Часть года записи оказываются на час раньше или позже нужного.
Почти всегда это допущение о часовом поясе. Тесты проверяются против пояса с переходом на летнее время, потому что в Заливе перехода нет и любой локальный тест пропустит ошибку.
Ответ 429 повторяется немедленно, и приложение троттлят ещё жёстче.
Retry-After соблюдается. Игнорировать его — значит усилить ограничение, и бот, который агрессивно повторяет запросы, выводит себя из строя заметно дольше, чем длился исходный лимит.
Подписка на уведомления об изменениях истекает, и никто этого не замечает.
Доступность расходится с реальностью, при этом нигде не возникает ошибки. Поэтому неудачное продление шлёт оповещение: отказ здесь тихий и медленный, а не громкий.
Согласие администратора отзывается при изменении политики тенанта.
Все календарные операции падают разом. Об этом немедленно сообщают персоналу, а не уходят в повторы: отозванное разрешение никакими повторами не возвращается.
Доступность в ОАЭ и остальных странах Залива
Весь мир
У самого Graph региональных ограничений нет. Реальные ворота — политика тенанта, которую задаёт ваш собственный отдел ИТ.
Бизнес-тенанты Microsoft 365
Тот случай, ради которого всё и делается. Права уровня приложения с согласием администратора — правильная схема, и она переживает смену персонала.
Личные аккаунты Outlook
Возможны через делегированные права и заметно более хрупки, поскольку доступ принадлежит человеку, а не организации.
Тенанты с политиками условного доступа
Обычное дело в регулируемых организациях Залива, и такие политики способны полностью закрыть доступ приложениям. Проверяйте это с ИТ до оценки объёма работ, а не во время разработки.
Когда эту интеграцию делать не нужно
- Ваш отдел ИТ не даст согласия администратора. Без него работоспособной интеграции просто нет, и выяснить это стоит в первом же разговоре.
- Политики условного доступа блокируют права уровня приложения. В регулируемых организациях это частый случай и жёсткий стоп, а не повод искать обход.
- Персонал живёт в Google Calendar, хотя организация сидит на Microsoft. Интегрироваться надо с тем календарём, которым люди действительно пользуются.
- Вам нужен продукт для управления расписанием, а не средство записи в календарь. Graph двигает события, но правил бронирования в себе не держит.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Обращения к Graph, кэш токенов и продление подписок по расписанию. |
| Cloudflare D1 | current | Брони, записи и отслеживание срока жизни подписок. |
| Cloudflare KV | current | Общий на все вызовы кэш токена доступа. |
| Zod | 4.4 | Проверка ответов Graph и уведомлений об изменениях. |
Вопросы, которые возникают при оценке
Почему записи уезжают ровно на час?
Практически всегда это допущение о часовом поясе. Graph несёт явный пояс на каждой дате со временем, а у тенанта, почтового ящика и запроса он может отличаться. В тестировании это прячется, потому что все тестируют в одном поясе и в одну половину года.
Нужно ли подключать наш отдел ИТ?
Да, ради согласия администратора, и это зависимость в плане, а не задача разработчика. Начатый до заказа разработки разговор с ИТ экономит больше времени, чем любое техническое решение внутри проекта.
Как правильно обрабатывать троттлинг?
Соблюдая заголовок Retry-After, а не подставляя собственную паузу. Microsoft описывает пороги лишь приблизительно, поэтому заголовок — единственный надёжный сигнал, а повтор запроса сквозь 429 только усиливает ограничение.
Читает ли бот содержимое календарей сотрудников?
Нет. Доступность считается через getSchedule, который возвращает свободные и занятые интервалы без содержания событий. Это и дешевле, и гораздо легче обосновать отделу ИТ, который рассматривает запрос на права.
Что происходит, если подписка на уведомления протухла?
Бот перестаёт видеть ручные правки, доступность расходится с реальностью, и при этом нигде ничего не падает. Продление запускается сильно раньше срока, а его неудача шлёт оповещение — именно потому, что сам отказ беззвучный.
Можно ли поддержать в одном боте календари Google и Microsoft сразу?
Да, за общим интерфейсом доступности, и для группы со смешанными практиками это обычное требование. Специфичной для каждого поставщика остаётся работа с часовыми поясами и с троттлингом — вот это не обобщается.
Что почитать дальше
Если компания работает на Google Workspace, то ей соответствует страница про интеграцию с Google Calendar.
Проектам на Microsoft 365 почти всегда нужно ещё и хранилище документов, поэтому посмотрите интеграцию с SharePoint.
Бот, ради которого эта интеграция и существует, — это разбор бота записи.
Остальные сборки, которые пишут в корпоративный календарь, перечисляет каталог с ценами.