Documentazione della Rest API e della Python API

Questo documento fornisce il riferimento per la REST API di Requirements & Systems Portal. Utilizzando la REST API, gli utenti possono ottenere e modificare i dati di Requirements & Systems Portal o persino riscrivere i dati in Requirements & Systems Portal, aggiornando così le informazioni. Inoltre, questo offre la possibilità di connettersi/integrarsi con altre applicazioni o app.

Accesso alla Rest API in Requirements & System Portal tramite token

Per accedere alla REST API nell'applicazione Requirements & Systems Portal su Altium A365, gli utenti possono generare i token accedendo al menu Settings e selezionando User Tokens. Nella pagina delle impostazioni User Tokens troverai l'indirizzo API per la tua specifica distribuzione. Questo indirizzo è necessario per effettuare chiamate API.

Fai clic sull'icona “+” nella pagina User Tokens per generare un nuovo token. Ogni token è valido per 3 months e deve essere rigenerato dopo la scadenza.

Per utilizzare l'API con l'access_token, è necessario aggiungere un token tramite un "Bearer ..." nell'header Authorization della richiesta HTTP, usando il tipo di applicazione "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
    }
}'

oppure, usando requests, puoi inviare l'access token in questo modo

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)

Documentazione Python API

La Python API ti consente di accedere e aggiornare gli oggetti nella tua distribuzione con codice python.

Installa il pacchetto python API necessario con pip:

pip install valispace

Importa il modulo API in uno script python:

import valispace

e inizializzalo con

valispace = valispace.API()

Maggiori informazioni sulle funzionalità e sulle funzioni dell'API sono disponibili qui. Il pacchetto python API è concesso in licenza MIT, il che significa che chiunque può contribuire al codice clonando il repository GitHub.

Endpoint

Gli utenti possono accedere agli endpoint nella pagina rest. Per accedere alla pagina, aggiungi “rest/” alla fine dell'URL API che si trova in Requirements & Systems Portal in Settings e “User Tokens“. La pagina Rest mostra Django Swagger con tutti gli endpoint esistenti.

Sono disponibili i metodi “GET”,” POST”,” PUT”,” PATCH” e “DELETE”.

Ogni oggetto in Requirements & Systems Portal ha il proprio ID; puoi usarlo per cercare e recuperare le informazioni dell'oggetto stesso. L'ID dell'oggetto può essere visto direttamente in Requirements & Systems Portal oppure nell'URL quando fai clic sull'oggetto in Requirements & Systems Portal.

Ad esempio, se usi la funzione get per ottenere informazioni su vali tramite rest, puoi usare il seguente endpoint per ottenere i dettagli del vali.

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

Uso di GET per recuperare le informazioni del vali

Allo stesso modo, puoi usare i metodi per recuperare/aggiornare o pubblicare diversi oggetti come Blocks, tag, valis, textvalis, requirements, specifications, verification methods, ecc. Puoi cercare gli endpoint nella pagina rest.

Filtraggio degli oggetti per progetto

Oltre all'autenticazione, puoi usare il metodo "GET" per recuperare oggetti come Valis o Requirements all'interno della distribuzione. Se hai bisogno di filtrare i risultati in base a un progetto specifico, puoi farlo sfruttando le capacità di filtro, a condizione che l'endpoint sia configurato di conseguenza. Ad esempio, per recuperare i requisiti associati al progetto 24, puoi usare la seguente richiesta GET:

GET /rest/requirements/?project=24

Questa funzionalità è mostrata nel video qui sotto per una comprensione più chiara.

Funzioni integrate

All'interno di Requirements & Systems Portal, ogni volta che un utente digita del testo nel campo di testo, il testo viene salvato nel backend in formato HTML
. Il formato HTML mantiene i riferimenti di formattazione a valis o ad altri oggetti. Quindi, se stai ottenendo le informazioni dei requisiti, potresti ricevere il testo HTML nell'importazione. Per evitarlo, abbiamo implementato due funzioni che possono essere utili per convertire i campi HTML in solo testo oppure in formattazione HTML con i valis convertiti in testo. Le funzioni sono clean_text e clean_html.

Funzione clean_text

La funzione clean_text converte in testo tutti i formati HTML e i riferimenti a oggetti all'interno del campo. Tuttavia, in questo caso, anche la formattazione viene persa. Ad esempio, la formattazione viene persa anche se hai un elenco, tabelle o colore. Puoi usarla come mostrato di seguito.

Qui sto applicando il filtro per il progetto 24 e sto chiedendo di restituire il testo pulito per il testo e la motivazione del campo. L'output per questa specifica azione sarebbe il seguente.

Requisiti dopo l'uso della funzione Clean_text

Funzione clean_html

La funzione clean_html mantiene le opzioni di formattazione del testo, ma converte in testo i riferimenti/gli oggetti come i valis. Se il testo contiene opzioni di formattazione come elenchi, colore di sfondo, tabelle ecc., queste informazioni vengono mantenute.

Requisiti dopo l'uso della funzione clean_html

Domande comuni:

Come trovare l'endpoint corretto?

Orientarsi tra numerosi endpoint con nomi simili può creare confusione. Se hai dubbi su un endpoint specifico, ti invitiamo a contattare la nostra Altium Support Page per chiarimenti. In alternativa, puoi sfruttare la funzione "network" del browser per osservare quali endpoint vengono attivati quando esegui azioni nel front-end del software.

Come esempio, considera il processo di creazione di un Block. In questo caso, l'endpoint associato può essere identificato come una richiesta "POST" a "/rest/components"; questa informazione può essere facilmente individuata ispezionando l'attività di rete durante l'azione. Una breve dimostrazione di questo approccio è fornita nel breve video qui sotto.

Come si ottengono/pubblicano i verification methods (VM) e i Blocks di un requisito?

Un requisito in Requirements & Systems Portal può essere associato a più verification methods (VM), ognuno dei quali può a sua volta avere più Blocks collegati. Sono supportati vari tipi di verification method, inclusi rules, test, inspection, analyses, review e VM personalizzati. Ogni tipo di verification method è identificato in modo univoco dal proprio ID.

Puoi usare l'endpoint appropriato per recuperare gli ID di questi tipi di verification method.

GET /rest/requirements/verification-methods/

Ad esempio, per ottenere gli ID dei tipi di Verification method per il project id 24, puoi usare il seguente endpoint

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

Elenco dei verification method del progetto

Per ottenere i verification methods collegati a un requisito specifico, Requirements & Systems Portal crea un oggetto dedicato noto come "Requirement-VMS". Questo oggetto ha un identificatore univoco (ID), a cui si può accedere tramite il seguente endpoint:

GET /rest/requirements/requirement-vms/

Ad esempio, questo requisito, SPC-002 con ID 2165, ha un verification method di tipo “Rules”, e l'ID oggetto di requirment-vms è 2203.

Se usiamo l'endpoint, “/rest/requirements/requirement-vms/2203 ” otteniamo la seguente risposta.

Chiavi e valori di Requirment-vms

Esaminando l'oggetto "Requirement-vms", noterai che l'ID metodo "20" corrisponde al Verification Method "Rules", in base all'elenco dei tipi di verification method ottenuto in precedenza. Quando incorpori queste informazioni nel tuo script, assicurati di mappare l'ID del metodo al rispettivo tipo di verification method.

Inoltre, all'interno dell'oggetto "Requirement-vms", ci sono riferimenti a due component-vms. Questi ID di component-vm rappresentano i Blocks collegati ai Requirement Verification Methods. Quando interagisci con questi Blocks a livello di codice, utilizza questi ID nel tuo script di conseguenza.

L'endpoint per accedere ai component-vms sarebbe

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

Quando ottieni i dettagli dei component-vms, il campo component fornisce l'ID del Block con cui puoi mappare il nome del Block.

Component-vms