Documentation de l’API REST et de l’API Python

Ce document fournit la référence de l’API REST de Requirements & Systems Portal. À l’aide de l’API REST, les utilisateurs peuvent obtenir et modifier des données de Requirements & Systems Portal, ou même réécrire des données dans Requirements & Systems Portal et ainsi mettre à jour les informations. De plus, cela vous permet de vous connecter à d’autres applications ou de les intégrer.

Accéder à l’API REST dans Requirements & Systems Portal à l’aide de jetons

Pour accéder à l’API REST dans l’application Requirements & Systems Portal sur Altium A365, les utilisateurs peuvent générer des jetons en accédant au menu Settings et en sélectionnant User Tokens. Dans la page de paramètres User Tokens, vous trouverez l’adresse API correspondant à votre déploiement spécifique. Cette adresse est nécessaire pour effectuer des appels API.

Cliquez sur l’icône “+” dans la page User Tokens pour générer un nouveau jeton. Chaque jeton est valide pendant 3 months et doit être régénéré après expiration.

Pour consommer l’API à l’aide de l’access_token, il est nécessaire d’ajouter un jeton via un « Bearer ... » dans l’en-tête Authorization de la requête HTTP, en utilisant le type d’application « 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
    }
}'

ou, en utilisant requests, vous pouvez envoyer le jeton d’accès comme ceci

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)

Documentation de l’API Python

L’API Python vous permet d’accéder aux objets de votre déploiement et de les mettre à jour avec du code Python.

Installez le package API Python nécessaire avec pip :

pip install valispace

Importez le module API dans un script Python :

import valispace

et initialisez-le avec

valispace = valispace.API()

Vous trouverez plus d’informations sur les fonctionnalités et les fonctions de l’API ici. Le package de l’API Python est distribué sous licence MIT, ce qui signifie que tout le monde peut contribuer au code en clonant le dépôt GitHub.

Endpoints

Les utilisateurs peuvent accéder aux endpoints sur la page rest. Pour accéder à cette page, ajoutez « rest/ » à la fin de l’URL de l’API, que vous trouverez dans Requirements & Systems Portal sous Settings puis « User Tokens ». La page Rest affiche Django Swagger avec tous les endpoints existants.

Les méthodes disponibles sont « GET », « POST », « PUT », « PATCH » et « DELETE ».

Chaque objet dans Requirements & Systems Portal possède son propre ID ; vous pouvez l’utiliser pour rechercher et récupérer les informations de l’objet lui-même. L’ID de l’objet peut être visible soit directement dans Requirements & Systems Portal, soit dans l’URL lorsque vous cliquez sur l’objet dans Requirements & Systems Portal.

Par exemple, si vous utilisez la fonction get pour obtenir des informations sur un vali via rest, vous pouvez utiliser l’endpoint suivant pour obtenir les détails du vali.

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

Utilisation de GET pour récupérer les informations du vali

De la même manière, vous pouvez utiliser ces méthodes pour récupérer/mettre à jour ou publier différents objets tels que des Blocks, tags, valis, textvalis, requirements, specifications, verification methods, etc. Vous pouvez rechercher les endpoints sur la page rest.

Filtrage des objets par projet

En plus de l’authentification, vous pouvez utiliser la méthode « GET » pour récupérer des objets tels que des Valis ou des Requirements dans le déploiement. Si vous devez filtrer les résultats en fonction d’un projet spécifique, vous pouvez le faire en exploitant les capacités de filtrage, à condition que l’endpoint soit configuré en conséquence. Par exemple, pour récupérer les requirements associées au projet 24, vous pouvez utiliser la requête GET suivante :

GET /rest/requirements/?project=24

Cette fonctionnalité est illustrée dans la vidéo ci-dessous pour une meilleure compréhension.

Fonctions intégrées

Dans Requirements & Systems Portal, chaque fois qu’un utilisateur saisit du texte dans le champ de texte, ce texte est enregistré côté backend au format HTML
. Le format HTML conserve les références de mise en forme vers les valis ou d’autres objets. Ainsi, si vous récupérez les informations des requirements, il se peut que vous obteniez le texte HTML dans votre import. Pour éviter cela, nous avons implémenté deux fonctions utiles pour convertir les champs HTML soit en texte brut, soit en HTML avec les valis convertis en texte. Ces fonctions sont clean_text et clean_html.

Fonction clean_text

La fonction clean_text convertit tous les formats HTML et les références d’objets dans le champ en texte. Cependant, dans ce cas, la mise en forme est également perdue. Par exemple, si vous avez une liste, des tableaux ou de la couleur, cette mise en forme sera aussi perdue. Vous pouvez l’utiliser comme indiqué ci-dessous.

Ici, j’applique le filtre pour le projet 24 et je demande le texte nettoyé pour le texte et la justification du champ. Le résultat serait le suivant pour cette action spécifique.

Requirements après utilisation de la fonction Clean_text

Fonction clean_html

La fonction clean_html conserve les options de mise en forme du texte, mais convertit les références/objets comme les valis en texte. Si le texte contient des options de mise en forme telles que des listes, une couleur d’arrière-plan, des tableaux, etc., ces informations sont conservées.

Requirements après utilisation de la fonction clean_html

Questions fréquentes :

Comment trouver le bon endpoint ?

Il peut être déroutant de naviguer parmi de nombreux endpoints aux noms similaires. Si vous avez un doute sur un endpoint spécifique, nous vous invitons à contacter notre Altium Support Page pour obtenir des précisions. Vous pouvez également utiliser la fonctionnalité « network » de votre navigateur pour observer quels endpoints sont déclenchés lorsque vous effectuez des actions dans l’interface du logiciel.

À titre d’illustration, prenons le processus de création d’un Block. Dans ce cas, l’endpoint associé peut être identifié comme une requête « POST » vers « /rest/components » ; cette information peut être facilement déterminée en inspectant l’activité réseau pendant l’action. Une brève démonstration de cette approche est fournie dans la courte vidéo ci-dessous.

Comment obtenir/publier les verification methods (VM) et les Blocks d’une requirement ?

Une requirement dans Requirements & Systems Portal peut être associée à plusieurs verification methods (VM), chacun pouvant à son tour avoir plusieurs Blocks attachés. Différents types de verification methods sont pris en charge, notamment rules, test, inspection, analyses, review et des VM personnalisés. Chaque type de verification method est identifié de manière unique par son propre ID.

Vous pouvez utiliser l’endpoint approprié pour récupérer les ID de ces types de verification methods.

GET /rest/requirements/verification-methods/

Par exemple, pour obtenir les ID des types de Verification method pour le projet d’ID 24, vous pouvez utiliser l’endpoint suivant

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

Liste des verification methods du projet

Pour obtenir les verification methods liés à une requirement spécifique, Requirements & Systems Portal crée un objet dédié appelé « Requirement-VMS ». Cet objet possède son propre identifiant unique (ID), accessible via l’endpoint suivant :

GET /rest/requirements/requirement-vms/

Par exemple, cette requirement, SPC-002 avec l’ID 2165, possède une verification method de type « Rules », et l’ID de l’objet requirement-vms est 2203.

Si nous utilisons l’endpoint « /rest/requirements/requirement-vms/2203 », nous obtenons la réponse suivante.

Clés et valeurs de requirement-vms

En examinant l’objet « Requirement-vms », vous remarquerez que l’ID de méthode « 20 » correspond à la Verification Method « Rules », conformément à la liste des types de verification methods obtenue précédemment. Lorsque vous intégrez ces informations dans votre script, veillez à mapper l’ID de méthode au type de verification method correspondant.

En outre, dans l’objet « Requirement-vms », il existe des références à deux component-vms. Ces ID de component-vm représentent les Blocks attachés aux Requirement Verification Methods. Lorsque vous interagissez avec ces Blocks par programmation, utilisez ces ID dans votre script en conséquence.

L’endpoint pour accéder aux component-vms est

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

Lorsque vous obtenez les détails des component-vms, le champ component fournit l’ID du Block, avec lequel vous pouvez faire la correspondance avec le nom du Block.

Component-vms