Dokumentation zur REST-API und Python-API
Auf einen Blick
- Ermitteln Sie die API-Adresse Ihrer Bereitstellung, generieren Sie Zugriffstoken und authentifizieren Sie Anfragen.
- Richten Sie das Python-API-Paket ein und erkunden Sie Endpunkte zum Abrufen und Ändern von Objekten.
- Filtern Sie Ergebnisse nach Projekt und erfahren Sie, wann Sie 'clean_text' oder 'clean_html' verwenden sollten.
Diese Seite enthält die Referenz zur REST-API von Requirements Portal. Mit der REST-API können Sie Daten aus Requirements Portal abrufen und ändern oder Daten in Requirements Portal zurückschreiben und so Informationen aktualisieren. Darüber hinaus können Sie damit Verbindungen zu anderen Anwendungen herstellen bzw. diese integrieren.
Zugriff auf die REST-API in Requirements Portal mithilfe von Tokens
Für den Zugriff auf die REST-API in Requirements Portal können Sie auf der Seite Settings – User Tokens Tokens generieren. (Klicken Sie dazu oben rechts auf das Symbol
, wählen Sie im angezeigten Menü Settings und anschließend in der Liste im linken Bereich User Tokens aus.) Auf dieser Seite finden Sie die API address für Ihre spezifische Bereitstellung. Diese Adresse ist für API-Aufrufe erforderlich.
Klicken Sie unten rechts auf der Seite Settings – User Tokens auf das Symbol +, um ein neues Token zu generieren. Jedes Token ist für 3 months gültig und muss nach Ablauf neu generiert werden.
Um die API mit dem access_token zu nutzen, müssen Sie dem HTTP-Anfrageheader „Authorization“ ein Token über „Bearer ...“ hinzufügen und dabei den Anwendungstyp „JSON“ verwenden.
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
}
}'
Mit requests können Sie das Zugriffstoken auch 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)
Dokumentation zur Python-API
Mit der Python-API können Sie über Python-Code auf Objekte in Ihrer Bereitstellung zugreifen und diese aktualisieren.
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. Somit kann jeder zum Code beitragen, indem er das GitHub-Repository klont.
Endpunkte
Benutzer können auf der Swagger-Seite auf die Endpunkte zugreifen. Um diese Seite aufzurufen, hängen Sie swagger/ an die API-URL an, die Sie auf der Seite Settings – User Tokens finden. Die Seite zeigt Django Swagger mit allen vorhandenen Endpunkten.
Es stehen die Methoden GET, POST, PUT, PATCH und DELETE zur Verfügung.
Jedes Objekt in Requirements Portal hat eine eigene ID. Mit dieser können Sie nach dem Objekt suchen und dessen Informationen abrufen. Die Objekt-ID ist entweder direkt in Requirements Portal oder in der URL sichtbar, wenn Sie in Requirements Portal auf das Objekt klicken.
Wenn Sie beispielsweise die GET-Funktion verwenden, um über Swagger Informationen zum Anforderungsverlauf abzurufen, können Sie mit dem folgenden Endpunkt die Details des Anforderungsverlaufs abrufen.
GET /rest/requirements/{requirement-id}/history/

Abrufen der Informationen zum Anforderungsverlauf mit GET
Ebenso können Sie die Methoden verwenden, um verschiedene Objekte wie Blöcke, Tags, Valis, Textvalis, Anforderungen, Spezifikationen, Verifizierungsmethoden usw. abzurufen, zu aktualisieren oder per POST zu erstellen. Sie können auf der Swagger-Seite nach den Endpunkten suchen.
Objekte nach Projekten filtern
Zusätzlich zur Authentifizierung können Sie mit der GET-Methode Objekte wie Valis oder Anforderungen innerhalb der Bereitstellung abrufen. Wenn Sie die Ergebnisse nach einem bestimmten Projekt filtern müssen, können Sie die Filterfunktionen nutzen, sofern der Endpunkt entsprechend konfiguriert ist. Um beispielsweise Anforderungen abzurufen, die Projekt 24 zugeordnet sind, können Sie die folgende GET-Anfrage verwenden:
GET /rest/requirements/?project=24
Zur Veranschaulichung wird diese Funktion im folgenden Video demonstriert.
Integrierte Funktionen
Wenn ein Benutzer in Requirements Portal Text in ein Textfeld eingibt, wird dieser im Backend im HTML-Format gespeichert. Das HTML-Format behält die Formatierung sowie Verweise auf Valis oder andere Objekte bei. Wenn Sie Anforderungsinformationen abrufen, kann Ihr Import daher HTML-Text enthalten. Um dies zu vermeiden, haben wir zwei Funktionen implementiert, mit denen Sie HTML-Felder in reinen Text oder in HTML mit als Text dargestellten Valis umwandeln können. Diese Funktionen heißen clean_text und clean_html.
Die Funktion clean_text
Die Funktion clean_text wandelt sämtliche HTML-Formatierungen und Objektverweise innerhalb des Felds in Text um. Dabei geht jedoch auch die Formatierung verloren. Dies betrifft beispielsweise Listen, Tabellen oder Farben. Sie können die Funktion wie unten gezeigt verwenden.
Hier filtere ich nach Projekt 24 und fordere reinen Text für den Text und die Begründung des Felds an. Die Ausgabe für diese spezifische Aktion sieht wie folgt aus.
Anforderungen nach Verwendung der Funktion clean_textDie Funktion clean_html
Die Funktion clean_html behält die Formatierung des Texts bei, wandelt jedoch Verweise bzw. Objekte wie Valis in Text um. Enthält der Text Formatierungen wie Listen, Hintergrundfarben, Tabellen usw., bleiben diese Informationen erhalten.
Anforderungen nach Verwendung der Funktion clean_html
Häufige Fragen
Wie finde ich den richtigen Endpunkt?
Bei zahlreichen Endpunkten mit ähnlichen Namen kann die Orientierung schwierig sein. Wenn Sie sich bei einem bestimmten Endpunkt unsicher sind, wenden Sie sich zur Klärung an unsere Altium-Supportseite. Alternativ können Sie die Netzwerkfunktion Ihres Browsers nutzen, um zu beobachten, welche Endpunkte bei Aktionen im Frontend der Software aufgerufen werden.
Betrachten wir zur Veranschaulichung das Erstellen eines Blocks. In diesem Fall lässt sich der zugehörige Endpunkt als „POST“-Anfrage an „/rest/components“ identifizieren. Diese Information lässt sich leicht ermitteln, indem Sie während der Aktion die Netzwerkaktivität untersuchen. Das folgende kurze Video zeigt diese Vorgehensweise.


