Dokumentation der Rest API und Python API

Updated: September 30, 2025

Dieses Dokument dient als Referenz für die REST-API des Requirements & Systems Portal. Mithilfe der REST-API können Benutzer Daten aus dem Requirements & Systems Portal abrufen und ändern oder sogar Daten zurück in das Requirements & Systems Portal schreiben und dadurch Informationen aktualisieren. Darüber hinaus bietet dies die Möglichkeit, Verbindungen/Integrationen mit anderen Anwendungen oder Apps herzustellen.

Zugriff auf die Rest API im Requirements & System Portal mithilfe von Tokens

Um auf die REST-API in der Anwendung Requirements & Systems Portal auf Altium A365 zuzugreifen, können Benutzer Tokens generieren, indem sie zum Menü Settings navigieren und User Tokens auswählen. Auf der Einstellungsseite User Tokens finden Sie die API-Adresse für Ihre spezifische Bereitstellung. Diese Adresse ist für API-Aufrufe erforderlich.

Klicken Sie auf der Seite „User Tokens“ auf das Symbol “+”, um ein neues Token zu generieren. Jedes Token ist für 3 months gültig und muss nach Ablauf erneut generiert werden.

Um die API mit dem access_token zu verwenden, muss dem HTTP-Request-Header Authorization ein Token über „Bearer ...“ unter Verwendung des Anwendungstyps „JSON“ hinzugefügt werden.

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

oder mithilfe von requests können Sie das Access Token wie folgt senden

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-Dokumentation

Die Python API ermöglicht Ihnen den Zugriff auf und die Aktualisierung von Objekten in Ihrer Bereitstellung mit Python-Code.

Installieren Sie das erforderliche Python-API-Paket mit pip:

pip install valispace

Importieren Sie das API-Modul in ein Python-Skript:

import valispace

und initialisieren Sie es mit

valispace = valispace.API()

Weitere Informationen zu den Funktionalitäten und Funktionen der API finden Sie hier. Das Python-API-Paket ist unter der MIT-Lizenz lizenziert, was bedeutet, dass jeder durch Klonen des GitHub-Repositorys zum Code beitragen kann.

Endpoints

Benutzer können auf der Rest-Seite auf die Endpoints zugreifen. Um auf die Seite zuzugreifen, fügen Sie „rest/“ am Ende der API-URL hinzu, die Sie im Requirements & Systems Portal unter Settings und „User Tokens“ finden. Die Rest-Seite zeigt Django Swagger mit allen vorhandenen Endpoints an.

Um auf die Rest-Seite zuzugreifen, verwenden Sie „your_API_URL/rest/“. Wenn Sie das „/“ am Ende von rest weglassen, werden Sie nicht auf die Rest-Seite weitergeleitet. Um Ihre API-URL zu erhalten, gehen Sie bitte in den Settings zu „User Tokens“.

Es gibt die Methoden „GET“, „POST“, „PUT“, „PATCH“ und „DELETE“.

Jedes Objekt im Requirements & Systems Portal hat eine eigene ID; Sie können diese verwenden, um nach dem Objekt zu suchen und dessen Informationen abzurufen. Die Objekt-ID ist entweder direkt im Requirements & Systems Portal sichtbar oder in der URL, wenn Sie im Requirements & Systems Portal auf das Objekt klicken.

Wenn Sie beispielsweise die get-Funktion verwenden, um über die Rest-Schnittstelle Vali-Informationen abzurufen, können Sie den folgenden Endpoint verwenden, um die Vali-Details zu erhalten.

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

Ebenso können Sie die Methoden verwenden, um verschiedene Objekte wie Blocks, Tags, Valis, Textvalis, Requirements, Specifications, Verification Methods usw. abzurufen/zu aktualisieren oder zu posten. Sie können auf der Rest-Seite nach den Endpoints suchen.

Objekte für Projekte filtern

Zusätzlich zur Authentifizierung können Sie die Methode „GET“ verwenden, um Objekte wie Valis oder Requirements innerhalb der Bereitstellung abzurufen. Wenn Sie die Ergebnisse anhand eines bestimmten Projekts filtern müssen, können Sie dies mithilfe der Filterfunktionen erreichen, sofern der Endpoint entsprechend konfiguriert ist. Um beispielsweise Requirements abzurufen, die dem Projekt 24 zugeordnet sind, können Sie die folgende GET-Anfrage verwenden:

GET /rest/requirements/?project=24

Diese Funktionalität wird im folgenden Video zur besseren Veranschaulichung demonstriert.

Integrierte Funktionen

Innerhalb des Requirements & Systems Portal wird der Text, den ein Benutzer in das Textfeld eingibt, im Backend im HTML-
Format gespeichert. Das HTML-Format behält die Formatierungsreferenzen auf Valis oder andere Objekte bei. Wenn Sie also Requirement-Informationen abrufen, erhalten Sie in Ihrem Import möglicherweise HTML-Text. Um dies zu vermeiden, haben wir zwei Funktionen implementiert, die nützlich sein können, um die HTML-Felder entweder in reinen Text oder in HTML-Formatierung mit in Text umgewandelten Valis zu konvertieren. Die Funktionen heißen clean_text und clean_html.

Funktion clean_text

Die Funktion clean_text konvertiert alle HTML-Formate und Objektreferenzen innerhalb des Feldes in Text. In diesem Fall geht jedoch auch die Formatierung verloren. Beispielsweise geht die Formatierung auch verloren, wenn Sie eine Liste, Tabellen oder Farbe haben. Sie können dies wie unten gezeigt verwenden.

Hier filtere ich nach Projekt 24 und fordere den bereinigten Text für das Feld text und rationale an. Die Ausgabe würde für diese spezifische Aktion wie folgt aussehen.

Funktion clean_html

Die Funktion clean_html behält die Formatierungsoptionen des Textes bei, konvertiert jedoch Referenzen/Objekte wie Valis in Text. Wenn der Text Formatierungsoptionen wie Listen, Hintergrundfarbe, Tabellen usw. enthält, bleiben diese Informationen erhalten.

Häufige Fragen:

Wie findet man den richtigen Endpoint?

Die Navigation durch zahlreiche Endpoints mit ähnlichen Namen kann verwirrend sein. Wenn Sie sich bei einem bestimmten Endpoint unsicher sind, empfehlen wir Ihnen, unsere Altium Support Page für eine Klärung zu kontaktieren. Alternativ können Sie die „Netzwerk“-Funktion Ihres Browsers nutzen, um zu beobachten, welche Endpoints ausgelöst werden, wenn Sie Aktionen im Frontend der Software ausführen.

Betrachten Sie zur Veranschaulichung den Prozess zum Erstellen eines Blocks. In diesem Fall kann der zugehörige Endpoint als „POST“-Anfrage an „/rest/components“ identifiziert werden; diese Information lässt sich leicht erkennen, indem Sie die Netzwerkaktivität während der Aktion prüfen. Eine kurze Demonstration dieses Ansatzes wird im folgenden kurzen Video gezeigt.

Wie ruft man die Verification Methods (VM) und Blocks eines Requirements ab bzw. wie postet man sie?

Ein Requirement im Requirements & Systems Portal kann mit mehreren Verification Methods (VMs) verknüpft sein, von denen wiederum jede mehrere angehängte Blocks haben kann. Es werden verschiedene Verification-Method-Typen unterstützt, darunter Rules, Test, Inspection, Analyses, Review und benutzerdefinierte VMs. Jeder Verification-Method-Typ wird eindeutig durch eine eigene ID identifiziert.

Sie können den entsprechenden Endpoint verwenden, um die IDs dieser Verification-Method-Typen abzurufen.

GET /rest/requirements/verification-methods/

Um beispielsweise die IDs der Verification-Method-Typen für die Projekt-ID 24 zu erhalten, können Sie den folgenden Endpoint verwenden

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

Um die mit einem bestimmten Requirement verknüpften Verification Methods zu erhalten, erstellt das Requirements & Systems Portal ein dediziertes Objekt namens „Requirement-VMS“. Dieses Objekt hat eine eindeutige Kennung (ID), auf die über den folgenden Endpoint zugegriffen werden kann:

GET /rest/requirements/requirement-vms/

Beispielsweise hat dieses Requirement, SPC-002 mit der ID 2165, eine Verification Method vom Typ „Rules“, und die Objekt-ID von requirment-vms ist 2203.

Wenn wir den Endpoint „/rest/requirements/requirement-vms/2203 “ verwenden, erhalten wir die folgende Antwort.

Bei der Prüfung des Objekts „Requirement-vms“ werden Sie feststellen, dass die Methoden-ID „20“ der Verification Method „Rules“ entspricht, gemäß der zuvor erhaltenen Liste der Verification-Method-Typen. Wenn Sie diese Informationen in Ihr Skript einbinden, stellen Sie sicher, dass Sie die Methoden-ID dem entsprechenden Verification-Method-Typ zuordnen.

Darüber hinaus gibt es innerhalb des Objekts „Requirement-vms“ Verweise auf zwei component-vms. Diese component-vm-IDs repräsentieren die Blocks, die an die Requirement Verification Methods angehängt sind. Wenn Sie programmgesteuert mit diesen Blocks interagieren, verwenden Sie diese IDs entsprechend in Ihrem Skript.

Der Endpoint für den Zugriff auf die component-vms lautet

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

Wenn Sie die Details der component-vms abrufen, liefert das Feld component die Block-ID, mit der Sie den Namen des Blocks zuordnen können.

Printer-friendly version

AI-localized

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.