Dokumentation zur REST-API und Python-API

Auf einen Blick

Erfahren Sie, wie Sie über die REST-API und das Python-API-Paket auf Daten im Requirements Portal zugreifen und diese aktualisieren. Dieser Leitfaden behandelt die Token-Authentifizierung, das Auffinden von Endpunkten in Swagger, das Filtern von Anforderungen nach Projekt sowie die Umwandlung von HTML-Feldern in nutzbaren Text mit oder ohne Formatierung. Lesen Sie weiter und erfahren Sie, wie Sie diese API-Werkzeuge in Ihrer eigenen Bereitstellung einsetzen können.

- 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.
Mit KI tiefer einsteigen:

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.

Verwenden Sie your_API_URL/swagger/, um auf die Swagger-Seite zuzugreifen. Wenn Sie / am Ende weglassen, werden Sie nicht auf die Seite weitergeleitet. Ihre API-URL finden Sie auf der Seite Settings – User Tokens.

Alternativ können Sie your_Workspace_URL/requirements/swagger/ verwenden, um die Seite aufzurufen.

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

Die 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.

AI-LocalizedKI-lokalisiert
Wenn Sie ein Problem feststellen, wählen Sie den Text/das Bild aus und drücken SieCtrl + Enter, um uns Ihr Feedback zu senden.
Contents
Funktionsverfügbarkeit

Die Ihnen zur Verfügung stehenden Funktionen hängen davon ab, über welche Altium-Lösung Sie verfügen – Altium Develop, Altium Agile Teams, Altium Agile Enterprise oder Altium Designer (mit aktivem Laufzeitvertrag).

Wenn Sie eine dokumentierte Funktion in Ihrer tatsächlich verwendeten Software nicht sehen, wenden Sie sich an den Altium-Vertrieb, um mehr zu erfahren.

Contents