Hướng Dẫn Bắt Đầu Nhanh về API Altium 365

API Altium 365 cho phép bạ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, ký hiệu, footprint, v.v. Đây là API GraphQL, 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 bắt đầu từ con số 0 đến cuộc 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, SDK Altium Designer, 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à tích hợp khi ưu tiên sự đơn giản.

Xem Using an Access token để biết chi tiết.

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

Cách tiếp cận an toàn hơn. Bạn sẽ nhận được một refresh token cùng với client ID và client secret. Refresh token được trao đổi theo chương trình để lấy access token thời hạn ngắn, sau đó được dùng trong các yêu cầu API. Bản thân refresh token 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 production 24/7.

Xem Using a Refresh Token để biết luồng trao đổi.

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 cung cấp bởi Nitro). Điều hướng đến:

https://{workspace-domain}.altium.com/api/graphql/

Thay {workspace-domain} bằng tên miền 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 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 đó 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 một cách trực quan tại:

https://{workspace-domain}.altium.com/api/voyager

Các bước tiếp theo

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

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

• Xem Using a Refresh Token cho các tích hợp tự động