Я использую Confluence чуть более двух лет, и, хотя у него есть недостатки, он неплохо помогает мне в организации контента. Он также предоставляет хороший API, который позволяет мне делать то, что программное обеспечение не может делать изначально.
Одна из вещей, которыми я занимаюсь, - это создание множества похожего контента. Я часто использую свойства страницы, и у меня есть таблица свойств страницы для отслеживания различных атрибутов документа.
Для создания и обновления этих страниц я использую почтальон. Почтальон - это отсутствующий инструмент в традиционном пакете офисных приложений. Если вы можете создать электронную таблицу в таблицах Google, вы можете использовать почтальон.
По мере того, как я продолжаю создавать нашу программу безопасности, я хочу сопоставить элементы управления с конкретными фреймворками. В этой статье основное внимание уделяется загрузке в Confluence страниц, которые представляют собой элементы управления согласно Приложению A ISO27001. Я использовал электронную таблицу здесь для создания страниц Confluence.
Настроить Atlassian
Получить токен API для Confluence довольно просто. Выполните следующие действия, чтобы создать токен.
- Перейдите сюда
- Нажмите «Создать токен API».
- Назовите токен (я обычно называю его датой создания)
- Скопируйте токен в безопасное место.
Я использую Lastpass для хранения токена для последующего извлечения. Когда у вас есть токен, вам нужно настроить почтальон.
Настройка почтальона
Если у вас не установлен Почтальон, начните с посещения сайта Почтальон и скачайте последнюю версию. После того, как у вас установлен почтальон, рекомендую создать среду.
Я назвал свою среду Jira, но имя произвольное. Кроме того, я выбрал имена jira_user и jira_token, но они тоже произвольны. Jira_token - это токен, полученный вами на предыдущих шагах. Наконец, я рекомендую вам создать jira_host, который представляет ваш экземпляр Confluence. Confluence API использует базовую аутентификацию, поэтому настройте ее в Postman ниже. После того, как вы создали среду, вам нужно проверить свои учетные данные.
Учетные данные для тестирования
Теперь, когда у вас есть учетные данные в среде, вы можете протестировать доступ к API, запросив список ваших пространств.
Почтальон использует двойные угловые скобки для замены значений переменными среды. Таким образом, здесь можно использовать значения, определенные на предыдущем шаге. Вы можете видеть, что в поле с надписью 1 выше я ввел {{jira_user}} и в поле 2 выше я ввел {{jira_token}}. Я также заменил имя хоста в используемом мной тестовом URL на {{jira_host}}. Я выбрал для тестирования космическую конечную точку, но вы можете выбрать любую конечную точку Confluence, которая вам нравится. Обратите внимание, что в качестве типа аутентификации я выбрал Обычная аутентификация. После того, как вы ввели URL-адрес, имя пользователя и токен, нажмите Отправить, и вы должны увидеть статус 200, как в поле 4 выше, и некоторые выходные данные, показанные стрелкой 5.
Распространенными ошибками являются ваши учетные данные, неверное имя пользователя или пароль. Убедитесь, что в вашем токене нет начального или конечного пробела.
Создание страницы-шаблона
Для создания массовых страниц в Confluence я использую стандартную страницу Confluence в качестве шаблона. Хотя я хотел бы использовать шаблон слияния, на момент написания этой статьи не существовало метода api для создания страницы из шаблона. Я потратил время на создание рабочей страницы с данными, которые будут частью страницы, и остановился на следующем макете.
Содержание довольно простое. У меня есть поровну разделенная страница со свойствами страницы слева и несколько элементов метаданных справа, включая предупреждение о том, что страница создается автоматически, оглавление и таблицу цитирования. Наконец, внизу находится JQL-запрос, чтобы показать элементы управления компании, связанные с этим элементом управления. Вот как выглядит страница после рендеринга.
Чтобы завершить работу над этим форматом, потребовалось немного пробной ошибки. Несколько замечаний:
- Запрос JQL для ссылки на элемент управления внизу страницы перекрывает таблицу цитат. Я хотел убедиться, что правильно помечаю элементы управления, поскольку они были задокументированы и реализованы. Моя цель - пометить элементы управления соответствующими элементами управления ISO и показать их на этой странице, чтобы понять охват и пробелы.
- Таблица цитат, вероятно, будет включать больше, чем просто элементы управления, поскольку процессы и процедуры могут также ссылаться на этот элемент управления.
- Имя страницы представляет собой объединение ссылки на элемент управления и имени элемента управления.
- Единственные данные, которые будут меняться на каждой странице, - это данные в таблице свойств страницы, запрос JQL и метки страниц.
В шаблон могут быть внесены дальнейшие изменения на этой странице, а затем страницы могут быть автоматически сгенерированы в соответствии с описанным ниже процессом.
Получите шаблон с помощью почтальона
Теперь, когда у нас есть страница, мы можем увидеть, как она выглядит в формате JSON.
Это конечная точка контента, в частности, мы запрашиваем / wiki / rest / api / content / search со следующими параметрами запроса
- expand = body.storage, metadata.properties, history.nextVersion, version, metadata.labels, space
- cql = title = "A.8.1.3 Допустимое использование активов" и пробел = SEC и type = page
Используйте ту же аутентификацию и имя экземпляра, что и в нашем тесте выше. Этот запрос важен, потому что мы будем использовать фактическое содержание для создания страницы позже с помощью Postman. Вы можете найти фактический контент, если прокрутите вниз в разделе ответов, пока не увидите следующее
посмотрев на атрибут «тело» в разделе «хранилище», а затем «значение», вы можете увидеть фактическое содержимое на этой странице. Это одна полная строчка в ответе. Я скопировал это ниже. Вы можете увидеть, где размещен текст в шаблоне и в различных разделах страницы.
"<ac:layout><ac:layout-section ac:type=\"two_equal\"><ac:layout-cell><h2>Definition</h2><p><br /></p><ac:structured-macro ac:name=\"details\" ac:schema-version=\"1\" ac:macro-id=\"ad531b4d-a4a1-4000-b69e-0e097244798b\"><ac:rich-text-body><p><br /></p><table data-layout=\"default\"><colgroup><col /><col /></colgroup><tbody><tr><th><p><strong>Domain</strong></p></th><td><p>Asset management</p></td></tr><tr><th><p><strong>Sub Domain</strong></p></th><td><p>Responsibility for assets</p></td></tr><tr><th><p><strong>Control Name</strong></p></th><td><p>Acceptable use of assets</p></td></tr><tr><th><p><strong>Control Reference</strong></p></th><td><p>A.8.1.3</p></td></tr><tr><th><p><strong>Control Description</strong></p></th><td><p>Rules for the acceptable use of information and of assets associated with information and information processing facilities shall be identified, documented and implemented.</p></td></tr></tbody></table><p class=\"auto-cursor-target\"><br /></p></ac:rich-text-body></ac:structured-macro><p class=\"auto-cursor-target\"><br /></p></ac:layout-cell><ac:layout-cell><p class=\"auto-cursor-target\"><br /></p><ac:structured-macro ac:name=\"note\" ac:schema-version=\"1\" ac:macro-id=\"19b3a146-341a-472e-bdaa-45febcbd438b\"><ac:rich-text-body><p>This page is auto generated. Changes may be overwritten.</p></ac:rich-text-body></ac:structured-macro><ac:structured-macro ac:name=\"toc\" ac:schema-version=\"1\" ac:macro-id=\"5afbd337-9992-439b-8028-051f4b94eeb0\" /><ac:structured-macro ac:name=\"qc-doc-citation-macro\" ac:schema-version=\"1\" ac:macro-id=\"d6d39a49-f9fa-47f0-b0c5-c01ee4d5ae1f\" /></ac:layout-cell></ac:layout-section><ac:layout-section ac:type=\"single\"><ac:layout-cell><h2>Controls</h2><ac:structured-macro ac:name=\"detailssummary\" ac:schema-version=\"3\" ac:macro-id=\"ffcbafc6-5f99-4374-adca-de476bff6fd1\"><ac:parameter ac:name=\"headings\">Control Requirements, Control Response, Updated</ac:parameter><ac:parameter ac:name=\"cql\">label = "tsc" and label = "A_8_1_3" and space = currentSpace ( )</ac:parameter></ac:structured-macro></ac:layout-cell></ac:layout-section></ac:layout>"
Алгоритм
Теперь, когда я могу получить тело шаблона из Confluence, мне нужно выяснить, как создавать контент. В Confluence API есть метод как для создания, так и для обновления контента. Поскольку я хочу иметь возможность обновлять их в будущем, я хотел убедиться, что могу как создавать контент, так и обновлять его. Ниже приведен алгоритм, который я использовал для создания страниц.
Коллекция почтальона
Я создал коллекцию почтальонов, которая фиксирует этот поток здесь. Большая часть логики заключена в первом поисковом запросе. Вы можете скачать эту коллекцию и импортировать ее в Почтальон.
Первый запрос ищет страницу из итерации почтальона-бегуна. Если он находит страницу с таким именем, он обновляет ее, в противном случае он создает новую страницу.
В поисковом запросе есть сценарий публикации, который выполняет большую часть работы после того, как запрос вернул результаты. Я разделю это на несколько разделов
После определения тестовой функции ответ извлекается из поиска. Переменная «html» - это контент из нашего поиска по шаблону в начале. Следующий раздел проходит по клавишам текущего объекта. Данные итерации - это таблица, приведенная выше. Если вы посмотрите на названия столбцов на этом листе, вы обнаружите, что они соответствуют названиям свойств таблицы. Я использую заголовок таблицы, чтобы найти аналогичное значение в исходном html, если я его найду, я заменяю значение свойств страницы значением из итерации. В противном случае значение игнорируется. Вся цель этого кода - заполнить таблицу в документе Confluence данными из таблицы Google.
В следующем разделе кода обновляется метка в запросе CQL, а затем определяется, нужно ли создать страницу или обновить страницу.
Confluence не допускает точек в ярлыках, поэтому мне пришлось заменить их подчеркиванием. Как только это будет сделано, я заменяю известный ярлык CQL ярлыком страницы. Наконец, я определяю, нужно ли мне создать или обновить страницу. Если я обновляю страницу, мне нужно увеличить ее номер версии и установить идентификатор страницы, которую я собираюсь обновить. Я также установил «setNextRequest» на имя функции обновления в моей коллекции «страница слияния обновлений». В противном случае я «setNextRequest», чтобы «создать страницу слияния». И update, и create требуют тела из html, который мы сгенерировали в начале тестовой функции.
Обе функции POST и PUT довольно просты: они просто создают / обновляют страницу и не обрабатывают ответ.
Почтальон Бегущий
Последний шаг в процессе - создание страниц с помощью Postman Runner. Бегун почтальона в основном позволяет вам перебирать коллекцию. Хотя цель runner - перебрать коллекцию с тестовыми данными для тестирования API, мы будем использовать его для загрузки данных.
Чтобы запустить раннер, нажмите кнопку бегуна в верхнем левом углу окна почтальона. После запуска Collection Runner или Runner найдите коллекцию «Добавить элементы управления ISO». Это изменит отображение и предоставит некоторые дополнительные параметры.
Выберите среду, которую мы установили в начале, загрузите CSV-файл элементов управления в файле googlesheets, затем нажмите «Run Add ISO Cont…».
Это создаст 114 страниц (количество итераций).
Смотреть вперед
Я использовал этот шаблон проектирования в нескольких случаях, когда мне нужно было импортировать или массово создавать страницы в Confluence. Я обнаружил, что API может быть очень требовательным к входным данным, а некоторые ошибки API могут быть очень загадочными. Пара основных наблюдений:
- У почтальона возникла проблема с цитатами в тексте. Не удалось бы отправить данные с правильно экранированными кавычками для текста CSV. Я не могу вспомнить, остается ли это проблемой, но имейте в виду, что данные, которые вы импортируете, могут потребовать некоторой дезинфекции. Сначала сделайте это в таблице Google.
- новые строки, возврат каретки, непечатаемые символы. Все это может вызвать проблемы с импортом. Если у вас возникли проблемы с созданием страниц, проверьте наличие непечатаемых символов.
- Я всегда тестировал с несколькими образцами, прежде чем создавать большое количество страниц. Думаю, что для этого поста я тестировал одну страницу несколько раз, удаляя страницу после каждого теста, затем тестируя 5 страниц, затем еще 5 и т. Д. Страницы легко воссоздать, но удаление 114 страниц может занять много времени. Тестируйте небольшими партиями.
- В более позднем варианте использования я обнаружил, что мое регулярное выражение оказалось не таким точным, как я надеялся. Я опубликую еще одну статью о более качественном регулярном выражении для обновления таблицы свойств страницы.
- Я мог бы лучше справляться с ошибками. Я в основном игнорирую ошибки в коде. Было бы несложно добавить код, останавливающий выполнение в случае сбоя.
- Я использовал похожий шаблон для Jira. Я найду время написать, как это сделать и для Jira.