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, связанная с поставками, предоставляет доступ к более чем 95 миллионам компонентов, включая наличие на складе, цены, статус жизненного цикла, сроки поставки, datasheet-файлы, технические характеристики, CAD-модели и рекомендации по похожим компонентам; эти данные поступают от электронных дистрибьюторов и обновляются ежедневно. 

• Проектных данных — для клиентов Altium, охватывающих содержимое ваших рабочих пространств проектирования: от проектов до сведений о компонентах. Здесь также полезна общедоступная модель данных Nexar: 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 поиск микроконтроллера RA0E2 из семейства Renesas RA вернул сам компонент; добавление технических спецификаций подтвердило, что он помечен как соответствующий требованиям RoHS (restriction of hazardous substances, ограничение содержания опасных веществ); добавление datasheet вернуло ссылку на файл, его название и дату создания, поскольку Octopart оценивает доступные datasheet-файлы и может вернуть лучший из них. Но ничего из этого не приходит, пока вы об этом не попросите.

Пример 2: несколько способов поиска

Как и Octopart, Nexar API гибок в отношении способов поиска компонента. Если вам нужен широкий поиск, можно искать по части MPN или по ключевым словам. Если вы точно знаете, что вам нужно, можно искать по точному MPN.

Для более широкого поиска в API следует использовать операцию ‘supSearch’. Эта операция выполняет нечеткий поиск совпадений.

query search { 

  supSearch (q: "Current sensor") { 

    hits 

    results { 

      part { 

        id 

        name 

        shortDescription 

      } 

    } 

  } 

} 

В приведенном выше примере поиск по запросу “current sensor” вернет количество совпадений, идентификаторы компонентов, их названия и краткое описание компонента. 

Операция ‘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 (mechanical computer-aided design) и позиционной информацией. Вы сами выбираете, насколько далеко идти и сколько данных из каждой точки забрать.

Чтение — это только половина возможностей. Mutation выполняет запись: добавление комментария, загрузку проекта. Если для операции нужен файл, сначала его нужно отправить в файловый сервис Nexar по адресу files.nexar.com/File/Upload, передав токен с областями действия design.domain, user.access и openid. В ответ возвращается идентификатор, действительный 24 часа, если он не был использован, на который затем ссылаются в самом запросе. Рассматривайте этот идентификатор как непрозрачный, поскольку его формат может измениться.

Что это меняет в вашей работе

Ценность проще всего увидеть, если посмотреть, как уже сейчас тратят свое время представители трех ролей и в какой части этого времени API дает отдачу.

Менеджер по закупкам или закупщик

В EMS (поставщик услуг контрактного производства электроники) или OEM (производитель оригинального оборудования) этот специалист проверяет, что все компоненты для сборки есть в наличии, находит дистрибьютора, который может уложиться в срок поставки, понимает цену и размещает заказ. Это может быть как несколько заказов в неделю, так и 50–100 в день. Обычно работа ведется по одному компоненту из таблицы: ввести один MPN, проверить доступность, перейти по ссылке к дистрибьютору и повторить. Сначала проверяются авторизованные дистрибьюторы, и только если на складе ничего нет, поиск расширяется на неавторизованных брокеров. Многие закупщики повторно проверяют данные непосредственно перед оформлением заказа — на случай, если за ночь что-то изменилось.

У каждого из этих шагов есть эквивалент выше. Один запрос API заменяет сотню отдельных поисков. Использование в API фильтра только по авторизованным поставщикам — это тот же принцип “сначала предпочтительные, затем расширять поиск”, только выраженный в виде настройки, а не второго круга ручного поиска. Повторная проверка перед заказом превращается в задачу, которая выполняется по расписанию и уведомляет только тогда, когда что-то изменилось. Возвращается не необходимость суждения — она остается за закупщиком, — а время, которое сейчас уходит на набор текста и переключение между вкладками. Заранее согласованные контрактные цены по-прежнему остаются на стороне дистрибьютора, поэтому API предназначен для предварительного отбора и отслеживания изменений, а не для замены заказа на поставку.

Инженер-разработчик

В OEM этот специалист отвечает за весь жизненный цикл электрического проектирования — от структурной схемы и выбора компонентов до захвата схемы, трассировки и выпуска BOM. Главное ограничение здесь предельно ясно: компонент, который невозможно закупить, — это проблема проекта. Поэтому Octopart используется как этап валидации, отвечающий на вопрос “можно ли вообще купить этот компонент и не в одном ли только месте?”, а также как инструмент поиска и сравнения кандидатов. Широта представленности у дистрибьюторов сама по себе служит сигналом, потому что компонент, который есть только у одного дистрибьютора (или у нескольких, но с общим снижением запасов из недели в неделю), представляет риск для цепочки поставок еще до того, как станет проблемой закупок.

Если выполнять эту проверку через API, она перестает быть реактивным действием по каждому компоненту и становится контрольной точкой. При выпуске можно проверить каждую строку BOM, а все компоненты с одним дистрибьютором, низкими запасами или флагом жизненного цикла можно выявить до утверждения проекта, а не спустя месяцы. Опасение, которое это снимает, вполне конкретно и дорого обходится: компонент достигает EOL (end of life) уже после включения в проект, что вынуждает выполнять перепроектирование. Datasheet-файлы тоже можно одновременно подтягивать в ваши собственные инструменты, хотя инженеры, разумеется, все равно будут сверять характеристики с самим datasheet — и так и должно быть.

Инженер по компонентам

Такой специалист встречается в средних и крупных OEM, особенно в аэрокосмической, оборонной, автомобильной и медицинской отраслях, и обычно не создает новые проекты. Он управляет компонентами, уже находящимися в производстве: поддерживает в актуальном состоянии библиотеку одобренных компонентов, выявляет устаревание до того, как оно станет кризисом, и квалифицирует альтернативы, когда компонент снимается с производства. Компоненты группы риска находятся в списке наблюдения, который периодически проверяется, отчасти потому, что снятый с производства компонент иногда снова появляется на рынке.

Самопроверяемый список наблюдения — самый очевидный выигрыш в этой статье. Вместо того чтобы кому-то приходилось помнить о необходимости снова просмотреть список, это делает запланированный запрос и сообщает об исключениях. Поскольку одно приложение может одновременно охватывать контуры поставок и проектирования, библиотеку можно считывать со стороны проектирования и сравнивать с актуальными рыночными данными со стороны поставок в рамках одного запуска, превращая периодический ручной аудит в постоянный отчёт. Octopart по-прежнему расширяет воронку, а не замыкает её: отсюда поступают кандидаты на замену и данные о доступности на рынке, тогда как проверка form, fit, function, compliance и lifecycle по-прежнему выполняется в инструментах PLM (product lifecycle management) и у специализированных поставщиков данных.

Что общего у всех трёх

Ни одна из этих ролей не хочет заходить на новый веб-сайт. Им нужно, чтобы ответ приходил прямо в ту систему, в которой они уже работают, именно в тот момент, когда это важно, без необходимости кому-то специально идти и искать эту информацию. Именно для этого и нужен API, и это близко к тому, как Nexar описывает собственное назначение: демократизировать информацию и объединять людей, чтобы они могли работать эффективнее и принимать более взвешенные бизнес-решения.

Начало работы

1. Зарегистрируйтесь на portal.nexar.com с помощью адреса электронной почты и пароля либо через Google, Facebook или учётные данные Altium 365. Организации, уже использующие SSO (single sign-on) с Altium 365, могут входить таким способом.
2. Создайте организацию или присоединитесь к существующей. Этот шаг обязателен. Чтобы присоединиться к уже существующей организации, попросите одного из её участников отправить вам приглашение.
3. Сразу после регистрации вам будет доступно преднастроенное приложение “Evaluation”. Вы можете перейти в Apps и при необходимости создать дополнительные приложения.
4. В панели API есть sandbox-среда, которая позволяет сразу приступить к изучению. Когда будете готовы интегрировать данные в свой инструмент или приложение, перейдите на вкладку Authorization и получите учётные данные для аутентификации.
5. Возьмите client ID и client secret на вкладке Authorization приложения. Это статические учётные данные. Обращайтесь с secret как с паролем.
6. Обменяйте их на токен доступа. Nexar использует OAuth 2.0 (Open Authorization, версия 2.0), а срок действия токенов составляет 24 часа. Для запросов, связанных с поставками, используется grant client credentials; для запросов design и adm — grant authorization code с областями OpenID, design.domain и user.access.

Перед тем как написать хотя бы одну строку кода приложения, вы можете выполнить все приведённые выше примеры в редакторе GraphQL, таком как Nitro (ранее Banana Cake Pop) или Postman. Эндпоинты: api.nexar.com/graphql для API, identity.nexar.com/connect/token для токенов и files.nexar.com/File/Upload для загрузок. 

Куда двигаться дальше

Посмотрите API в действии. Rob Barton, Head of Platform API в Altium, рассказывает об эволюции API Altium и выполняет живые запросы к данным о поставках Octopart в подкасте OnTrack: Altium API Deep Dive: Opening PCB Data to Developers на YouTube.

Послушайте выпуск. OnTrack: The PCB Design Podcast, ведущий — Zach Peterson.

Изучите модель данных. Nexar Voyager даёт визуальное представление схемы GraphQL.

Ознакомьтесь с документацией. Полная документация и глоссарий терминов доступны на support.nexar.com. Примеры рабочего кода опубликованы на GitHub NexarDeveloper.