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

Этот документ содержит справочную информацию о REST API портала Requirements & Systems Portal. Используя REST API, пользователи могут получать и изменять данные из Requirements & Systems Portal или даже записывать данные обратно в Requirements & Systems Portal и таким образом обновлять информацию. Кроме того, это дает возможность подключения/интеграции с другими приложениями или программами.

Доступ к Rest API в Requirements & System Portal с помощью токенов

Чтобы получить доступ к REST API в приложении Requirements & Systems Portal на Altium A365, пользователи могут сгенерировать токены, перейдя в Settings меню и выбрав User Tokens. На странице User Tokens на странице настроек вы найдете адрес API для вашего конкретного развертывания. Этот адрес необходим для выполнения вызовов API.

Нажмите на значок “+” значок на странице Токены пользователей, чтобы сгенерировать новый токен. Каждый токен действителен в течение 3 months и должен быть сгенерирован заново после истечения срока его действия.

При использовании API с помощью access_token необходимо добавить токен через "Bearer ..." с использованием типа приложения "JSON" в заголовок HTTP-запроса Authorization.

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
    }
}'

или используя запросы, вы можете отправить токен доступа следующим образом

access_token = 'Generated_Access_token'
api_url = 'Api_Address'

# идентификатор рабочего пространства и тип компонента

идентификатор рабочего пространства = 1
component_type_name = "CompA"

# Определите заголовки с маркером доступа
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json', # Настройте тип содержимого по мере необходимости
}

# Выполните GET-запрос (вы можете использовать другие HTTP-методы, такие как POST, PUT и т. д.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)

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

Python API позволяет вам получать доступ и обновлять объекты в вашем развертывании с помощью кода на языке python.

Установите необходимый пакет python API с помощью pip:

pip install valispace

Импортируйте модуль API в скрипт на python:

import valispace

и инициализируйте с помощью

valispace = valispace.API()

Более подробную информацию о возможностях и функциях API можно найти здесь. Пакет python API лицензирован под лицензией MIT, что означает, что любой может внести свой вклад в код, клонировав репозиторий GitHub.

Конечные точки

Пользователи могут получить доступ к конечным точкам на странице rest. Чтобы получить доступ к странице, добавьте "rest/"в конце URL-адреса API, который можно найти на портале "Требования и системы" в разделе "Настройки" и "Токены пользователей". На странице Rest отображается Django Swagger со всеми существующими конечными точками.

Существуют методы "GET", "POST", "PUT", "PATCH" и "DELETE".

Каждый объект в Requirements & Systems Portal имеет свой собственный ID; вы можете использовать его для поиска и получения информации о самом объекте. Идентификатор объекта можно увидеть либо непосредственно в Requirements & Systems Portal, либо в URL при нажатии на объект в Requirements & Systems Portal.

Например, если вы используете функцию get для получения информации о вали через остаток, вы можете использовать следующую конечную точку для получения информации о вали.

GET /rest/valis/{vali-id}/

Используя GET, получаем информацию о вали

Аналогичным образом вы можете использовать методы для получения/обновления или размещения различных объектов, таких как блоки, теги, вали, текст вали, требования, спецификации, методы проверки и т. д. Вы можете искать конечные точки на странице остального.

Фильтрация объектов для проектов

Помимо аутентификации, вы можете использовать метод "GET" для получения таких объектов, как Valis или Requirements в рамках развертывания. Если вам нужно отфильтровать результаты на основе конкретного проекта, вы можете добиться этого, используя возможности фильтрации, при условии, что конечная точка настроена соответствующим образом. Например, чтобы получить требования, связанные с проектом 24, можно использовать следующий запрос GET:

GET /rest/requirements/?project=24

Для наглядности эта функциональность продемонстрирована в видеоролике ниже.

Встроенные функции

В рамках портала "Требования и системы" каждый раз, когда пользователь набирает текст в текстовом поле, он сохраняется в бэкенде в формате HTML
формате. Формат HTML сохраняет форматирование ссылок на валиды или другие объекты. Поэтому, если вы получаете информацию о требованиях, вы можете получить HTML-текст в импорте. Чтобы избежать этого, мы реализовали две функции, которые могут быть полезны для преобразования HTML-полей в просто текст или HTML-формат с valis, преобразованными в текст. Эти функции - cleanan_text и cleanan_html.

Функция cleanan_text

Функция clean text преобразует все HTML-форматы и ссылки на объекты в поле в текст. Однако в этом случае форматирование также теряется. Например, форматирование также теряется, если в поле есть список, таблицы или цвет. Вы можете использовать эту функцию, как показано ниже.

Здесь я делаю фильтр для проекта 24 и прошу выдать чистый текст для текста и обоснования поля. В результате для этого конкретного действия будет получено следующее.

Требования после использования функции Clean_text

Функция Clean_html

Функция clean_html сохраняет параметры форматирования текста, но затем преобразует ссылки/объекты, такие как valis, в текст. Если текст содержит параметры форматирования, такие как списки, цвет фона, таблицы и т. д., эта информация сохраняется.

Требования после использования функции clean_html

Общие вопросы:

Как найти нужную конечную точку?

Навигация по многочисленным конечным точкам с похожими именами может сбить с толку. Если у вас возникнут сомнения по поводу конкретной конечной точки, мы рекомендуем вам обратиться за разъяснениями на страницу поддержки Altium. Кроме того, вы можете воспользоваться функцией "сеть" вашего браузера, чтобы увидеть, какие конечные точки запускаются при выполнении действий во внешнем интерфейсе программы.

В качестве иллюстрации рассмотрим процесс создания блока. В этом случае связанная с ним конечная точка может быть идентифицирована как запрос "POST" к "/rest/components", и эту информацию можно легко обнаружить, проанализировав сетевую активность во время выполнения действия. Краткая демонстрация этого подхода представлена в коротком видеоролике ниже.

Как получить/разместить методы проверки (VM) и блоки требования?

Требование в Requirements & Systems Portal может быть связано с несколькими методами проверки (VM), каждый из которых, в свою очередь, может иметь несколько блоков, прикрепленных к нему. Поддерживаются различные типы методов проверки, включая правила, испытания, инспекции, анализы, обзоры и пользовательские ВМ. Каждый тип метода проверки однозначно идентифицируется своим собственным идентификатором.

Вы можете использовать соответствующую конечную точку для получения идентификаторов этих типов методов проверки.

GET /rest/requirements/verification-methods/

Например, чтобы получить идентификаторы типов методов верификации для проекта id 24, вы можете использовать следующую конечную точку

GET /rest/requirements/verification-methods/?project=24

Список методов верификации проекта

Для получения методов верификации, связанных с конкретным требованием, портал Requirements & Systems Portal создает специальный объект, известный как "Requirement-VMS" Этот объект имеет свой уникальный идентификатор (ID), доступ к которому можно получить через следующую конечную точку:

GET /rest/requirements/requirement-vms/

Например, данное требование, SPC-002 с идентификатором 2165, имеет один метод проверки типа "Правила", а идентификатор объекта requirment-vms равен 2203.

Если мы используем конечную точку "/rest/requirements/requirement-vms/2203 ", то получим следующий ответ.

Ключи и значения Requirment-vms

Посмотрев на объект "Requirement-vms", вы заметите, что идентификатор метода "20" соответствует методу верификации "Правила", согласно списку типов методов верификации, полученному ранее. При включении этой информации в сценарий убедитесь, что вы сопоставили идентификатор метода с соответствующим типом метода проверки.

Кроме того, в объекте "Requirement-vms" есть ссылки на два компонента-vms. Идентификаторы этих компонент-vm представляют блоки, прикрепленные к методам проверки требований. При программном взаимодействии с этими блоками используйте эти идентификаторы в своем сценарии соответствующим образом.

Конечной точкой доступа к компоненту-vms будет

GET /rest/requirements/component-vms/{id}

Когда вы получаете подробную информацию о компоненте-vms, поля компонента дают вам идентификатор блока, с которым вы можете сопоставить имя блока.

Компонент-vms