Документация по REST API и Python API
Краткий обзор
- Найдите адрес API своего развертывания, создайте токены доступа и настройте аутентификацию запросов.
- Настройте пакет Python для работы с API и изучите эндпоинты для получения и изменения объектов.
- Фильтруйте результаты по проекту и узнайте, в каких случаях использовать 'clean_text' или 'clean_html'.
На этой странице представлена справочная информация по REST API Requirements Portal. С помощью REST API можно получать и изменять данные в Requirements Portal, а также записывать данные обратно в Requirements Portal, обновляя информацию. Кроме того, API позволяет подключать и интегрировать другие приложения.
Доступ к REST API в Requirements Portal с помощью токенов
Для доступа к REST API в Requirements Portal можно создать токены на странице Settings – User Tokens (для перехода на нее нажмите значок
в правом верхнем углу, выберите Settings в появившемся меню, затем выберите User Tokens в списке на левой панели). На этой странице указан API address для вашего развертывания. Этот адрес необходим для выполнения вызовов API.
Нажмите значок + в правом нижнем углу страницы Settings – User Tokens, чтобы создать новый токен. Каждый токен действителен в течение 3 months; после истечения срока действия необходимо создать новый токен.
Для работы с API с использованием access_token необходимо добавить токен в формате "Bearer ..." в заголовок HTTP-запроса Authorization, указав тип содержимого "JSON".
curl --location 'http://deployment_name/rest/requirements/versions/search/' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer hO2lwhLZsYOgXPNVI' \
--data '{
"size": 10,
"query_filters": {
"object_id": 93
}
}'
Или, используя requests, можно передать токен доступа следующим образом:
access_token = 'Generated_Access_token'
api_url = 'Api_Address'
# workspace id and component type
workspace_id = 1
component_type_name = "CompA"
# Define headers with the access token
headers = {
'Authorization': f'Bearer {access_token}',
'Content-Type': 'application/json', # Adjust content type as needed
}
# Make a GET request (you can use other HTTP methods like POST, PUT, etc.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)
Документация по Python API
Python API позволяет получать доступ к объектам в вашем развертывании и обновлять их с помощью кода Python.
Установите необходимый пакет Python API с помощью pip:
pip install valispace
Импортируйте модуль API в скрипте Python:
import valispace
и выполните инициализацию:
valispace = valispace.API()
Дополнительную информацию о возможностях и функциях API можно найти здесь. Пакет Python API распространяется по лицензии MIT, поэтому любой желающий может внести свой вклад в код, клонировав репозиторий GitHub.
Конечные точки
Пользователи могут получить доступ к конечным точкам на странице Swagger. Чтобы открыть эту страницу, добавьте swagger/ в конец URL-адреса API, указанного на странице Settings – User Tokens. Откроется страница Django Swagger со всеми существующими конечными точками.
Доступны методы GET, POST, PUT, PATCH и DELETE.
Каждый объект в Requirements Portal имеет собственный идентификатор. Его можно использовать для поиска объекта и получения информации о нем. Идентификатор объекта можно увидеть непосредственно в Requirements Portal или в URL-адресе при нажатии на объект в Requirements Portal.
Например, если вы используете метод GET для получения истории требования через Swagger, сведения об истории требования можно получить с помощью следующей конечной точки.
GET /rest/requirements/{requirement-id}/history/

Получение истории требования с помощью GET
Аналогичным образом можно использовать методы для получения, обновления или добавления различных объектов, таких как блоки, теги, valis, textvalis, требования, спецификации, методы верификации и т. д. Найти нужные конечные точки можно на странице Swagger.
Фильтрация объектов по проектам
Помимо аутентификации, API позволяет использовать метод GET для получения объектов, таких как Valis или требования, в рамках развертывания. Если необходимо отфильтровать результаты по определенному проекту, можно воспользоваться возможностями фильтрации при условии, что конечная точка настроена соответствующим образом. Например, для получения требований, связанных с проектом 24, можно использовать следующий GET-запрос:
GET /rest/requirements/?project=24
Для наглядности эта возможность показана в видео ниже.
Встроенные функции
Когда пользователь вводит текст в текстовое поле в Requirements Portal, этот текст сохраняется на сервере в формате HTML. Формат HTML сохраняет форматирование и ссылки на valis или другие объекты. Поэтому при получении информации о требованиях импортируемые данные могут содержать текст в формате HTML. Чтобы избежать этого, мы реализовали две функции, позволяющие преобразовывать HTML-поля в обычный текст или сохранять HTML-форматирование, преобразуя valis в текст. Это функции clean_text и clean_html.
Функция clean_text
Функция clean_text преобразует HTML-разметку и ссылки на объекты внутри поля в обычный текст. При этом форматирование также теряется. Например, не сохраняется оформление списков, таблиц и цвета. Ниже показан пример использования этой функции.
Здесь мы фильтруем данные по проекту 24 и запрашиваем обычный текст для полей текста и обоснования требования. Результат этого действия будет следующим.
Требования после применения функции clean_textФункция clean_html
Функция clean_html сохраняет форматирование текста, но преобразует ссылки и объекты, например valis, в текст. Если текст содержит такие элементы форматирования, как списки, цвет фона, таблицы и т. д., эта информация сохраняется.
Требования после применения функции clean_html
Часто задаваемые вопросы
Как найти нужную конечную точку?
Среди множества конечных точек с похожими названиями бывает непросто найти нужную. Если у вас возникли сомнения по поводу конкретной конечной точки, рекомендуем обратиться за разъяснениями на страницу поддержки Altium. Также можно воспользоваться вкладкой «Сеть» в инструментах разработчика браузера, чтобы увидеть, какие конечные точки вызываются при выполнении действий в пользовательском интерфейсе приложения.
В качестве примера рассмотрим создание блока. В этом случае соответствующую конечную точку можно определить по запросу "POST" к "/rest/components". Эту информацию легко найти, просматривая сетевую активность во время выполнения действия. Краткая демонстрация этого подхода приведена в видео ниже.


