Tài liệu API Rest và API Python

Tài liệu này cung cấp tài liệu tham chiếu cho REST API của Requirements & Systems Portal. Sử dụng REST API, người dùng có thể lấy và chỉnh sửa dữ liệu từ Requirements & Systems Portal hoặc thậm chí ghi dữ liệu ngược trở lại Requirements & Systems Portal để cập nhật thông tin. Ngoài ra, điều này cũng cho phép bạn kết nối/tích hợp với các ứng dụng hoặc app khác.

Truy cập Rest API trong Requirements & System Portal bằng token

Để truy cập REST API trong ứng dụng Requirements & Systems Portal trên Altium A365, người dùng có thể tạo token bằng cách đi tới menu Settings và chọn User Tokens. Trong trang cài đặt User Tokens, bạn sẽ tìm thấy địa chỉ API dành cho triển khai cụ thể của mình. Địa chỉ này là cần thiết để thực hiện các lệnh gọi API.

Nhấp vào biểu tượng “+” trên trang User Tokens để tạo token mới. Mỗi token có hiệu lực trong 3 months và phải được tạo lại sau khi hết hạn.

Để sử dụng API bằng access_token, cần thêm token dưới dạng "Bearer ..." với loại ứng dụng "JSON" vào header Authorization của yêu cầu HTTP.

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

hoặc khi dùng requests, bạn có thể gửi access token như sau

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)

Tài liệu Python API

Python API cho phép bạn truy cập và cập nhật các đối tượng trong deployment của mình bằng mã python.

Cài đặt gói python API cần thiết bằng pip:

pip install valispace

Import mô-đun API trong một script python:

import valispace

và khởi tạo bằng

valispace = valispace.API()

Thông tin thêm về các khả năng và hàm trong API có thể được tìm thấy tại đây. Gói python API được cấp phép theo giấy phép MIT, nghĩa là bất kỳ ai cũng có thể đóng góp vào mã bằng cách clone kho lưu trữ GitHub.

Endpoints

Người dùng có thể truy cập các endpoint trên trang rest. Để truy cập trang này, hãy thêm “rest/” vào cuối URL API có thể tìm thấy trong Requirements & Systems Portal dưới Settings và “User Tokens“. Trang Rest hiển thị Django Swagger với tất cả các endpoint hiện có.

Có các phương thức “GET”,” POST”,” PUT”,” PATCH” và “DELETE”.

Mỗi đối tượng trong Requirements & Systems Portal đều có ID riêng; bạn có thể dùng ID đó để tìm kiếm và lấy chính thông tin của đối tượng. ID đối tượng có thể được xem trực tiếp trong Requirements & Systems Portal hoặc trong URL khi nhấp vào đối tượng trong Requirements & Systems Portal.

Ví dụ, nếu bạn dùng hàm get để lấy thông tin vali thông qua rest, bạn có thể dùng endpoint sau để lấy chi tiết vali.

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

Sử dụng GET để lấy thông tin của vali

Tương tự, bạn có thể dùng các phương thức để truy xuất/cập nhật hoặc đăng các đối tượng khác nhau như Blocks, tags, valis, textvalis, requirements, specifications, verification methods, v.v. Bạn có thể tìm các endpoint trên trang rest.

Lọc đối tượng cho project

Ngoài xác thực, bạn có thể dùng phương thức "GET" để lấy các đối tượng như Valis hoặc Requirements trong deployment. Nếu cần lọc kết quả theo một project cụ thể, bạn có thể thực hiện điều này bằng cách tận dụng khả năng lọc, miễn là endpoint được cấu hình phù hợp. Ví dụ, để lấy các requirement liên quan đến project 24, bạn có thể dùng yêu cầu GET sau:

GET /rest/requirements/?project=24

Chức năng này được minh họa trong video bên dưới để giúp bạn hiểu rõ hơn.

Các hàm tích hợp sẵn

Trong Requirements & Systems Portal, bất cứ khi nào người dùng nhập văn bản vào trường text, văn bản sẽ được lưu ở backend dưới
định dạng HTML. Định dạng HTML giữ lại các tham chiếu định dạng tới valis hoặc các đối tượng khác. Vì vậy, nếu bạn đang lấy thông tin requirement, bạn có thể nhận được văn bản HTML trong dữ liệu import của mình. Để tránh điều này, chúng tôi đã triển khai hai hàm hữu ích để chuyển đổi các trường HTML thành chỉ văn bản thuần hoặc HTML với các vali được chuyển thành text. Hai hàm đó là clean_text và clean_html.

Hàm Clean_text

Hàm clean text chuyển đổi tất cả định dạng HTML và tham chiếu đối tượng trong trường thành văn bản. Tuy nhiên, trong trường hợp này, định dạng cũng sẽ bị mất. Ví dụ, nếu bạn có danh sách, bảng hoặc màu sắc thì định dạng cũng sẽ bị mất. Bạn có thể dùng như minh họa bên dưới.

Ở đây, tôi đang lọc cho project 24 và yêu cầu trả về clean text cho text và rationale của trường. Đầu ra cho thao tác cụ thể này sẽ là như sau.

Requirements sau khi dùng hàm Clean_text

Hàm Clean_html

Hàm clean_html giữ lại các tùy chọn định dạng của văn bản nhưng chuyển các tham chiếu/đối tượng như valis thành text. Nếu văn bản chứa các tùy chọn định dạng như danh sách, màu nền, bảng, v.v., thì thông tin này sẽ được giữ lại.

Requirements sau khi dùng hàm clean_html

Câu hỏi thường gặp:

Làm thế nào để tìm đúng endpoint?

Việc điều hướng qua nhiều endpoint có tên tương tự nhau có thể gây nhầm lẫn. Nếu bạn không chắc chắn về một endpoint cụ thể, chúng tôi khuyến khích bạn liên hệ Altium Support Page để được làm rõ. Ngoài ra, bạn có thể tận dụng tính năng "network" của trình duyệt để quan sát endpoint nào được kích hoạt khi thực hiện thao tác trong giao diện người dùng của phần mềm.

Ví dụ, hãy xem quá trình tạo một Block. Trong trường hợp này, endpoint tương ứng có thể được xác định là một yêu cầu "POST" tới "/rest/components"; thông tin này có thể dễ dàng nhận ra bằng cách kiểm tra hoạt động mạng trong lúc thực hiện thao tác. Một minh họa ngắn gọn cho cách tiếp cận này được cung cấp trong video ngắn bên dưới.

Làm thế nào để lấy/đăng verification methods(VM) và Blocks của một requirement?

Một requirement trong Requirements & Systems Portal có thể được liên kết với nhiều verification method (VM), và mỗi verification method đó lại có thể gắn với nhiều Block. Hệ thống hỗ trợ nhiều loại verification method khác nhau, bao gồm rules, test, inspection, analyses, review và VM tùy chỉnh. Mỗi loại verification method được xác định duy nhất bằng ID riêng.

Bạn có thể dùng endpoint phù hợp để lấy ID của các loại verification method này.

GET /rest/requirements/verification-methods/

Ví dụ, để lấy ID của các loại Verification method cho project id 24, bạn có thể dùng endpoint sau

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

Danh sách verification method của project

Để lấy các verification method được liên kết với một requirement cụ thể, Requirements & Systems Portal tạo ra một đối tượng chuyên biệt gọi là "Requirement-VMS." Đối tượng này có mã định danh (ID) riêng, có thể được truy cập qua endpoint sau:

GET /rest/requirements/requirement-vms/

Ví dụ, requirement này, SPC-002 với ID 2165 có một verification method thuộc loại “Rules”, và object id của requirment-vms là 2203.

Nếu chúng ta dùng endpoint “/rest/requirements/requirement-vms/2203 ” thì sẽ nhận được phản hồi sau.

Các khóa và giá trị của Requirment-vms

Khi kiểm tra đối tượng "Requirement-vms", bạn sẽ thấy method ID "20" tương ứng với Verification Method "Rules", theo danh sách các loại verification method đã lấy trước đó. Khi đưa thông tin này vào script của bạn, hãy đảm bảo rằng bạn ánh xạ method ID tới đúng loại verification method tương ứng.

Ngoài ra, bên trong đối tượng "Requirement-vms" còn có tham chiếu đến hai component-vms. Các ID component-vm này đại diện cho các Block được gắn với Requirement Verification Methods. Khi tương tác với các Block này theo cách lập trình, hãy sử dụng các ID này tương ứng trong script của bạn.

Endpoint để truy cập component-vms sẽ là

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

Khi bạn lấy chi tiết của component-vms, trường component sẽ cung cấp Block id để bạn có thể ánh xạ tới tên của Block.

Component-vms