Nexar API 详解：它是什么、如何工作，以及它将为使用它的人带来哪些改变

首先，什么是 API

API 是 application programming interface（应用程序编程接口）的缩写。人们使用网站时，会通过点击和阅读来获取信息；但程序不能“点击”，因此它需要一个服务窗口，用来提出精确的问题，并以它能理解的格式获得精确的答案。这个窗口就是 API。Octopart 是一个网站，用户可以在上面查找电子元器件，并从各个维度查看相关信息。这些信息包括：哪些供应商有现货、价格、生命周期状态、技术属性等。你甚至还可以搜索某个元器件，查看哪些其他元器件与它相似。Nexar API 则把同样的信息直接提供给贵公司的业务软件系统。

使用 Nexar API 的优势

• 集成到你自己的工具中： 你可以将 Nexar API 中的最新数据直接嵌入内部系统，例如自定义的采购订单管理系统或产品生命周期管理系统。
• 不仅仅是供应数据： 除了供应信息，Nexar API 还可以从你的 Altium 365 工作区中提取设计数据，因此通过一次集成，就能同时获取采购与设计数据。
• 跨团队的一致性： 任何人使用相同的查询，都会得到相同的结果：同样的价格、同样的库存水平，以及同一时刻的同样单位。这样一来，不同人员、不同报表以及不同时间点之间的数据都可以保持可比性。
• 大规模自动化： Nexar API 支持你通过编程方式一次查询最多 100 个元器件，并且每分钟最多可执行 300 次查询（理论上单分钟可分析 30,000 个元器件！）

Nexar API

Nexar API 主要包括： 

• 供应数据 即 Octopart 的元器件信息：API 的供应侧可访问超过 9500 万个元器件的数据，包括库存、价格、生命周期状态、交期、数据手册、技术属性、CAD 模型以及相似元器件建议，这些数据来自电子分销商并每日更新。 

• 设计数据 面向 Altium 客户，涵盖你设计工作区中的内容，包括项目和元器件详情。Nexar Data Model 在这里也具有公开价值： Nexar Voyager。在这个数据模型中，每个操作都带有一个前缀，用来说明它作用的对象： sup 表示供应， des 表示设计， adm 表示账户管理。

示例 1：由你定义想要的返回结果

Nexar 使用 GraphQL，这是一种面向 API 的查询语言。使用其他 API 基础设施时，你通常会请求一整块固定的数据，接收全部内容后，再编写代码丢弃不需要的部分。而使用 GraphQL 时，你可以直接写出你希望返回结果的结构，最终返回的也正是这个结构。下面是按 MPN（manufacturer part number，制造商料号）搜索的文档化形式：

query MpnSearch { 

  supSearchMpn { 

    results { part { id  name  mpn } } 

  } 

} 

可以这样读出来：执行一次制造商料号搜索，告诉我命中了多少条结果，并且对于每条结果，返回该元器件的标识符、名称和 MPN。除此之外不会返回任何其他内容。你请求更多字段，就会得到更多字段。在一次 Altium 的现场演示中，搜索 Renesas RA 系列的 RA0E2 微控制器时，成功返回了该元器件；加入技术规格字段后，确认它被标记为符合 RoHS（有害物质限制）要求；再加入数据手册字段后，则返回了文件链接、文件名以及创建日期，因为 Octopart 会对可用的数据手册进行评分，并返回最优的那一份。所有这些内容，只有在被明确请求时才会返回。

示例 2：多种搜索方式

与 Octopart 类似，Nexar API 在元器件搜索方式上也非常灵活。如果你想做较宽泛的搜索，可以使用部分 MPN 或基于关键字进行搜索；如果你明确知道自己要找什么，则可以直接按精确 MPN 搜索。

对于较宽泛的搜索，你需要在 API 中使用的操作是“supSearch”。这个操作会执行模糊匹配搜索。

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

在上面的示例中，搜索 “current sensor” 将返回命中数量、元器件 ID、名称以及该元器件的简短描述。 

“supMultiMatch” 操作接收一个列表，最多可包含 100 个元器件，可通过 MPN 或 SKU（stock keeping unit，库存单位）标识，并将它们一起解析。与 “supSearch” 不同的是，使用 “supMultiMatch” 时，所有部分匹配都会被忽略。下面这个示例查询了两个元器件：

query MultiSearch { 

  supMultiMatch (queries: [ 

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

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

  ]) { hits  parts { id  name  mpn } } 

} 

列表中的每一项都可以对应 BOM（bill of materials，物料清单）中的一行，因此整份物料清单都可以直接完成价格查询，而无需任何人打开浏览器。

示例 3：设计侧以及将数据写回

设计侧的工作方式也是一样。带有 des 前缀的操作，例如 “desWorkspaces”，可以访问你的 Altium 365 工作区。由于数据的组织形式类似图结构，因此你可以从任意起点沿着关系向外追踪：从工作区到其中的设计，再从设计到其包含的内容，范围可涵盖网络、元器件详情，一直到 MCAD（机械计算机辅助设计）和位置信息。你可以自行决定遍历多深，以及每一层要带回多少信息。

读取只是其中一半，mutation 用于写入：比如添加评论、上传项目。当某个操作需要文件时，你需要先把文件上传到 Nexar 的文件服务 files.nexar.com/File/Upload，并传递一个包含 design.domain、user.access 和 openid 作用域的令牌。返回结果是一个标识符；如果未被使用，它会在 24 小时后失效；随后你需要在请求本身中引用这个标识符。请将这个标识符视为不透明值，因为它的格式可能会发生变化。

这会如何改变你的工作方式

要理解它的价值，最简单的方法就是看看三类角色目前是如何花费时间的，以及 API 能在哪些环节节省时间。

采购经理或采购员

在 EMS（electronics manufacturing services，电子制造服务提供商）或 OEM（original equipment manufacturer，原始设备制造商）中，这类人员需要确认生产所需的每个元器件都有库存，找到能够满足交付日期的分销商，了解价格，并下达订单。这个工作量可能是一周处理几张订单，也可能是一天处理 50 到 100 张。通常，这项工作是围绕电子表格逐个元器件完成的：输入一个 MPN，检查可得性，点进分销商页面，然后重复操作。首先会检查授权分销商；只有在没有现货时，才会把搜索范围扩大到非授权经纪商。很多采购人员还会在正式下单前立刻再检查一次，以防库存隔夜发生变化。

上述每一个步骤，在这里都有对应的 API 实现方式。一次 API 查询即可替代上百次单独查找。API 中的仅授权分销商筛选，相当于把“优先选择首选渠道，再逐步扩大范围”的习惯写成一个设置，而不是再次手动搜索。下单前的复查则可以变成一个按计划自动运行的任务，只有在发生变化时才发出提醒。API 节省下来的不是判断本身——判断仍然由采购人员来做——而是目前大量消耗判断力的输入和切换标签页操作。预先谈妥的合同价格依然掌握在分销商那里，因此 API 适用于候选筛选和变化监控，而不是用来取代采购订单。

设计工程师

在 OEM 中，这类人员负责电气设计生命周期的各个阶段，从框图、元器件选型、原理图绘制、布局布线到 BOM 发布。他们面临的核心约束非常直接：无法采购到的元器件，本身就是一个设计问题。因此，Octopart 常被用作验证环节，用来回答“这个元器件是否真的可以买到，而且是否能从不止一个渠道买到？”同时，它也是一个发现工具，用于寻找和比较候选器件。分销商覆盖面本身就是一个信号，因为如果某个元器件只有一家分销商备货（或者虽然有多家分销商，但总体库存连续数周下降），那么它在成为采购问题之前，就已经是供应链风险。

通过 API 来执行这项检查后，它就不再是逐个元器件的条件反射式动作，而会变成一道关卡。BOM 中的每一行都可以在发布时接受检查，任何只有单一分销商、库存偏薄或带有生命周期标记的问题，都能在设计签核之前暴露出来，而不是几个月后才发现。它所解决的担忧非常具体，而且代价高昂：某个元器件在被设计导入后进入 EOL（end of life，生命周期终止），从而被迫重新设计。同时，数据手册也可以被拉取到你自己的工具链中，不过工程师仍然会像本应如此的那样，以数据手册本身为准来核对规格。

元器件工程师

这类角色通常出现在中大型 OEM，尤其是在航空航天、国防、汽车和医疗行业。他们通常不负责创建新设计，而是管理已经投入生产的元器件：维护批准元器件库的最新状态，在淘汰风险演变成危机之前及时发现，并在某个元器件停产时评估替代件。存在风险的元器件会放在观察名单上，并定期检查，部分原因在于，已经停产的元器件有时也会重新回到市场。

本文中最明显的亮点，是一个可自检的观察清单。与其依赖某个人记得回头重新查看列表，不如通过定时查询去遍历它并报告异常。由于同一个应用程序可以同时承载供应和设计两个范围，因此在同一次运行中，既可以从设计侧读取库数据，也可以将其与供应侧的实时市场数据进行比对，从而把周期性的人工审核转变为持续性的报告。Octopart 仍然是用来打开筛选入口，而不是完成最终闭环：候选替代料和市场可得性信息来自这里，而外形、装配、功能、合规性以及生命周期验证，则仍然继续在 PLM（产品生命周期管理）工具和专业数据提供商中进行。

三者的共同点

这些不同角色都不是在要求去访问一个新网站。他们想要的是：答案能够直接出现在自己已经在使用的系统中；在真正需要的那一刻出现，而不是还得让人专门去查找。这正是 API 的用途，也与 Nexar 对自身使命的描述非常接近：让信息更普及、让人与人更容易协作，从而更高效地工作，并做出更明智的业务决策。

开始设置

1. 前往 portal.nexar.com ，使用电子邮件地址和密码注册，或使用 Google、Facebook 或 Altium 365 凭据登录。已经通过 Altium 365 使用 SSO（单点登录）的组织，也可以通过这种方式登录。
2. 创建或加入一个组织。 这是必需步骤。若要加入现有组织，请让其中一位成员邀请你。
3. 注册完成后，系统会立即为你提供一个预建的“Evaluation”应用程序供使用。如果需要，你可以进入 Apps 创建其他应用程序。
4. API 仪表板中内置了一个沙盒环境，方便你立即开始探索。当你准备好将数据集成到自己的工具或应用程序中时，可以前往 Authorization 选项卡获取身份验证凭据。
5. 从应用程序的 Authorization 选项卡中获取 client ID 和 client secret。它们是静态凭据。请像保护密码一样保护 secret。
6. 用它们换取 access token。 Nexar 使用 OAuth 2.0（开放授权 2.0），token 的有效期为 24 小时。供应查询使用 client credentials grant；design 和 adm 查询则使用 authorization code grant，并带有 OpenID、design.domain 和 user.access 作用域。

在编写任何一行应用程序代码之前，你都可以先在 GraphQL 编辑器中运行上面的所有示例，例如 Nitro（原 Banana Cake Pop）或 Postman。相关端点分别是：API 使用 api.nexar.com/graphql，token 使用 identity.nexar.com/connect/token，上传使用 files.nexar.com/File/Upload。 

下一步去哪里

观看 API 的实际演示。Altium 平台 API 负责人 Rob Barton 在 OnTrack 播客中讲解了 Altium API 的演进，并现场运行了针对 Octopart 供应数据的查询： YouTube 上的 Altium API Deep Dive: Opening PCB Data to Developers。

收听这一期节目。 OnTrack: The PCB Design Podcast，由 Zach Peterson 主持。

探索数据模型。 Nexar Voyager 以可视化方式展示 GraphQL schema。

阅读文档。完整文档和术语表可在 support.nexar.com 获取。带示例的代码已发布在 NexarDeveloper GitHub 上。