Documentação da API REST e da API Python

Este documento fornece a referência para a API REST do Requirements & Systems Portal. Ao utilizar a API REST, os utilizadores podem obter e modificar dados do Requirements & Systems Portal ou até escrever dados de volta no Requirements & Systems Portal e, assim, atualizar informação. Adicionalmente, isto dá-lhe a possibilidade de ligar/integrar com outras aplicações ou apps.

Aceder à API REST no Requirements & System Portal utilizando tokens

Para aceder à API REST na aplicação Requirements & Systems Portal no Altium A365, os utilizadores podem gerar os tokens navegando até ao menu Settings e selecionando User Tokens. Na página de definições User Tokens, encontrará o endereço da API para a sua implementação específica. Este endereço é necessário para efetuar chamadas à API.

Clique no ícone “+” na página User Tokens para gerar um novo token. Cada token é válido durante 3 months e tem de ser gerado novamente após expirar.

Ao consumir a API utilizando o access_token, é necessário adicionar um token através de um "Bearer ..." ao cabeçalho Authorization do pedido HTTP, usando o tipo de aplicação "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, utilizando requests, pode enviar o token de acesso desta forma

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)

Documentação da API Python

A Python API permite-lhe aceder e atualizar objetos na sua implementação com código Python.

Instale o pacote necessário da API Python com pip:

pip install valispace

Importe o módulo da API num script Python:

import valispace

e inicialize com

valispace = valispace.API()

Mais informações sobre as funcionalidades e funções da API podem ser encontradas aqui. O pacote da API Python está licenciado sob a licença MIT, o que significa que qualquer pessoa pode contribuir para o código clonando o repositório GitHub.

Endpoints

Os utilizadores podem aceder aos endpoints na página rest. Para aceder à página, adicione “rest/” no fim do URL da API, que pode ser encontrado no Requirements & Systems Portal em Settings e “User Tokens“. A página Rest mostra o Django Swagger com todos os endpoints existentes.

Existem métodos “GET”,” POST”,” PUT”,” PATCH” e “DELETE”.

Cada objeto no Requirements & Systems Portal tem o seu próprio ID; pode utilizá-lo para procurar e obter a informação do próprio objeto. O ID do objeto pode ser visto diretamente no Requirements & Systems Portal ou no URL ao clicar no objeto no Requirements & Systems Portal.

Por exemplo, se utilizar a função get para obter informação de vali através do rest, pode usar o seguinte endpoint para obter os detalhes do vali.

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

Utilizar GET para obter a informação do vali

Da mesma forma, pode utilizar os métodos para obter/atualizar ou publicar diferentes objetos, como Blocks, tags, valis, textvalis, requirements, specifications, verification methods, etc. Pode procurar os endpoints na página rest.

Filtrar objetos por projetos

Além da autenticação, pode utilizar o método "GET" para obter objetos como Valis ou Requirements dentro da implementação. Se precisar de filtrar os resultados com base num projeto específico, pode fazê-lo tirando partido das capacidades de filtragem, desde que o endpoint esteja configurado em conformidade. Por exemplo, para obter requirements associados ao projeto 24, pode utilizar o seguinte pedido GET:

GET /rest/requirements/?project=24

Esta funcionalidade é demonstrada no vídeo abaixo para uma compreensão mais clara.

Funções incorporadas

No Requirements & Systems Portal, sempre que um utilizador escreve texto no campo de texto, esse texto é guardado no backend em HTML
formato. O formato HTML mantém as referências de formatação a valis ou outros objetos. Assim, se estiver a obter a informação dos requirements, poderá receber o texto HTML na sua importação. Para evitar isto, implementámos duas funções que podem ser úteis para converter os campos HTML apenas em texto ou em formatação HTML com os valis convertidos em texto. As funções são clean_text e clean_html.

Função clean_text

A função clean_text converte todos os formatos HTML e referências a objetos dentro do campo em texto. No entanto, neste caso, a formatação também se perde. Por exemplo, a formatação também se perde se tiver uma lista, tabelas ou cor. Pode utilizá-la como mostrado abaixo.

Aqui, estou a aplicar o filtro ao projeto 24 e a pedir que devolva o texto limpo para o texto e a rationale do campo. O resultado seria este para esta ação específica.

Requirements após utilizar a função Clean_text

Função clean_html

A função clean_html mantém as opções de formatação do texto, mas converte as referências/objetos como valis em texto. Se o texto contiver opções de formatação como listas, cor de fundo, tabelas, etc., essa informação é mantida.

Requirements após utilizar a função clean_html

Perguntas frequentes:

Como encontrar o endpoint correto?

Navegar por inúmeros endpoints com nomes semelhantes pode ser confuso. Se alguma vez tiver dúvidas sobre um endpoint específico, recomendamos que contacte a nossa Página de Suporte Altium para esclarecimentos. Em alternativa, pode utilizar a funcionalidade "network" do seu navegador para observar quais os endpoints acionados ao executar ações no front end do software.

Como ilustração, considere o processo de criação de um Block. Neste caso, o endpoint associado pode ser identificado como um pedido "POST" para "/rest/components"; esta informação pode ser facilmente identificada ao inspecionar a atividade de rede durante a ação. Uma demonstração concisa desta abordagem é apresentada no breve vídeo abaixo.

Como obter/publicar os verification methods (VM) e Blocks de um requirement?

Um requirement no Requirements & Systems Portal pode estar associado a vários verification methods (VMs), cada um dos quais pode, por sua vez, ter vários Blocks anexados. São suportados vários tipos de verification method, incluindo rules, test, inspection, analyses, review e VMs personalizados. Cada tipo de verification method é identificado de forma única pelo seu próprio ID.

Pode utilizar o endpoint apropriado para obter os IDs destes tipos de verification method.

GET /rest/requirements/verification-methods/

Por exemplo, para obter os IDs dos tipos de Verification method para o projeto com ID 24, pode utilizar o seguinte endpoint

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

Lista de verification methods do projeto

Para obter os verification methods ligados a um requirement específico, o Requirements & Systems Portal cria um objeto dedicado conhecido como "Requirement-VMS". Este objeto tem o seu identificador único (ID), ao qual se pode aceder através do seguinte endpoint:

GET /rest/requirements/requirement-vms/

Por exemplo, este requirement, SPC-002 com ID 2165, tem um verification method do tipo “Rules”, e o ID do objeto de requirment-vms é 2203.

Se utilizarmos o endpoint, “/rest/requirements/requirement-vms/2203 ” obtemos a seguinte resposta.

Chaves e valores de requirment-vms

Ao inspecionar o objeto "Requirement-vms", irá notar que o ID do método "20" corresponde ao Verification Method "Rules", de acordo com a lista de tipos de verification method obtida anteriormente. Ao incorporar esta informação no seu script, certifique-se de que mapeia o ID do método para o respetivo tipo de verification method.

Além disso, dentro do objeto "Requirement-vms", existem referências a dois component-vms. Estes IDs de component-vm representam os Blocks anexados aos Requirement Verification Methods. Ao interagir com estes Blocks de forma programática, utilize estes IDs no seu script em conformidade.

O endpoint para aceder aos component-vms seria

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

Quando obtém os detalhes dos component-vms, o campo component fornece-lhe o ID do Block com o qual pode mapear o nome do Block.

Component-vms