Dokumentacja Rest API i Python API

Niniejszy dokument stanowi odniesienie dla interfejsu API REST Portalu Wymagań i Systemów. Korzystając z interfejsu API REST, użytkownicy mogą pobierać i modyfikować dane z portalu wymagań i systemów, a nawet zapisywać dane z powrotem w portalu wymagań i systemów, a tym samym aktualizować informacje. Dodatkowo daje to możliwość połączenia/integracji z innymi aplikacjami.

Dostęp do Rest API w Portalu Wymagań i Systemów za pomocą tokenów

Aby uzyskać dostęp do REST API w aplikacji Portal Wymagań i Systemów na Altium A365, użytkownicy mogą wygenerować tokeny, przechodząc do menu Settings i wybierając User Tokens. Na stronie ustawień User Tokens znajduje się adres API dla konkretnego wdrożenia. Adres ten jest niezbędny do wykonywania połączeń API.

Kliknij ikonę “+” na stronie User Tokens, aby wygenerować nowy token. Każdy token jest ważny dla 3 months i musi zostać ponownie wygenerowany po jego wygaśnięciu.

Korzystając z interfejsu API przy użyciu access_token, konieczne jest dodanie tokena za pomocą "Bearer ..." przy użyciu typu aplikacji "JSON" do nagłówka żądania HTTP autoryzacji.

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

lub używając żądań, możesz wysłać token dostępu w następujący sposób

access_token = 'Generated_Access_token'
api_url = 'Api_Address'

# identyfikator obszaru roboczego i typ komponentu

workspace_id = 1
component_type_name = "CompA"

# Definiowanie nagłówków z tokenem dostępu
headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json', # Dostosuj typ zawartości według potrzeb
}

# Wykonaj żądanie GET (możesz użyć innych metod HTTP, takich jak POST, PUT itp.)
component_types_workspace = requests.get(api_url + "components/types/?workspace="+str(workspace_id), headers=headers)

Dokumentacja API Python

Interfejs API Python umożliwia dostęp i aktualizację obiektów we wdrożeniu za pomocą kodu Python.

Zainstaluj niezbędny pakiet API Python za pomocą pip:

pip install valispace

Zaimportuj moduł API w skrypcie Pythona:

import valispace

i zainicjuj za pomocą

valispace = valispace.API()

Więcej informacji na temat funkcjonalności i funkcji API można znaleźć tutaj. Pakiet Python API jest licencjonowany na licencji MIT, co oznacza, że każdy może wnieść swój wkład w kod poprzez klonowanie repozytorium GitHub.

Punkty końcowe

Użytkownicy mogą uzyskać dostęp do punktów końcowych na stronie rest. Aby uzyskać dostęp do strony, należy dodać "rest/" na końcu adresu URL API, który można znaleźć w Portalu wymagań i systemów oraz w Ustawieniach i "Tokenach użytkownika". Strona Rest pokazuje Django Swagger ze wszystkimi istniejącymi punktami końcowymi.

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

Każdy obiekt w portalu wymagań i systemów ma swój własny identyfikator; można go użyć do wyszukiwania i pobierania informacji o samym obiekcie. Identyfikator obiektu można zobaczyć bezpośrednio w Portalu Wymagań i Systemów lub w adresie URL po kliknięciu obiektu w Portalu Wymagań i Systemów.

Na przykład, jeśli używasz funkcji get, aby uzyskać informacje o vali przez resztę, możesz użyć następującego punktu końcowego, aby uzyskać szczegóły vali.

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

Korzystanie z GET, pobieranie informacji o vali

Podobnie można użyć metod do pobierania/aktualizowania lub publikowania różnych obiektów, takich jak bloki, tagi, valis, textvalis, wymagania, specyfikacje, metody weryfikacji itp. Punkty końcowe można wyszukać na pozostałej stronie.

Filtrowanie obiektów dla projektów

Oprócz uwierzytelniania można użyć metody "GET", aby pobrać obiekty takie jak Valis lub Requirements w ramach wdrożenia. Jeśli chcesz przefiltrować wyniki na podstawie konkretnego projektu, możesz to osiągnąć, wykorzystując możliwości filtrowania, pod warunkiem, że punkt końcowy jest odpowiednio skonfigurowany. Na przykład, aby pobrać wymagania powiązane z projektem 24, można użyć następującego żądania GET:

GET /rest/requirements/?project=24

Ta funkcjonalność została zademonstrowana na poniższym filmie, aby lepiej ją zrozumieć.

Funkcje wbudowane

W portalu wymagań i systemów za każdym razem, gdy użytkownik wpisuje tekst w polu tekstowym, tekst jest zapisywany w zapleczu w formacie HTML
formacie HTML. Format HTML zachowuje odniesienia formatowania do wartości lub innych obiektów. Tak więc, jeśli otrzymujesz informacje o wymaganiach, możesz otrzymać tekst HTML w swoim imporcie. Aby tego uniknąć, zaimplementowaliśmy dwie funkcje, które mogą być przydatne do konwersji pól HTML na zwykły tekst lub formatowanie HTML z wartościami przekonwertowanymi na tekst. Funkcje te to clean_text i clean_html.

Funkcja clean_text

Funkcja clean_text konwertuje wszystkie formaty HTML i odwołania do obiektów w polu na tekst. Jednak w tym przypadku formatowanie jest również tracone. Na przykład formatowanie jest również tracone, jeśli masz listę, tabele lub kolor. Możesz użyć tej funkcji, jak pokazano poniżej.

Tutaj wykonuję filtr dla projektu 24 i proszę o podanie czystego tekstu dla tekstu i uzasadnienia pola. Wynik będzie następujący dla tego konkretnego działania.

Wymagania po użyciu funkcji Clean_text

Funkcja clean_html

Funkcja clean_html zachowuje opcje formatowania tekstu, ale następnie konwertuje odniesienia/obiekty, takie jak wartości, na tekst. Jeśli tekst zawiera opcje formatowania, takie jak listy, kolor tła, tabele itp., informacje te są zachowywane.

Wymagania po użyciu funkcji clean_html

Często zadawane pytania:

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

Poruszanie się po wielu punktach końcowych o podobnych nazwach może być mylące. W przypadku wątpliwości co do konkretnego punktu końcowego, zachęcamy do skontaktowania się z naszą stroną pomocy technicznej Altium w celu uzyskania wyjaśnień. Alternatywnie można wykorzystać funkcję "sieci" przeglądarki, aby obserwować, które punkty końcowe są uruchamiane podczas wykonywania działań w interfejsie oprogramowania.

Jako ilustrację rozważmy proces tworzenia bloku. W tym przypadku powiązany punkt końcowy można zidentyfikować jako żądanie "POST" do "/rest/components", informacje te można łatwo rozpoznać, sprawdzając aktywność sieciową podczas akcji. Zwięzła demonstracja tego podejścia znajduje się w krótkim filmie poniżej.

Jak uzyskać/zamieścić metody weryfikacji wymagania (VM) i bloki?

Wymaganie w portalu wymagań i systemów może być powiązane z wieloma metodami weryfikacji (VM), z których każda może z kolei mieć wiele dołączonych do niej bloków. Obsługiwane są różne typy metod weryfikacji, w tym reguły, testy, inspekcje, analizy, przeglądy i niestandardowe maszyny wirtualne. Każdy typ metody weryfikacji jest jednoznacznie identyfikowany przez własny identyfikator.

Można użyć odpowiedniego punktu końcowego, aby pobrać identyfikatory dla tych typów metod weryfikacji.

GET /rest/requirements/verification-methods/

Na przykład, aby uzyskać identyfikatory typów metod weryfikacji dla identyfikatora projektu 24, można użyć następującego punktu końcowego

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

Lista metod weryfikacji projektu

Aby uzyskać metody weryfikacji powiązane z konkretnym wymaganiem, Portal Wymagań i Systemów tworzy dedykowany obiekt znany jako "Wymaganie-VMS" Obiekt ten ma swój unikalny identyfikator (ID), do którego można uzyskać dostęp za pośrednictwem następującego punktu końcowego:

GET /rest/requirements/requirement-vms/

Na przykład, to wymaganie SPC-002 o ID 2165 ma jedną metodę weryfikacji typu "Rules", a identyfikator obiektu requirment-vms to 2203.

Jeśli użyjemy punktu końcowego "/rest/requirements/requirement-vms/2203 ", otrzymamy następującą odpowiedź.

Klucze i wartości requirment-vms

Po sprawdzeniu obiektu "Requirement-vms" można zauważyć, że identyfikator metody "20" odpowiada metodzie weryfikacji "Rules", zgodnie z listą typów metod weryfikacji uzyskaną wcześniej. Podczas włączania tych informacji do skryptu należy upewnić się, że identyfikator metody jest mapowany na odpowiedni typ metody weryfikacji.

Ponadto w obiekcie "Requirement-vms" znajdują się odniesienia do dwóch component-vms. Te identyfikatory component-vm reprezentują bloki dołączone do metod weryfikacji wymagań. Podczas programowej interakcji z tymi blokami należy odpowiednio wykorzystać te identyfikatory w skrypcie.

Punkt końcowy dostępu do component-vms to

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

Po uzyskaniu szczegółów komponentu-vms, pola komponentu podają identyfikator bloku, z którym można zmapować nazwę bloku.

Component-vms