Dokumentation zur REST-API und Python-API

Diese Seite enthält die Referenz zur REST-API von Requirements Portal. Über die REST-API können Sie Daten aus Requirements Portal abrufen und ändern oder Daten in Requirements Portal zurückschreiben und so Informationen aktualisieren. Außerdem können Sie damit andere Anwendungen anbinden bzw. integrieren.

Zugriff auf die REST-API in Requirements Portal mithilfe von Tokens

Um auf die REST-API in Requirements Portal zuzugreifen, 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 jeweilige Bereitstellung. Diese Adresse wird für API-Aufrufe benötigt.

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 das Token im Format „Bearer ...“ zum HTTP-Anforderungsheader „Authorization“ hinzufügen und 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
    }
}'

Alternativ können Sie das Zugriffstoken mit requests 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 einem Python-Skript:

import valispace

und initialisieren Sie es mit

valispace = valispace.API()

Weitere Informationen zu den Funktionen der API finden Sie hier. Das Python-API-Paket steht unter der MIT-Lizenz. Das bedeutet, dass jeder durch Klonen des GitHub-Repositorys zum Code beitragen kann.

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 verfügbaren Endpunkten.

Es stehen die Methoden GET, POST, PUT, PATCH und DELETE zur Verfügung.

Jedes Objekt in Requirements Portal hat eine eigene ID. Über diese ID können Sie nach dem Objekt suchen und dessen Informationen abrufen. Die Objekt-ID wird entweder direkt in Requirements Portal oder in der URL angezeigt, wenn Sie in Requirements Portal auf das Objekt klicken.

Wenn Sie beispielsweise die GET-Funktion verwenden, um Informationen zum Anforderungsverlauf über Swagger 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 mit den Methoden verschiedene Objekte wie Blöcke, Tags, Valis, Textvalis, Anforderungen, Spezifikationen, Verifizierungsmethoden usw. abrufen, aktualisieren oder per POST übermitteln. Auf der Swagger-Seite können Sie nach den Endpunkten suchen.

Objekte nach Projekten filtern

Neben der Authentifizierung können Sie die GET-Methode verwenden, um Objekte wie Valis oder Anforderungen innerhalb der Bereitstellung abzurufen. Wenn Sie die Ergebnisse nach einem bestimmten Projekt filtern möchten, können Sie dafür die Filterfunktionen nutzen, sofern der Endpunkt entsprechend konfiguriert ist. Um beispielsweise die 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 bewahrt die Formatierung sowie Verweise auf Valis oder andere Objekte. Wenn Sie Anforderungsinformationen abrufen, kann Ihr Import daher HTML-Text enthalten. Um dies zu vermeiden, haben wir zwei Funktionen implementiert, mit denen sich HTML-Felder in reinen Text oder in HTML-formatierten Text umwandeln lassen, bei dem Valis in Text konvertiert werden. Diese Funktionen heißen clean_text und clean_html.

Funktion clean_text

Die Funktion clean_text wandelt alle HTML-Formatierungen und Objektverweise innerhalb des Feldes in Text um. Dabei geht jedoch auch die Formatierung verloren, beispielsweise bei Listen, Tabellen oder Farben. Sie können die Funktion wie unten gezeigt verwenden.

Hier filtere ich nach Projekt 24 und fordere den reinen Text für die Felder „Text“ und „Begründung“ an. Für diese konkrete Aktion sieht die Ausgabe wie folgt aus.

Anforderungen nach Verwendung der Funktion clean_text

Funktion clean_html

Die Funktion clean_html behält die Textformatierung 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 bitte an unsere Altium-Supportseite. Alternativ können Sie mit der Netzwerkfunktion Ihres Browsers beobachten, welche Endpunkte bei Aktionen in der Benutzeroberfläche der Software aufgerufen werden.

Betrachten wir als Beispiel das Erstellen eines Blocks. Der zugehörige Endpunkt lässt sich in diesem Fall als „POST“-Anfrage an „/rest/components“ identifizieren. Diese Information können Sie einfach ermitteln, indem Sie während der Aktion die Netzwerkaktivität untersuchen. Das folgende kurze Video veranschaulicht diese Vorgehensweise.