Hướng dẫn bắt đầu nhanh về API Altium 365

API Altium 365 cung cấp cho bạn quyền truy cập theo chương trình vào dữ liệu Workspace của mình – dự án, BOM, linh kiện, symbol, footprint, v.v. Đây là một GraphQL API, nghĩa là bạn có thể truy vấn chính xác dữ liệu mình cần chỉ trong một yêu cầu duy nhất.

Hướng dẫn này sẽ giúp bạn đi từ con số 0 đến lệnh gọi API đầu tiên chỉ trong vài phút.

Điều kiện tiên quyết

• Một Workspace Altium 365

• Tài khoản quản trị viên Workspace

• Một tài khoản trên Altium Developer Center – cổng tự phục vụ của Altium dành cho nhà phát triển, nơi bạn có thể đăng ký các chương trình để truy cập API Altium 365, Altium Designer SDK, Embeddable Viewer và các sản phẩm dành cho nhà phát triển khác

Bước 1: Tạo Token

Để xác thực các yêu cầu API, bạn cần một access token. Token được tạo trong Workspace của bạn tại Admin → Developer.

Khi tạo token, bạn có thể chọn giữa hai tùy chọn sau.

Tùy chọn A: Access Token thời hạn dài

Cách đơn giản nhất để bắt đầu. Bạn sẽ nhận được một access token duy nhất với thời hạn có thể cấu hình (tối đa 1 năm). Sử dụng trực tiếp token này trong các yêu cầu API.

Phù hợp cho: khám phá nhanh, script và các tích hợp mà sự đơn giản được ưu tiên.

Xem Sử dụng access token để biết chi tiết.

Tùy chọn B: Refresh Token (Khuyến nghị cho môi trường production)

Một cách tiếp cận bảo mật hơn. Bạn sẽ nhận được một refresh token cùng với một client ID và client secret. Refresh token được trao đổi theo chương trình để lấy một access token thời hạn ngắn, sau đó access token này sẽ được dùng trong các yêu cầu API. Bản thân refresh token cũng có thời hạn có thể cấu hình (tối đa 1 năm).

Phù hợp cho: tích hợp tự động, dịch vụ nền và mọi thứ chạy trong môi trường production 24/7.

Xem Sử dụng Refresh Token để biết quy trình trao đổi token.

Bước 2: Thực hiện yêu cầu API đầu tiên của bạn

Cách nhanh nhất để khám phá API Altium 365 là thông qua IDE trình duyệt tích hợp sẵn (được hỗ trợ bởi Nitro). Điều hướng đến:

https://{workspace-domain}.altium.com/svc/napi/gateway/graphql/

Thay {workspace-domain} bằng domain Workspace thực tế của bạn (ví dụ: mycompany.altium.com).

Xác thực yêu cầu của bạn

Tất cả các yêu cầu API đều yêu cầu một access token được truyền trong header HTTP Authorization với scheme Bearer:

Authorization: Bearer {access-token}

Chạy truy vấn đầu tiên của bạn

Một truy vấn khởi đầu phù hợp là liệt kê các dự án trong Workspace của bạn:

query {
  desProjects(first: 10) {
    nodes {
      id
      name
      description
    }
  }
}

Dán truy vấn này vào IDE, nhấp vào Run, và bạn sẽ thấy các dự án Workspace của mình trong phản hồi.

Bạn cũng có thể khám phá toàn bộ schema API theo cách trực quan tại:

https://{workspace-domain}.altium.com/svc/napi/gateway/voyager/

Các bước tiếp theo

• Duyệt tổ chức GitHub AltiumDeveloper để xem các ứng dụng demo và truy vấn mẫu

• Xem Sử dụng Access Token để biết cách dùng token trong mã và script

• Xem Sử dụng Refresh Token cho các tích hợp tự động