При реализации бота поддержки часто требуется обеспечить поиск информации по базе знаний. Типовой бот Confluence Connector на платформе Sherlock Platform реализует интеграцию для поиска информации в wiki-системе Confluence. Ниже приведено описание логики работы данного бота.
Авторизация в Confluence
Для подключения бота необходимо создать аккаунт для доступа к Confluence (домен на портале Confluence или собственный Confluence Server), и разместить в этом пространстве необходимые вам публикации или справочные материалы.
Работа бота с Confluence осуществляется с помощью Confluence REST API. Для доступа к API требует получения токена авторизации. Получить токен API можно по ссылке: https://id.atlassian.com/manage/api-tokens.
Для создания токена необходимо указать его имя:
После ввода имени будет выдан токен. Его нужно обязательно скопировать, так как дальнейший просмотр будет недоступен. В последствии возможно будет только отозвать токен.
Поиск по ключевому слову
Для поиска в Confluence по ключевым словам необходимо выполнить Get запрос
curl --request GET \
--url 'https://your-domain.atlassian.net/wiki/rest/api/search?cql=title~"Keywords" \
--user '[email protected]:<api_token>' \
--header 'Accept: application/json'
В данном запросе необходимо указать:
- your-domain.atlassian.net – адрес домена или самостоятельного сервера на котором располагаются опубликованные материалы;
- search?cql=title – режим поиска (title – в заголовках, text – по тексту публикации, space.title – по заголовкам в определенном тематическом разделе;
- Keywords – непосредственно ключевые слова для поиска;
Также необходимо указать имя учетной записи email@example.com и полученный ранее API токен.
Помимо поиска статей по ключевым словам на основе API возможно получение информации по другим признакам опубликованных материалов. Подробно эти возможности рассмотрены в документации https://docs.atlassian.com/atlassian-confluence/REST/6.6.0/ и https://developer.atlassian.com/server/confluence/advanced-searching-using-cql/
Настройка интеграции в Sherlock Platform
Настройка внешнего сервера
Для обращения к материалам, опубликованным на платформе Confluence, в Sherlock Platform необходимо настроить внешний сервер:
При настройке необходимо указать:
- Имя сервера, например Confluence$
- Тип сервера – URL;
- Тип авторизации: Basic Authorization (REST API Confluence используется базовый тип авторизации). В качестве логина указываем имя учетной записи в Confluence, в качестве пароля - API токен.
Работа с API
Настраиваем команду «Внешний запрос»:
Необходимо указать:
- Имя команды, например «Поиск в Confluence»;
- Выбрать тип запроса – REST запрос (JSON data);
- Подключение к внешнему источнику – выбираем сконфигурированный на прошлом этапе сервер (Confluence);
- Указываем путь – для поиска по ключевым словам: /rest/api/search?cql=title~"#ClientRecq#", где ClientRecq – ключевые слова, которые можно указать как в форме переменной контекста, так и в явной форме константы.
- Выбираем метод запроса – GET.
Результат запроса – это JSON, структура которого приведена ниже:
{
"results": [
{
"content": {
"id": "229377",
"type": "page",
"status": "current",
"title": "Page 1",
"childTypes": {},
"macroRenderedOutput": {},
"restrictions": {},
"_expandable": {
"container": "",
"metadata": "",
"extensions": "",
"operations": "",
"children": "",
"history": "/rest/api/content/229377/history",
"ancestors": "",
"body": "",
"version": "",
"descendants": "",
"space": "/rest/api/space/NT"
},
"_links": {
"webui": "/spaces/NT/pages/229377/Page+1",
"self": "https://testsherlock.atlassian.net/wiki/rest/api/content/229377",
"tinyui": "/x/AYAD"
}
},
"title": "@@@hl@@@Page@@@endhl@@@ 1",
"excerpt": "test\n\ntest\n\ntest",
"url": "/spaces/NT/pages/229377/Page+1",
"resultGlobalContainer": {
"title": "New test",
"displayUrl": "/spaces/NT"
},
"breadcrumbs": [],
"entityType": "content",
"iconCssClass": "aui-iconfont-page-default",
"lastModified": "2019-07-12T08:20:28.442Z",
"friendlyLastModified": "Jul 12, 2019",
"score": 11.319031
},
{
"content": {
"id": "393217",
"type": "page",
"status": "current",
"title": "Page 2",
"childTypes": {},
"macroRenderedOutput": {},
"restrictions": {},
"_expandable": {
"container": "",
"metadata": "",
"extensions": "",
"operations": "",
"children": "",
"history": "/rest/api/content/393217/history",
"ancestors": "",
"body": "",
"version": "",
"descendants": "",
"space": "/rest/api/space/NT"
},
"_links": {
"webui": "/spaces/NT/pages/393217/Page+2",
"self": "https://testsherlock.atlassian.net/wiki/rest/api/content/393217",
"tinyui": "/x/AQAG"
}
},
"title": "@@@hl@@@Page@@@endhl@@@ 2",
"excerpt": "new test content",
"url": "/spaces/NT/pages/393217/Page+2",
"resultGlobalContainer": {
"title": "New test",
"displayUrl": "/spaces/NT"
},
"breadcrumbs": [],
"entityType": "content",
"iconCssClass": "aui-iconfont-page-default",
"lastModified": "2019-07-12T08:21:47.904Z",
"friendlyLastModified": "Jul 12, 2019",
"score": 11.319031
}
],
"start": 0,
"limit": 25,
"size": 2,
"totalSize": 2,
"cqlQuery": "title~\"Page\"",
"searchDuration": 48,
"_links": {
"base": "https://testsherlock.atlassian.net/wiki",
"context": "/wiki"
}
}
Из JSON ответа нам необходимо:
$..content.title – название страниц, найденных по ключевым словам;
$..base+$..content._links.webui – полный URL найденной страницы;
$..excerpt – краткое содержание страницы (55 первых слов).