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