Документация по REST API и Python API

На этой странице представлена справочная информация по 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 необходимо добавить токен в заголовок Authorization HTTP-запроса в формате «Bearer ...», указав тип приложения «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». Это легко определить, просмотрев сетевую активность во время выполнения действия. Краткая демонстрация этого подхода приведена в видео ниже.