17. API tích hợp và khóa API

API tích hợp cho phép chương trình, bảng tính hoặc tập lệnh của bạn tự động đọc dữ liệu dự án của bạn: danh sách dự án, bảng kê cáp và vật tư, bảng mạch và danh sách đầu nối của các tủ phân phối, bảng bóc khối lượng và việc lập bộ hồ sơ thiết kế. API chỉ đọc: nó không bao giờ thay đổi bản vẽ hay dự án.

Ai có thể nhận khóa API

Quyền truy cập API do đơn vị vận hành bật theo từng tài khoản. Khi tài khoản của bạn được cấp quyền, thẻ Khóa API sẽ xuất hiện trên trang Hồ sơ; nếu chưa có quyền, thẻ này bị ẩn. Một tài khoản có tối đa 5 khóa đang hoạt động cùng lúc.

Khóa thấy cùng những dự án như bạn: dự án của chính bạn và, khi có yêu cầu, những dự án được chia sẻ với bạn. Với dự án được chia sẻ, các bảng kê và bảng bóc khối lượng chỉ được trả về nếu việc chia sẻ cho phép xuất.

Tạo khóa

1. Trên thẻ Khóa API của trang Hồ sơ, nhấp Khóa mới.
2. Đặt tên cho khóa (ví dụ tên của chương trình sẽ dùng nó).
3. Chọn phạm vi: Đọc dự án cho danh sách dự án và dữ liệu dự án, Đọc tài liệu cho các bảng kê, bảng bóc khối lượng và bộ hồ sơ thiết kế. Chỉ chọn những gì chương trình thật sự cần.
4. Chọn thời hạn: 30, 90 hoặc 365 ngày. Khóa hết hạn sẽ ngừng hoạt động; hãy tạo khóa mới thay thế.
5. Nhập mật khẩu hiện tại của bạn (tài khoản không có mật khẩu cần đăng nhập gần đây). Với khóa đầu tiên, hãy chấp nhận điều khoản sử dụng API.

Sau khi tạo, khóa chỉ hiển thị một lần duy nhất: hãy sao chép và cất ở nơi an toàn. Về sau danh sách chỉ hiển thị tiền tố của khóa (avk_…), cùng ngày tạo và ngày hết hạn, lần dùng gần nhất và số lượt gọi. Chúng tôi cũng gửi thông báo qua e-mail về khóa mới (không kèm khóa).

Thu hồi khóa

Nút Thu hồi bên cạnh khóa sẽ làm khóa không dùng được ngay lập tức; không thể hoàn tác. Hãy thu hồi khóa khi bạn không còn dùng nó, khi ngừng chương trình đã dùng nó, hoặc khi nghi ngờ khóa bị lộ.

Lời khuyên về bảo mật

• Hãy coi khóa như mật khẩu của bạn: ai biết khóa đều có thể đọc dự án của bạn trong phạm vi đã cấp.
• Hãy lưu trong kho bí mật (trình quản lý mật khẩu, biến môi trường của máy chủ hoặc biến bí mật của CI), không để trong mã nguồn: đừng đưa vào kho git, bảng tính chia sẻ hay e-mail.
• Đừng dùng trong mã chạy trên trình duyệt (trang web, tiện ích mở rộng trình duyệt): ở đó ai cũng có thể đọc được. Khóa thuộc về máy chủ, tập lệnh hoặc chương trình máy tính.
• Hãy cấp cho mỗi chương trình một khóa riêng với phạm vi hẹp nhất và thời hạn ngắn, để thu hồi một khóa không làm dừng chương trình khác.

Sử dụng từ chương trình

Khóa được gửi trong tiêu đề yêu cầu dưới dạng Bearer token: Authorization: Bearer avk_…. Các điểm cuối nằm dưới /api/v1/ (ví dụ GET /api/v1/projects) và trả lời bằng JSON. Mô tả đầy đủ theo định dạng OpenAPI có tại /api/v1/openapi.json; hầu hết công cụ phát triển đều có thể nhập nó.

Số lượt gọi bị giới hạn theo từng khóa và từng tài khoản (mặc định 60 mỗi phút và 10.000 mỗi ngày); vượt mức này máy chủ trả lời 429, khi đó hãy chờ một chút. Đăng nhập trên trang web (cookie) không mở API, và khóa không đăng nhập bạn vào giao diện web.