Интеграция API и Code Assist Toolkit

Используйте API Integration and Code Assist Toolkit, чтобы ускорить перенос на Merchant API и создать новые интеграции с помощью инструментов разработки на основе искусственного интеллекта.

Обзор

При переходе с Content API for Shopping на Merchant API или создании новой интеграции необходимо разобраться в новых структурах сервисов, названиях ресурсов и методах. Инструменты разработки на основе искусственного интеллекта особенно хорошо подходят для следующих задач:

  • Трансляция и перенос кода. Помогает понять и преобразовать устаревший код Content API for Shopping в новый формат Merchant API. В частности, необходимо сопоставить атрибуты товаров с новой структурой и обновить файлы управления зависимостями.
  • Документация по API. Чат-бот предоставляет понятные объяснения ресурсов, методов, полей, квот и рекомендаций Merchant API на основе официальной документации Google API.
  • Генерация кода. Создание фрагментов кода для различных задач Merchant API на разных языках, включая Python, Java и PHP.
  • Устранение неполадок. Помогает диагностировать и устранять распространенные ошибки API.

Выберите вариант, который лучше всего подходит для вашей среды разработки и конкретного случая использования. Используйте API Integration and Code Assist Toolkit, чтобы настроить рабочий процесс:

На схеме ниже показаны варианты настройки переноса кода с помощью ИИ в наиболее распространенных интегрированных средах разработки (IDE), таких как Antigravity, Visual Studio Code, Cursor и Copilot. Вы можете настроить помощников по написанию кода, таких как Gemini, Claude, ChatGPT и Grok, и предоставить им доступ к серверу MCP с документацией для разработчиков Merchant API или навыкам агента Merchant API, чтобы повысить точность ответов и ускорить интеграцию.

Диаграмма интеграции ИИ-помощника в программировании (Merchant API)

Документация для разработчиков по Merchant API: MCP-сервер

Получайте контекстные подсказки о Merchant API от выбранного вами помощника в программировании. Теперь вы можете получить доступ к документации для разработчиков в IDE с помощью сервиса Model Context Protocol (MCP). Этот сервис передает вашему помощнику по программированию ключевую информацию из официальной документации по API Google. Подробную информацию о самом протоколе можно найти в стандарте Model Context Protocol.

Принцип работы

Когда вы задаете помощнику по помощи в программировании в IDE с поддержкой MCP вопрос о Merchant API, сервис извлекает наиболее релевантные фрагменты текста и кода из официальных ресурсов и возвращает их в качестве контекста вашему помощнику по помощи в программировании, используя специализированный бэкенд генерации с дополненной выборкой (RAG). Система RAG улучшает качество ответов LLM, подключая их к внешним актуальным источникам знаний. Это позволяет помощнику давать точные и актуальные ответы, а вам – не покидать среду разработки.

Пример рабочего процесса:

  1. Вы задаете вопрос помощнику по программированию или агенту, совместимому с MCP (например, вопрос на естественном языке, запрос на пример кода или трансляцию кода).
  2. Помощник в программировании отправляет запрос контекста конечной точке MCP.
  3. Сервис MCP выполняет поиск по проиндексированной коллекции официальной документации, руководств и примеров кода Merchant API.
  4. Сервис возвращает авторитетные фрагменты в качестве контекста для вашего помощника по программированию.
  5. Помощник в программировании использует этот контекст, чтобы сгенерировать обоснованный ответ или выполнить задачу по трансляции кода.

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

Чтобы интегрировать и использовать MCP, выполните следующие действия:

1. Используйте совместимый инструмент

Откройте интегрированную среду разработки или помощь в программировании, которая поддерживает Model Context Protocol с потоковой передачей по HTTP.

2. Настройте конечную точку

Чтобы подключить интегрированную среду разработки или помощь в программировании к MCP, используйте предоставленные сведения об удаленной конечной точке. В зависимости от конфигурации инструмента вам может потребоваться ввести прямой URL сервиса или определение MCP.

Варианты конфигурации:

Antigravity

Следуйте инструкциям в документации Antigravity.

"mcpServers": {
  "mapi-devdocs": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote",
      "https://merchantapi.googleapis.com/devdocs/mcp"
    ]
  }
}

Visual Studio Code

Следуйте инструкциям в документации Visual Studio Code.

"servers": {
"mapi-devdocs": {
  "type": "http",
  "url": "https://merchantapi.googleapis.com/devdocs/mcp/"
  }
}

3. Добавьте инструкции для агента (необязательно)

Чтобы агент мог напрямую переводить код с помощью MCP, предоставьте ему системные инструкции для агента Merchant Integrator. Эти инструкции помогают агенту правильно использовать MCP для трансляции кода. В зависимости от используемого инструмента вы можете предоставить эти инструкции либо в конфигурации системных инструкций, либо в виде дополнительного файла контекста для агента.

Примеры сценариев использования

MCP может ускорить вашу работу в следующих распространенных случаях:

Сценарий 1. Перенос кода products.insert

Вы можете попросить агента напрямую перенести код интеграции Content API for Shoppingproducts.insert в Merchant API.

Запрос пользователя:

"Перенесите код products.insert в Merchant API"

Если вы предоставите агенту системные инструкции и доступ к MCP, он сможет переводить код Content API for Shopping в код Merchant API прямо в вашей IDE. В этом случае он определит productInputs.insert как эквивалентный вызов и сопоставит атрибуты товара из старого формата с новым форматом, требуемым Merchant API. Он также может обновить необходимые импорты и файл управления зависимостями (например, requirements.txt, pom.xml или package.json). Вы можете поручить агенту внести изменения на месте или создать новую папку.

Сценарий 2. Поиск эквивалентных функций

У вас есть приложение, использующее Content API for Shopping, и вы хотите его обновить. Вы можете спросить о конкретном устаревшем методе, чтобы получить подробную информацию о новой реализации и соответствующий пример кода.

Запрос пользователя:

"Какой метод Merchant API соответствует методу accountstatuses.get в Content API for Shopping?"

Сервис MCP предоставляет контекст из официальных руководств по переносу и справочной документации, позволяя помощнику дать подробный ответ, включая новое название API – accounts.issues.

Сценарий 3. Поиск примера кода

Вы внедряете новую функцию и вам нужен практический пример.

Запрос пользователя:

"Покажи мне пример кода на Python для добавления новой службы доставки с помощью Merchant API".

Сервис MCP извлекает нужные примеры кода из официальных репозиториев Google на GitHub и руководств для разработчиков. Затем ваш помощник может представить полный, готовый к адаптации блок кода.

Сценарий 4. Понимание концепций API

Вы столкнулись с новым понятием или хотите понять структуру ресурса или общую схему Merchant API.

Запрос пользователя:

"Как обновить ассортимент товаров с помощью Merchant API?"

Сервис MCP возвращает контекст из документации по ресурсу products и соответствующих руководств. Затем помощник может объяснить, как использовать метод accounts.productInputs.insert, и предоставить частичный ресурс товара, содержащий только productId и поля, связанные с ассортиментом, которые необходимо обновить.

"Как авторизовать вызовы приложения с помощью Merchant API?"

Сервис MCP получает контекст из официальных руководств по аутентификации, в которых описаны разные способы авторизации. Затем помощник может объяснить основные доступные варианты, например использование сервисного аккаунта для взаимодействия между серверами или идентификатора клиента OAuth 2.0 при действиях от имени пользователя.

Сценарий 5. Адаптация к изменениям API

В Merchant API используются новые шаблоны, например пакетные запросы, которые отличаются от Content API for Shopping. В Content API for Shopping используются специальные методы custombatch, а в Merchant API – встроенная общая функция пакетной обработки HTTP.

Запрос пользователя:

"Как теперь выполнять products.custombatch в Merchant API?"

Сервис MCP извлекает контекст из статьи Рефакторинг кода для параллельных запросов, в которой объясняется, что в Merchant API нет специальных методов custombatch. Вместо этого в ней рассказывается, как использовать пакетную обработку HTTP с Content-Type multipart. Затем помощник может объяснить, как создать один HTTP-запрос, содержащий несколько вызовов API, отправленных в конечную точку https://merchantapi.googleapis.com/batch/{sub-api}/v1, и привести пример структуры составного запроса. Это превращает потенциально запутанную задачу миграции в управляемый процесс.

Сценарий 6. Перевод запроса отчета

Вы можете попросить агента перевести запрос отчета из Content API for Shopping в Merchant API.

Запрос пользователя:

"Перенесите этот запрос отчета из Content API в Merchant API: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

Сервис MCP получает последнюю справочную документацию по отчетам, руководства для разработчиков и руководства по переносу данных. На основе этой информации он преобразует запрос в новую структуру и обновляет поля, присваивая им новые названия и значения.

Навыки агента Merchant API

Спецификация навыков агента – это открытый стандарт, принятый в инструментах разработки ИИ. Используйте навыки агента, чтобы улучшить опыт разработки и оптимизировать как переход с Content API for Shopping, так и создание новых интеграций. Пакеты навыков агента Merchant API содержат знания и инструменты для конкретных областей, которые расширяют возможности ИИ-агентов и позволяют получать помощь экспертов по запросу, например при поиске информации в документации, генерации кода и устранении неполадок.

Навыки агента Merchant API совместимы с различными инструментами командной строки на основе искусственного интеллекта и интегрированными средами разработки, такими как Antigravity и Claude Code.

Принцип работы

Навыки агента Merchant API – это пакет специализированных знаний, созданный на основе открытого стандарта Agent Skills. Навык агента mapi-developer-assistant выступает в качестве интеллектуального слоя между вашими инструментами разработки ИИ и базовым MCP-сервером документации для разработчиков Merchant API. Она включает в себя экспертные знания в предметной области и процедурные рекомендации, обладая следующими свойствами:

  • Нулевая конфигурация. Автоматическое управление подключениями к MCP-серверу, устраняющее необходимость в ручной настройке конечных точек.
  • Экспертные рабочие процессы. Преобразует запросы пользователей в оптимизированные запросы для эффективного получения наиболее релевантной информации.
  • Управление контекстом и эффективное использование токенов. Использует прогрессивное раскрытие, чтобы загружать информацию по запросу и сохранять окно контекста ИИ.
  • Улучшенное форматирование выходных данных. Содержит инструкции по форматированию и структурированию выходных данных для получения практичных, читаемых и согласованных ответов.

Пример рабочего процесса:

  1. Вы задаете вопрос о Merchant API в инструменте разработки на основе ИИ.
  2. Навык агента Merchant API анализирует ваше намерение, формулирует точный запрос и применяет к нему свои процедурные знания.
  3. Навык агента отправляет запрос контекста на MCP-сервер документации для разработчиков Merchant API, расположенный по адресу merchantapi.googleapis.com/devdocs/mcp/.
  4. Сервис MCP выполняет поиск по проиндексированной коллекции официальной документации, руководств и примеров кода Merchant API.
  5. ИИ-агент использует эту информацию, чтобы предоставить обобщенный и полезный ответ.

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

В файле README для навыков агента Merchant API есть пошаговые инструкции по следующим вопросам:

  • Требования для таких инструментов, как инструмент командной строки Antigravity.
  • Включите поддержку навыков агента в выбранном инструменте.
  • Установка навыка mapi-developer-assistant из хранилища GitHub в соответствии с инструкциями в файле README.
  • Проверка установки.
  • Основные команды для управления навыками.

Подробные инструкции по установке и настройке различных ИИ-инструментов, включая инструмент командной строки Antigravity, Claude Code и другие, можно найти в файле README.

Примеры запросов

После установки и включения в инструментах разработки ИИ навык mapi-developer-assistant обычно активируется автоматически, когда вы задаете вопросы, связанные с Merchant API.

"Как добавить товар с помощью Merchant API в Python?"

"Какой метод Merchant API соответствует методу accountstatuses.get в Content API?"

"Покажи пример кода на Java для обработки аутентификации в Merchant API".

"При вызове productInputs.insert возникает ошибка 400: неверный запрос с ошибкой проверки. Как это исправить?"

"В чем разница между ProductInput и Product в Merchant API?"

Источники базы знаний

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