Tài liệu về REST API và Python API

Trang này cung cấp tài liệu tham khảo cho REST API của Requirements Portal. Với REST API, bạn có thể lấy và sửa đổi dữ liệu từ Requirements Portal, hoặc thậm chí ghi dữ liệu trở lại Requirements Portal để cập nhật thông tin. Ngoài ra, API còn cho phép bạn kết nối/tích hợp với các ứng dụng khác.

Truy cập REST API trong Requirements Portal bằng token

Để truy cập REST API trong Requirements Portal, bạn có thể tạo token trên trang Settings – User Tokens (truy cập bằng cách nhấp vào biểu tượng  ở góc trên bên phải, chọn Settings từ menu xuất hiện, rồi chọn User Tokens từ danh sách trong ngăn bên trái). Trên trang này, bạn sẽ tìm thấy API address dành cho bản 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 + ở góc dưới bên phải của trang Settings – 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 với access_token, bạn cần thêm token theo dạng "Bearer ..." vào tiêu đề Authorization của yêu cầu HTTP, sử dụng kiểu ứng dụng "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
    }
}'

Hoặc khi sử dụng requests, bạn có thể gửi token truy cập 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 bản triển khai 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

Nhập mô-đun API vào một tập lệnh Python:

import valispace

và khởi tạo bằng

valispace = valispace.API()

Bạn có thể tìm thêm thông tin về các chức năng và hàm trong API 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 mã bằng cách sao chép kho lưu trữ GitHub.

Các điểm cuối

Người dùng có thể truy cập các điểm cuối trên trang Swagger. Để truy cập trang này, hãy thêm swagger/ vào cuối URL API có trên trang Settings – User Tokens. Trang này hiển thị Django Swagger cùng tất cả các điểm cuối hiện có.

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

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

Ví dụ, nếu dùng hàm GET để lấy thông tin lịch sử yêu cầu qua Swagger, bạn có thể dùng điểm cuối sau để lấy chi tiết lịch sử yêu cầu.

GET /rest/requirements/{requirement-id}/history/

Sử dụng GET để truy xuất thông tin lịch sử yêu cầu

Tương tự, bạn có thể dùng các phương thức để truy xuất/cập nhật hoặc gửi các đối tượng khác nhau như khối, thẻ, valis, textvalis, yêu cầu, đặc tả, phương pháp xác minh, v.v. Bạn có thể tìm các điểm cuối trên trang Swagger.

Lọc đối tượng theo dự án

Ngoài việc xác thực, bạn có thể dùng phương thức GET để truy xuất các đối tượng như Valis hoặc Yêu cầu trong bản triển khai. Nếu cần lọc kết quả theo một dự án cụ thể, bạn có thể tận dụng các khả năng lọc, miễn là điểm cuối được cấu hình phù hợp. Chẳng hạn, để truy xuất các yêu cầu liên quan đến dự án 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 để bạn dễ hiểu hơn.

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

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

Hàm clean_text

Hàm clean_text chuyển toàn bộ định dạng HTML và các 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 bị mất. Ví dụ, nếu nội dung có danh sách, bảng hoặc màu sắc, các định dạng này cũng sẽ bị mất. Bạn có thể sử dụng hàm như minh họa bên dưới.

Ở đây, tôi đang lọc theo dự án 24 và yêu cầu trả về văn bản thuần túy cho nội dung văn bản và lý do của trường. Kết quả của thao tác cụ thể này sẽ như sau.

Các yêu cầu sau khi sử 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 văn bản. Nếu văn bản có các tùy chọn định dạng như danh sách, màu nền, bảng, v.v., thông tin này sẽ được giữ lại.

Các yêu cầu sau khi sử dụng hàm clean_html

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

Làm thế nào để tìm đúng điểm cuối?

Việc tìm kiếm trong số nhiều điểm cuối 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 điểm cuối cụ thể, chúng tôi khuyến khích bạn liên hệ với Trang hỗ trợ Altium để được giải đáp. 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 những điểm cuối nào được gọi khi thực hiện các thao tác trên giao diện người dùng của phần mềm.

Ví dụ, hãy xem xét quy trình tạo một khối. Trong trường hợp này, điểm cuối tương ứng có thể được xác định là một yêu cầu "POST" đến "/rest/components". Bạn có thể dễ dàng nhận biết thông tin này bằng cách kiểm tra hoạt động mạng trong khi thực hiện thao tác. Video ngắn bên dưới minh họa ngắn gọn cách làm này.