Dokumentacja REST API i Python API

Ta strona zawiera dokumentację referencyjną interfejsu REST API portalu Requirements Portal. Za pomocą REST API można pobierać i modyfikować dane z Requirements Portal, a także zapisywać je z powrotem w portalu, aktualizując w ten sposób informacje. Umożliwia to również łączenie i integrację z innymi aplikacjami.

Dostęp do REST API w Requirements Portal za pomocą tokenów

Aby uzyskać dostęp do REST API w Requirements Portal, możesz wygenerować tokeny na stronie Settings – User Tokens (aby ją otworzyć, kliknij ikonę  w prawym górnym rogu, wybierz Settings z wyświetlonego menu, a następnie User Tokens z listy w lewym panelu). Na tej stronie znajdziesz API address dla swojego wdrożenia. Ten adres jest niezbędny do wykonywania wywołań API.

Kliknij ikonę + w prawym dolnym rogu strony Settings – User Tokens, aby wygenerować nowy token. Każdy token jest ważny przez 3 months i po wygaśnięciu należy wygenerować go ponownie.

Aby korzystać z API za pomocą access_token, należy dodać token w formacie „Bearer ...” do nagłówka Authorization żądania HTTP, używając typu danych „JSON”.

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

Możesz też użyć biblioteki requests i przesłać token dostępu w następujący sposób:

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)

Dokumentacja API dla języka Python

API dla języka Python umożliwia dostęp do obiektów w Twoim wdrożeniu i ich aktualizację za pomocą kodu w języku Python.

Zainstaluj wymagany pakiet API dla języka Python za pomocą pip:

pip install valispace

Zaimportuj moduł API w skrypcie w języku Python:

import valispace

i zainicjalizuj go za pomocą

valispace = valispace.API()

Więcej informacji o możliwościach i funkcjach API znajdziesz tutaj. Pakiet API dla języka Python jest udostępniany na licencji MIT, co oznacza, że każdy może współtworzyć kod po sklonowaniu repozytorium GitHub.

Punkty końcowe

Użytkownicy mogą uzyskać dostęp do punktów końcowych na stronie Swagger. Aby ją otworzyć, dodaj swagger/ na końcu adresu URL API, który znajdziesz na stronie Settings – User Tokens. Strona wyświetla Django Swagger ze wszystkimi istniejącymi punktami końcowymi.

Dostępne są metody GET, POST, PUT, PATCH i DELETE.

Każdy obiekt w Requirements Portal ma własny identyfikator. Możesz go użyć do wyszukania obiektu i pobrania informacji o nim. Identyfikator obiektu jest widoczny bezpośrednio w Requirements Portal lub w adresie URL po kliknięciu obiektu w portalu.

Na przykład, jeśli używasz metody GET do pobierania informacji o historii wymagania za pośrednictwem Swagger, możesz skorzystać z poniższego punktu końcowego, aby pobrać szczegóły tej historii.

GET /rest/requirements/{requirement-id}/history/

Pobieranie informacji o historii wymagania za pomocą GET

Podobnie możesz używać tych metod do pobierania, aktualizowania lub dodawania różnych obiektów, takich jak bloki, tagi, valis, textvalis, wymagania, specyfikacje, metody weryfikacji itp. Punkty końcowe możesz wyszukiwać na stronie Swagger.

Filtrowanie obiektów według projektów

Po uwierzytelnieniu możesz używać metody GET do pobierania obiektów, takich jak Valis lub wymagania, w ramach wdrożenia. Jeśli chcesz filtrować wyniki według konkretnego projektu, możesz skorzystać z funkcji filtrowania, o ile dany punkt końcowy jest odpowiednio skonfigurowany. Na przykład, aby pobrać wymagania powiązane z projektem 24, możesz użyć następującego żądania GET:

GET /rest/requirements/?project=24

Aby ułatwić zrozumienie tej funkcji, przedstawiono ją w poniższym filmie.

Funkcje wbudowane

W Requirements Portal tekst wpisywany przez użytkownika w polu tekstowym jest zapisywany po stronie serwera w formacie HTML. Format HTML zachowuje formatowanie oraz odwołania do valis lub innych obiektów. Dlatego podczas pobierania informacji o wymaganiach importowane dane mogą zawierać tekst HTML. Aby tego uniknąć, udostępniliśmy dwie funkcje, które pozwalają przekształcać pola HTML w zwykły tekst lub zachować formatowanie HTML, jednocześnie zamieniając valis na tekst. Są to funkcje clean_text i clean_html.

Funkcja clean_text

Funkcja clean_text zamienia całą zawartość HTML i odwołania do obiektów w danym polu na tekst. Powoduje to jednak również utratę formatowania, na przykład list, tabel lub kolorów. Możesz jej użyć w sposób pokazany poniżej.

W tym przykładzie filtruję dane według projektu 24 i żądam zwrócenia zwykłego tekstu dla pól tekstu i uzasadnienia. Wynik tej operacji będzie wyglądał następująco.

Wymagania po użyciu funkcji clean_text

Funkcja clean_html

Funkcja clean_html zachowuje formatowanie tekstu, ale zamienia odwołania i obiekty, takie jak valis, na tekst. Jeśli tekst zawiera elementy formatowania, takie jak listy, kolor tła, tabele itp., informacje te zostają zachowane.

Wymagania po użyciu funkcji clean_html

Często zadawane pytania

Jak znaleźć właściwy punkt końcowy?

Poruszanie się wśród wielu punktów końcowych o podobnych nazwach może być mylące. Jeśli masz wątpliwości dotyczące konkretnego punktu końcowego, zachęcamy do kontaktu za pośrednictwem strony pomocy technicznej Altium w celu uzyskania wyjaśnień. Możesz też skorzystać z karty „Sieć” w narzędziach przeglądarki, aby sprawdzić, które punkty końcowe są wywoływane podczas wykonywania działań w interfejsie użytkownika oprogramowania.

Rozważmy na przykład tworzenie bloku. W tym przypadku powiązany punkt końcowy można zidentyfikować jako żądanie „POST” do „/rest/components”. Informację tę można łatwo ustalić, sprawdzając aktywność sieciową podczas wykonywania tej czynności. Krótki pokaz tego podejścia znajduje się w poniższym filmie.