Nexar API, Giải thích chi tiết: Đó là gì, hoạt động như thế nào và nó thay đổi điều gì đối với những người sử dụng nó

Trước hết, API là gì

API là viết tắt của application programming interface. Con người sử dụng website bằng cách nhấp và đọc. Chương trình thì không thể nhấp chuột, nên nó cần một “cửa sổ dịch vụ” để đặt một câu hỏi chính xác và nhận về một câu trả lời chính xác dưới định dạng mà nó hiểu được. “Cửa sổ” đó chính là API. Octopart là một website nơi người dùng của chúng tôi có thể tra cứu một linh kiện điện tử và xem thông tin của nó từ mọi góc độ. Thông tin này bao gồm nhà cung cấp nào đang có sẵn linh kiện trong kho, giá thành, trạng thái vòng đời, các thuộc tính kỹ thuật, v.v. Bạn thậm chí còn có thể tìm một linh kiện để xem những linh kiện nào khác tương tự với nó. Nexar API cung cấp chính những thông tin đó trực tiếp vào các hệ thống phần mềm nghiệp vụ của công ty bạn.

Lợi ích của việc sử dụng Nexar API

• Tích hợp vào các công cụ của riêng bạn: Bạn có thể nhúng dữ liệu cập nhật từ Nexar API trực tiếp vào các hệ thống nội bộ, chẳng hạn như hệ thống quản lý đơn đặt hàng tùy chỉnh hoặc hệ thống quản lý vòng đời sản phẩm.
• Không chỉ là dữ liệu nguồn cung: Bên cạnh thông tin nguồn cung, Nexar API còn truy xuất dữ liệu thiết kế từ các workspace Altium 365 của bạn, vì vậy chỉ với một lần tích hợp, bạn có thể kết hợp cả dữ liệu tìm nguồn cung ứng và dữ liệu thiết kế.
• Tính nhất quán giữa các nhóm: Bất kỳ ai dùng cùng một truy vấn cũng sẽ nhận về cùng một giá trị: cùng mức giá, cùng tồn kho và cùng đơn vị tại cùng một thời điểm. Các con số luôn có thể so sánh được giữa các cá nhân, giữa các báo cáo và theo thời gian.
• Tự động hóa ở quy mô lớn: Nexar API cho phép bạn truy vấn theo lập trình tối đa 100 linh kiện mỗi lần và thực hiện tối đa 300 truy vấn mỗi phút (tức có thể phân tích tới 30.000 linh kiện chỉ trong một phút!)

Nexar API

Nexar API chủ yếu bao gồm: 

• Dữ liệu nguồn cung là thông tin linh kiện của Octopart: phía dữ liệu nguồn cung của API cho phép truy cập hơn 95+ triệu linh kiện, với tồn kho, giá, trạng thái vòng đời, thời gian giao hàng, datasheet, thuộc tính kỹ thuật, mô hình CAD và gợi ý linh kiện tương tự, được lấy từ các nhà phân phối điện tử và cập nhật hằng ngày. 

• Dữ liệu thiết kế dành cho khách hàng Altium, bao quát nội dung trong các workspace thiết kế của bạn từ project đến chi tiết linh kiện. Nexar Data Model có giá trị công khai đặc biệt ở đây: Nexar Voyager. Trong data model, mỗi operation mang một tiền tố cho biết nó tác động tới phần nào: sup cho nguồn cung, des cho thiết kế, và adm cho quản trị tài khoản.

Ví dụ 1: bạn mô tả câu trả lời mình muốn nhận

Nexar sử dụng GraphQL, một ngôn ngữ truy vấn cho API. Với các hạ tầng API khác, bạn yêu cầu một khối dữ liệu cố định, nhận toàn bộ dữ liệu đó, rồi viết mã để loại bỏ phần mình không cần. Với GraphQL, bạn viết ra hình dạng của câu trả lời, và đúng hình dạng đó sẽ được trả về. Đây là dạng được tài liệu hóa cho tìm kiếm theo MPN (manufacturer part number):

query MpnSearch { 

  supSearchMpn { 

    results { part { id  name  mpn } } 

  } 

} 

Đọc theo nghĩa tự nhiên: hãy chạy tìm kiếm trên mã linh kiện của nhà sản xuất, cho tôi biết có bao nhiêu kết quả khớp, và với mỗi kết quả hãy trả về định danh, tên và MPN của linh kiện. Không có gì khác được trả về. Yêu cầu thêm thì bạn sẽ nhận thêm. Trong một buổi trình diễn trực tiếp của Altium, việc tìm một vi điều khiển RA0E2 thuộc họ Renesas RA đã trả về linh kiện đó; khi thêm thông số kỹ thuật thì xác nhận được rằng nó được đánh dấu là tuân thủ RoHS (hạn chế các chất nguy hại); khi thêm datasheet thì trả về liên kết đến tệp, tên tệp và ngày tạo, vì Octopart chấm điểm các datasheet hiện có và có thể trả về bản tốt nhất. Không có nội dung nào trong số đó được trả về trước khi nó được yêu cầu.

Ví dụ 2: nhiều cách tìm kiếm

Tương tự như Octopart, Nexar API rất linh hoạt về cách bạn có thể tìm kiếm một linh kiện. Nếu muốn thực hiện tìm kiếm rộng, bạn có thể tìm theo một phần của MPN hoặc tìm dựa trên từ khóa. Nếu bạn biết chính xác mình cần gì, thì có thể tìm theo MPN chính xác.

Đối với tìm kiếm rộng hơn, operation bạn nên sử dụng trong API là ‘supSearch’. Operation này sẽ thực hiện tìm kiếm fuzzy match.

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

Trong ví dụ trên, truy vấn “current sensor” sẽ trả về số lượng kết quả khớp, ID của các linh kiện, tên của chúng và mô tả ngắn của linh kiện. 

Operation ‘supMultiMatch’ nhận một danh sách tối đa 100 linh kiện, được nhận diện bằng MPN hoặc SKU (stock keeping unit), và đối sánh chúng cùng lúc. Không giống như ‘supSearch’, khi bạn sử dụng ‘SupMultiMatch’, mọi kết quả khớp một phần sẽ bị bỏ qua. Ví dụ này truy vấn hai linh kiện:

query MultiSearch { 

  supMultiMatch (queries: [ 

      {mpn: "SY55855VKG", limit: 1}, 

      {mpn: "BAV99-7-F"}, 

  ]) { hits  parts { id  name  mpn } } 

} 

Mỗi mục nhập có thể là một dòng trong BOM (bill of materials), vì vậy toàn bộ BOM có thể được báo giá mà không ai cần phải mở trình duyệt.

Ví dụ 3: phía thiết kế và ghi dữ liệu ngược trở lại

Phần thiết kế hoạt động theo cùng cách. Các operation có tiền tố des, chẳng hạn như ‘desWorkspaces’, sẽ truy cập vào các workspace Altium 365 của bạn. Vì dữ liệu được tổ chức theo dạng đồ thị, bạn sẽ lần theo các mối quan hệ từ bất kỳ điểm bắt đầu nào: từ một workspace đến các thiết kế bên trong nó, rồi từ một thiết kế đến những gì nó chứa, từ net và chi tiết linh kiện cho tới thông tin MCAD (mechanical computer-aided design) và vị trí. Bạn chọn đi sâu tới đâu và lấy bao nhiêu dữ liệu ở mỗi điểm.

Đọc dữ liệu mới chỉ là một nửa. Mutation là để ghi: thêm bình luận, tải project lên. Khi một operation cần tệp, trước tiên bạn tải tệp đó lên dịch vụ tệp của Nexar tại files.nexar.com/File/Upload, truyền kèm token có các scope design.domain, user.access và openid. Thứ được trả về là một định danh, có hiệu lực trong 24 giờ nếu chưa được sử dụng, và bạn sẽ tham chiếu đến nó trong chính request. Hãy coi định danh đó là dữ liệu opaque, vì định dạng của nó có thể thay đổi.

Điều này thay đổi công việc của bạn như thế nào

Giá trị của nó dễ thấy nhất khi nhìn vào cách ba vai trò hiện nay đang sử dụng thời gian của mình và phần nào trong quỹ thời gian đó được API hoàn trả lại.

Quản lý mua hàng hoặc người mua hàng

Tại một EMS (electronics manufacturing services provider) hoặc một OEM (original equipment manufacturer), người này xác nhận rằng mọi linh kiện trong một bản build đều còn hàng, tìm nhà phân phối có thể đáp ứng ngày giao hàng, nắm được mức giá và đặt đơn hàng. Khối lượng có thể chỉ là vài đơn mỗi tuần hoặc 50 đến 100 đơn mỗi ngày. Công việc thường được thực hiện theo kiểu từng linh kiện một từ bảng tính: nhập một MPN, kiểm tra tình trạng sẵn có, nhấp sang nhà phân phối rồi lặp lại. Các nhà phân phối được ủy quyền sẽ được kiểm tra trước, và chỉ khi không còn hàng thì mới mở rộng sang các broker không được ủy quyền. Nhiều người mua còn kiểm tra lại lần thứ hai ngay trước khi đặt hàng, phòng trường hợp có gì thay đổi chỉ sau một đêm.

Mỗi bước trong số đó đều có một tương đương ở trên. Một truy vấn API có thể thay thế một trăm lần tra cứu riêng lẻ. Việc dùng bộ lọc chỉ nhà phân phối được ủy quyền trong API cũng chính là cách biến tư duy “ưu tiên nguồn tin cậy trước, rồi mới mở rộng” thành một thiết lập thay vì một vòng tìm kiếm thủ công thứ hai. Việc kiểm tra lại trước khi đặt hàng trở thành một tác vụ chạy theo lịch và chỉ cảnh báo khi có điều gì đó thay đổi. Thứ được lấy lại không phải là năng lực phán đoán, vì điều đó vẫn thuộc về người mua, mà là thời gian gõ nhập và chuyển tab vốn đang tiêu tốn nó. Mức giá hợp đồng đã đàm phán trước vẫn thuộc về nhà phân phối, vì vậy API phục vụ cho việc lập danh sách rút gọn và phát hiện thay đổi, chứ không thay thế đơn đặt hàng.

Kỹ sư thiết kế

Tại một OEM, người này phụ trách vòng đời thiết kế điện từ sơ đồ khối, lựa chọn linh kiện, vẽ schematic, layout đến phát hành BOM. Ràng buộc cốt lõi của họ rất rõ ràng: một linh kiện không thể tìm mua được chính là một vấn đề thiết kế. Vì vậy Octopart được dùng như một bước xác thực, để trả lời câu hỏi “linh kiện này có thực sự mua được không, và có từ nhiều hơn một nguồn không?”, đồng thời cũng là công cụ khám phá để tìm và so sánh các ứng viên. Độ phủ nhà phân phối tự nó đã là một tín hiệu, bởi một linh kiện chỉ được một nhà phân phối tồn kho (hoặc có nhiều nhà phân phối nhưng tổng tồn kho giảm dần theo từng tuần) là một rủi ro chuỗi cung ứng ngay cả trước khi nó trở thành vấn đề mua hàng.

Khi thực hiện qua API, việc kiểm tra đó không còn là phản xạ làm từng linh kiện một mà trở thành một cổng kiểm soát. Mọi dòng trong BOM đều có thể được kiểm tra tại thời điểm phát hành, và bất kỳ mục nào chỉ có một nhà phân phối, tồn kho mỏng hoặc có cờ cảnh báo vòng đời đều có thể được đưa ra trước khi thiết kế được phê duyệt thay vì nhiều tháng sau. Nỗi lo mà điều này xử lý rất cụ thể và tốn kém: một linh kiện đi tới EOL (end of life) sau khi đã được thiết kế vào sản phẩm, buộc phải thiết kế lại. Datasheet cũng có thể được đưa vào công cụ nội bộ của bạn cùng lúc, dù các kỹ sư vẫn sẽ đối chiếu thông số với chính datasheet, và đó là điều nên làm.

Kỹ sư quản lý linh kiện

Có mặt tại các OEM quy mô vừa đến lớn, đặc biệt trong lĩnh vực hàng không vũ trụ, quốc phòng, ô tô và y tế, người này thường không tạo thiết kế mới. Họ quản lý các linh kiện đã có trong sản xuất: giữ cho thư viện linh kiện được phê duyệt luôn cập nhật, phát hiện nguy cơ lỗi thời trước khi nó trở thành khủng hoảng và đánh giá các phương án thay thế khi một linh kiện bị ngừng sản xuất. Các linh kiện có rủi ro được đưa vào danh sách theo dõi và được kiểm tra định kỳ, một phần vì đôi khi linh kiện đã ngừng sản xuất lại quay trở lại thị trường.

Danh sách theo dõi tự kiểm tra là điểm thắng rõ ràng nhất trong bài viết này. Thay vì phải có người nhớ quay lại xem lại một danh sách, một truy vấn theo lịch sẽ quét qua danh sách đó và báo cáo các ngoại lệ. Vì một ứng dụng có thể giữ đồng thời phạm vi nguồn cung và phạm vi thiết kế, thư viện có thể được đọc ở phía thiết kế và so sánh với dữ liệu thị trường trực tiếp ở phía nguồn cung trong cùng một lần chạy, biến một đợt kiểm tra thủ công định kỳ thành một báo cáo thường trực. Octopart vẫn đóng vai trò mở rộng đầu vào thay vì khép kín quy trình: các phương án thay thế tiềm năng và tình trạng sẵn có trên thị trường đến từ đây, trong khi việc xác minh hình dạng, độ phù hợp, chức năng, tuân thủ và vòng đời vẫn tiếp tục được thực hiện trong các công cụ PLM (quản lý vòng đời sản phẩm) và từ các nhà cung cấp dữ liệu chuyên biệt.

Điểm chung của cả ba

Không ai trong ba nhóm người dùng này muốn phải truy cập một website mới. Họ muốn câu trả lời xuất hiện ngay trong hệ thống mà họ đang làm việc; đúng vào thời điểm cần thiết, mà không cần ai đó phải đi tìm và lấy về. Đó chính là mục đích của API, và điều này khá gần với cách Nexar mô tả mục tiêu của mình: dân chủ hóa thông tin và kết nối mọi người để họ có thể làm việc hiệu quả hơn và đưa ra các quyết định kinh doanh thông minh hơn.

Thiết lập ban đầu

1. Đăng ký tại portal.nexar.com bằng địa chỉ email và mật khẩu, hoặc bằng thông tin đăng nhập Google, Facebook, hoặc Altium 365. Các tổ chức đã sử dụng SSO (đăng nhập một lần) với Altium 365 có thể đăng nhập theo cách đó.
2. Tạo hoặc tham gia một tổ chức. Bước này là bắt buộc. Để tham gia một tổ chức hiện có, hãy nhờ một thành viên gửi lời mời cho bạn.
3. Ngay sau khi đăng ký, sẽ có sẵn một ứng dụng ‘Evaluation’ được tạo sẵn để bạn sử dụng. Bạn có thể vào Apps và tạo thêm các ứng dụng khác nếu muốn.
4. Có một môi trường sandbox bên trong bảng điều khiển API cho phép bạn khám phá ngay lập tức. Khi đã sẵn sàng tích hợp dữ liệu vào công cụ hoặc ứng dụng của mình, bạn có thể chuyển đến tab Authorization và lấy thông tin xác thực.
5. Lấy client ID và client secret từ tab Authorization của ứng dụng. Đây là các thông tin xác thực tĩnh. Hãy bảo vệ secret như bảo vệ mật khẩu.
6. Đổi chúng lấy access token. Nexar sử dụng OAuth 2.0 (Open Authorization, phiên bản 2.0), và token có thời hạn 24 giờ. Các truy vấn nguồn cung sử dụng client credentials grant; các truy vấn design và adm sử dụng authorization code grant với các phạm vi OpenID, design.domain và user.access.

Bạn có thể chạy mọi ví dụ ở trên trong một trình biên tập GraphQL như Nitro (trước đây là Banana Cake Pop) hoặc Postman trước khi viết bất kỳ dòng mã ứng dụng nào. Các endpoint là api.nexar.com/graphql cho API, identity.nexar.com/connect/token cho token, và files.nexar.com/File/Upload cho tải lên. 

Nên đi tiếp từ đâu

Xem API hoạt động thực tế. Rob Barton, Head of Platform API tại Altium, trình bày quá trình phát triển API của Altium và chạy các truy vấn trực tiếp với dữ liệu nguồn cung Octopart trong podcast OnTrack: Altium API Deep Dive: Opening PCB Data to Developers trên YouTube.

Nghe tập này. OnTrack: The PCB Design Podcast, do Zach Peterson dẫn chương trình.

Khám phá mô hình dữ liệu. Nexar Voyager cung cấp biểu diễn trực quan của lược đồ GraphQL.

Đọc tài liệu. Tài liệu đầy đủ và bảng thuật ngữ hiện có tại support.nexar.com. Các ví dụ mã hoàn chỉnh được xuất bản trên GitHub NexarDeveloper.