Интеграция
Confluence и содержимое, которое от вас прячут макросы
Интеграция с Confluence читает пространства и страницы в Telegram-бота, обычно как корпус для ИИ-ассистента. Проблема извлечения — макросы: в исходнике страницы вместо отображаемого содержимого лежат заглушки макросов, поэтому наивное извлечение молча теряет всё, что они отрисовывают.
Confluence — интеграция: доступ, лимиты и доступность
- Модель авторизации
- Базовая аутентификация
- Формат хранения
- Формат хранения Confluence — макросы лежат заглушками, а не отрисованным выводом
- Доступность в Заливе
- Поддерживается Cloud; у Data Center другой набор API
- Поток данных
- 5 узлов, через воркер
As of 2025-10-01, Telegram Bot API 13.4
Зачем нужна эта интеграция
В Confluence документацию держат сложившиеся команды разработки и эксплуатации, и корпус, собранный оттуда, обычно качественнее собранного с общего диска: у страниц есть владельцы, структура и, как правило, хоть какое-то ревью. Для ассистента, отвечающего на внутренние вопросы, это часто лучший материал, какой вообще есть в организации.
Деталь извлечения, которая решает всё, — формат. Confluence хранит страницы в собственном формате хранения, XML-подобном представлении, где макросы лежат заглушками. Страница, показывающая таблицу переменных окружения, может хранить только ссылку на макрос и больше ничего, поэтому извлечение формата хранения даёт документ, в котором нет ровно того конкретного фактического содержимого, ради которого ассистент и полезен.
Альтернатива — отрисованный вид: он раскрывает макросы и выдаёт то, что люди действительно видят, ценой дополнительного запроса на страницу и большего объёма HTML, который надо вычистить. Для корпуса ассистента отрисованный вид почти всегда правильный выбор, потому что вся ценность в том, чтобы отвечать по написанному, а не по тому, что случайно оказалось сохранено прямо в тексте.
Как на самом деле движутся данные
Токен API в паре с адресом почты владельца учётной записи по базовой HTTP-аутентификации для Confluence Cloud, хранится как секрет воркера. Токен наследует права этой учётной записи на пространства, поэтому токен ограниченного аккаунта даёт корпус с дырами, которые выглядят как отсутствующая документация, а не как отсутствующий доступ.
Модель доступа: HTTP Basic
Их лимиты и что они означают для вас
Страницы хранятся в формате хранения Confluence, где макросы представлены заглушками, а не своим выводом.
Вместо него запрашивается отрисованный вид. Извлечение формата хранения теряет ровно то табличное, фактическое содержимое, о котором ассистента чаще всего и спрашивают.
Доступ через API наследует права на пространства у той учётной записи, от имени которой он идёт.
Ограниченный аккаунт даёт корпус с невидимыми дырами. Отчёт о загрузке перечисляет те пространства, которые действительно были видны, — так пробел превращается в задачу по правам доступа, а не в загадку.
Лимиты частоты применяются к учётной записи и различаются в зависимости от тарифа Confluence Cloud.
Полная загрузка идёт с выдержкой и инкрементально. Запрос отрисованного вида на каждую страницу удваивает число запросов по сравнению с форматом хранения, и на объёме это заметно.
Архивные страницы остаются доступными через API.
Если их загрузить, получится ассистент, отвечающий по документации, которую кто-то сознательно вывел из обращения. Архивное содержимое исключается явно, а не в расчёте на то, что до него не дотянутся.
Как это ломается и что происходит потом
Ассистент отвечает без той таблицы, которая была на странице.
Извлекался формат хранения, а не отрисованный вид. Это определяющий баг извлечения из Confluence, и он ухудшает ответы, а не ломает работу, — поэтому и живёт так долго.
Ассистент отвечает по странице, которую три года никто не трогал.
Архивные и устаревшие страницы исключаются, а каждый фрагмент несёт дату последнего изменения своей страницы, чтобы ответ по старому материалу можно было пометить как таковой.
Из корпуса выпало целое пространство.
Пробел в правах у интеграционной учётной записи. Отчёт о загрузке называет то, что было доступно, и превращает это в конкретный запрос вместо общей жалобы.
Загрузка идёт долго и упирается в лимит частоты.
Инкрементальная синхронизация по датам последнего изменения, с выдержкой под лимит. Полная перезагрузка — сознательная операция, а не ночное умолчание.
Доступность в ОАЭ и остальных странах Залива
Confluence Cloud
Тот случай, под который всё и рассчитано, со стабильным REST API и авторизацией по токену.
Confluence Data Center
Разворачивается у вас, с другим набором API и с сетевой доступностью, которую надо организовать. Возможно, но это отдельный разговор про объём работ.
Размещение данных
Atlassian предлагает региональное размещение данных на части тарифов. Построение эмбеддингов в другом месте — это отдельное перемещение данных, о котором стоит говорить прямо.
Пространства с разной степенью чувствительности
Одна интеграционная учётная запись либо видит пространство, либо нет. Там, где ассистент должен отвечать по-разному разным аудиториям, это вопрос архитектуры, а не прав доступа.
Когда эту интеграцию делать не нужно
- Ваш Confluence по большей части заброшен. Ассистент, отвечающий по протухшим страницам, хуже того, который честно говорит, что не знает.
- На практике документация живёт в другом месте. Интегрируйтесь туда, где люди действительно пишут, а не туда, где вики задумывалась.
- Разные аудитории должны получать разные ответы по одному и тому же пространству. Одна интеграционная учётная запись этого выразить не может.
- У вас Data Center и нет маршрута до него из воркера. Это разговор про сеть до того, как он станет разговором про интеграцию.
На чём это работает
| Компонент | Версия | Зачем |
|---|---|---|
| Cloudflare Workers | current | Загрузка с выдержкой, извлечение отрисованного вида и нарезка на фрагменты. |
| Cloudflare Vectorize | current | Векторный индекс с источником страницы и датой последнего изменения. |
| Cloudflare D1 | current | Курсоры синхронизации, опись пространств и отчёты о загрузке. |
| Zod | 4.4 | Валидация ответов API по эндпоинтам страниц и пространств. |
Вопросы, которые возникают при оценке
Почему ассистент не видит таблиц, которые явно есть на странице?
Потому что извлекался формат хранения, а не отрисованный вид. В формате хранения макросы представлены заглушками, поэтому теряется ровно то табличное фактическое содержимое, о котором люди и спрашивают. Работу это не ломает, а только ухудшает ответы, — оттого и остаётся незамеченным так долго.
Почему из корпуса пропало целое пространство?
Интеграционная учётная запись его не видит. Доступ через API наследует права этой записи на пространства, а отчёт о загрузке называет то, что было доступно, — так это становится конкретным запросом по правам, а не расплывчатой претензией к ассистенту.
Стоит ли включать архивные страницы?
Нет, и через API они остаются доступными, поэтому их исключение — сознательный шаг. Ассистент, отвечающий по документации, которую кто-то специально вывел из обращения, хуже ассистента с корпусом поменьше.
Что делать с документацией, которая просто устарела?
Каждый фрагмент несёт дату последнего изменения своей страницы, поэтому ответ по старому материалу можно пометить как таковой. Протухшую документацию это не чинит, но мешает ассистенту подавать её с незаслуженной уверенностью.
Чем это отличается от Notion в роли корпуса?
Блочное дерево у Notion даёт более чистые границы фрагментов; у страниц Confluence обычно понятнее владелец и ревью. Лучший корпус — тот, который ваша команда реально поддерживает в актуальном состоянии, а это вопрос про вашу организацию, а не про инструменты.
Сколько времени занимает первичная загрузка?
Дольше, чем заняла бы на формате хранения, потому что отрисованный вид — это дополнительный запрос на каждую страницу. Инкрементальная синхронизация по датам последнего изменения оставляет дальнейшую стоимость пропорциональной изменениям, а не размеру всей вики.
Что почитать дальше
Если документация команды живёт в Notion, эквивалентным корпусом будет интеграция с Notion.
Продукт, который питается этим корпусом, — ИИ-ассистент на базе знаний.
Там, где документация — это библиотека файлов, смотрите интеграцию с SharePoint.
Решённые обращения в поддержку — второй корпус, который стоит рассмотреть; за него отвечает интеграцию с Zendesk.