Integración de la API y Code Assist Toolkit

Usa el kit de herramientas de integración de APIs y Code Assist para acelerar la migración a la API de Merchant y crear nuevas integraciones con herramientas de desarrollo potenciadas por IA.

Descripción general

Cuando migras de Content API for Shopping a la API de Merchant o creas una integración nueva, debes comprender las nuevas estructuras de servicio, los nombres de los recursos y los métodos. Las herramientas de desarrollo potenciadas por IA son especialmente adecuadas para ayudar con las siguientes operaciones:

  • Traducción y migración de código: Te ayuda a comprender y convertir el código heredado de Content API for Shopping al nuevo formato de la API de Merchant. Esto incluye asignar atributos de productos a la nueva estructura y actualizar los archivos de administración de dependencias.
  • Experiencia en documentación de la API: Proporciona explicaciones claras de los recursos, métodos, campos, cuotas y prácticas recomendadas de la API de Merchant en función del contexto autorizado de la documentación oficial de las APIs de Google.
  • Generación de código: Genera fragmentos de código para varias tareas de la API de Merchant en lenguajes como Python, Java, PHP y otros.
  • Solución de problemas: Ayuda a diagnosticar y corregir errores comunes de la API.

Elige la opción que mejor se adapte a tu entorno de desarrollo y a tu caso de uso específico. Usa el kit de herramientas de integración de APIs y Code Assist para adaptar la configuración a tu flujo de trabajo preferido:

En el siguiente diagrama, se ilustran las opciones de configuración para una migración de código asistida por IA en los entornos de desarrollo integrado (IDE) de uso frecuente, como Antigravity, Visual Studio Code, Cursor o Copilot. Es posible configurar asistentes de programación como Gemini, Claude, ChatGPT, Grok y potenciarlos con el servidor de MCP de la documentación para desarrolladores de la API de Merchant o las habilidades del agente de la API de Merchant para que tengan más fundamentos y, al mismo tiempo, acelerar la integración.

(API de Merchant) Diagrama de Gemini Code Assist para la integración de IA

Servidor de MCP de la documentación para desarrolladores de la API de Merchant

Obtén inteligencia contextual sobre la API de Merchant del asistente de programación que elijas. Dentro de tu IDE, ahora puedes acceder a la documentación para desarrolladores con el servicio del Protocolo de contexto del modelo (MCP). Este servicio proporciona información clave a tu asistente de programación de la documentación oficial de la API de Google. Para obtener más información sobre el protocolo en sí, consulta el estándar del Protocolo de contexto del modelo.

Cómo funciona

Cuando le haces una pregunta a tu asistente de programación del IDE habilitado para MCP sobre la API de Merchant, el servicio recupera los fragmentos de texto y código más relevantes de los recursos oficiales y los muestra como contexto a tu asistente de programación con un backend especializado de generación aumentada por recuperación (RAG). Un sistema RAG es aquel que mejora la calidad de las respuestas de los LLM conectándolos a fuentes de conocimiento externas y actualizadas. Esto permite que tu asistente proporcione respuestas precisas y actualizadas sin que tengas que salir de tu entorno de desarrollo.

Ejemplo de flujo de trabajo:

  1. Haces una pregunta en tu asistente de programación o agente compatible con MCP (p.ej., una pregunta en lenguaje natural, una solicitud de una muestra de código o una traducción de código).
  2. Tu asistente de programación envía una solicitud de contexto al extremo de MCP.
  3. El servicio de MCP busca en su colección indexada de documentación, guías y muestras de código oficiales de la API de Merchant.
  4. El servicio muestra fragmentos autorizados como contexto a tu asistente de programación.
  5. Tu asistente de programación aprovecha este contexto para generar una respuesta fundamentada o una tarea de traducción de código.

Cómo comenzar

Para integrar y usar MCP, sigue estos pasos:

1. Usa una herramienta compatible

Abre un IDE o un asistente de programación que admita el Protocolo de contexto del modelo con transporte HTTP transmisible.

2. Configura el extremo

Para conectar tu IDE o asistente de programación a MCP, usa los detalles del extremo remoto proporcionados, que pueden requerir que ingreses la URL directa del servicio o la definición de MCP, según la configuración de tu herramienta:

Configuraciones:

Antigravity

Sigue las instrucciones de la documentación de Antigravity.

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

Visual Studio Code

Sigue las instrucciones de la documentación de Visual Studio Code.

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

3. Agrega instrucciones del agente (opcional)

Para permitir que tu agente traduzca código directamente con MCP, proporciónale las instrucciones del sistema: Protocolo del agente integrador de Merchant. Estas instrucciones guían al agente sobre cómo utilizar correctamente MCP para la traducción de código. Según tu herramienta, puedes proporcionar estas instrucciones en la configuración de las instrucciones del sistema o como un archivo de contexto adicional para el agente.

Situaciones de ejemplo de uso

MCP puede acelerar tu flujo de trabajo en los siguientes casos de uso comunes:

Situación 1: Migra el código products.insert

Puedes pedirle al agente que migre directamente un código de integración products.insert de Content API for Shopping a la API de Merchant.

Instrucción del usuario:

"Migra el código products.insert a la API de Merchant"

Si le proporcionas a tu agente instrucciones del sistema y acceso a MCP, este podrá traducir el código de Content API for Shopping al código de la API de Merchant directamente en tu IDE. En este caso, identificará productInputs.insert como la llamada equivalente y asignará los atributos del producto del formato antiguo al formato nuevo que requiere la API de Merchant. También puede actualizar las importaciones requeridas y el archivo de administración de dependencias (por ejemplo, requirements.txt, pom.xml o package.json). Puedes indicarle al agente que realice los cambios en el lugar o que cree una carpeta nueva.

Situación 2: Encuentra una funcionalidad equivalente

Tienes una aplicación existente que usa Content API for Shopping y necesitas actualizarla. Puedes preguntar sobre un método heredado específico para obtener detalles sobre la nueva implementación y una muestra de código pertinente.

Instrucción del usuario:

"¿Cuál es el equivalente de la API de Merchant para el método accountstatuses.get en Content API for Shopping?"

El servicio de MCP proporciona contexto de las guías de migración oficiales y la documentación de referencia, lo que permite que tu asistente responda con una respuesta detallada, incluido el nuevo nombre de la API, accounts.issues.

Situación 3: Encuentra una muestra de código

Estás implementando una función nueva y necesitas un ejemplo práctico para seguir.

Instrucción del usuario:

Muéstrame una muestra de código de Python para agregar un nuevo servicio de envío con la API de Merchant.

El servicio de MCP recupera muestras de código pertinentes de los repositorios oficiales de GitHub de Google y las guías para desarrolladores. Luego, tu asistente puede presentar un bloque de código completo y listo para adaptar.

Situación 4: Comprende los conceptos de la API

Te encuentras con un concepto nuevo o quieres comprender la estructura de un recurso o el patrón general de la API de Merchant.

Instrucción del usuario:

"¿Cómo actualizo el inventario de un producto con la API de Merchant?"

El servicio de MCP muestra contexto de la documentación del recurso products y las guías pertinentes. Luego, tu asistente puede explicar cómo usar el método accounts.productInputs.insert y proporcionar el recurso de producto parcial que contiene solo el productId y los campos relacionados con el inventario que necesitas actualizar.

"¿Cómo autorizo las llamadas de mi aplicación con la API de Merchant?"

El servicio de MCP recupera contexto de las guías de autenticación oficiales, que abarcan diferentes métodos de autorización. Luego, tu asistente puede explicar las opciones principales disponibles, como usar una cuenta de servicio para las interacciones de servidor a servidor o un ID de cliente de OAuth 2.0 cuando actúas en nombre de un usuario.

Situación 5: Adáptate a los cambios de la API

La API de Merchant presenta patrones nuevos, como las solicitudes por lotes, que difieren de Content API for Shopping. Content API for Shopping usa métodos custombatch específicos, mientras que la API de Merchant usa una función genérica integrada de procesamiento por lotes de HTTP.

Instrucción del usuario:

"¿Cuál es la nueva forma de hacer un products.custombatch en la API de Merchant?"

El servicio de MCP recupera contexto de Refactoriza el código para solicitudes simultáneas , en el que se explica que no existen métodos custombatch dedicados en la API de Merchant. En cambio, proporciona documentación sobre el uso del procesamiento por lotes de HTTP con un Content-Type de multipart. Luego, tu asistente puede explicar cómo construir una sola solicitud HTTP que contenga varias llamadas a la API, enviadas al extremo https://merchantapi.googleapis.com/batch/{sub-api}/v1, y proporcionar un ejemplo de cómo estructurar la solicitud de varias partes. Esto convierte una tarea de migración potencialmente confusa en un proceso guiado.

Situación 6: Traduce una consulta de informes

Puedes pedirle al agente que traduzca una consulta de informes de Content API for Shopping a la API de Merchant.

Instrucción del usuario:

"Migra esta consulta de informes de Content API a la API de Merchant: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

El servicio de MCP recupera la documentación de referencia, las guías para desarrolladores y las guías de migración más recientes sobre informes. En función de esta información, transforma la consulta a la nueva estructura y actualiza los campos a sus nuevos nombres y valores.

Habilidades del agente de la API de Merchant

La especificación de habilidades del agente es un estándar abierto adoptado en las herramientas de desarrollo de IA. Usa las habilidades del agente para mejorar tu experiencia como desarrollador y optimizar la migración de Content API for Shopping y la creación de integraciones nuevas. Las habilidades del agente de la API de Merchant empaquetan conocimientos y herramientas específicos del dominio para mejorar las capacidades de los agentes de IA y proporcionan asistencia experta a pedido para consultas de documentación, generación de código y solución de problemas.

Las habilidades del agente de la API de Merchant son compatibles con varias herramientas de línea de comandos y IDE potenciados por IA, como Gemini y Claude Code.

Cómo funciona

Las habilidades del agente de la API de Merchant proporcionan un paquete de experiencia especializada basado en el estándar abierto de habilidades del agente. Nuestra habilidad del agente mapi-developer-assistant actúa como una capa inteligente entre tus herramientas de desarrollo de IA y el servidor de MCP de la documentación para desarrolladores de la API de Merchant subyacente. Incorpora experiencia en el dominio y orientación sobre procedimientos, y tiene las siguientes propiedades:

  • Configuración cero: Administra automáticamente las conexiones del servidor de MCP, lo que elimina la necesidad de configurar el extremo de forma manual.
  • Flujos de trabajo expertos: Refina las instrucciones del usuario en consultas optimizadas para recuperar la información más pertinente de manera eficaz.
  • Administración de contexto y eficiencia de tokens: Usa la "divulgación progresiva" para cargar información a pedido y preservar la ventana de contexto de la IA.
  • Formato de salida mejorado: Proporciona instrucciones para dar formato y estructurar la salida para obtener respuestas prácticas, legibles y coherentes.

Ejemplo de flujo de trabajo:

  1. Haces una pregunta sobre la API de Merchant en una herramienta de desarrollo de IA.
  2. La habilidad del agente de la API de Merchant analiza tu intención, formula una consulta precisa y aplica su conocimiento de procedimientos a la solicitud.
  3. La habilidad del agente envía una solicitud de contexto al servidor de MCP de la documentación para desarrolladores de la API de Merchant ubicado en merchantapi.googleapis.com/devdocs/mcp/.
  4. El servicio de MCP busca en su colección indexada de documentación, guías y muestras de código oficiales de la API de Merchant.
  5. Tu agente de IA aprovecha esta información para proporcionar una respuesta sintetizada y práctica.

Cómo comenzar

El archivo README de las habilidades del agente de la API de Merchant proporciona orientación paso a paso sobre lo siguiente:

  • Requisitos previos para herramientas como la herramienta de línea de comandos de Gemini
  • Cómo habilitar la compatibilidad con las habilidades del agente en la herramienta elegida
  • Cómo instalar la habilidad mapi-developer-assistant desde el repositorio de GitHub según las instrucciones del archivo README
  • Cómo verificar la instalación
  • Comandos básicos de administración de habilidades

Para obtener instrucciones detalladas de instalación y configuración de varias herramientas de IA, incluida la herramienta de línea de comandos de Gemini, Claude Code y otras, sigue las instrucciones del archivo README.

Ejemplos de instrucciones

Una vez instalada y habilitada en tus herramientas de desarrollo de IA, la habilidad mapi-developer-assistant suele activarse automáticamente cuando haces preguntas relacionadas con la API de Merchant.

"¿Cómo inserto un producto con la API de Merchant en Python?"

"¿Cuál es el equivalente de la API de Merchant para el método accountstatuses.get de Content API?"

Muéstrame un ejemplo de Java para controlar la autenticación con la API de Merchant.

"Recibo un error '400 Bad Request' con un error de validación cuando llamo a productInputs.insert. ¿Cómo lo corrijo?".

"¿Cuál es la diferencia entre ProductInput y Product en la API de Merchant?"

Fuentes de la base de conocimiento

El servicio de MCP crea su base de conocimiento exclusivamente a partir de fuentes públicas y oficiales para garantizar que el contexto que proporciona sea preciso y confiable. El servicio indexa todo el contenido del sitio oficial para desarrolladores y el repositorio de muestras de código, incluidos los siguientes elementos: