Integração de API e kit de ferramentas do Code Assist

Use a integração de APIs e o kit de ferramentas do Code Assist para acelerar sua migração para a API Merchant e criar novas integrações com ferramentas para desenvolvedores com tecnologia de IA.

Visão geral

Ao migrar da API Content for Shopping para a API Merchant ou criar uma nova integração, é preciso entender as novas estruturas de serviço, nomes de recursos e métodos. As ferramentas para desenvolvedores com tecnologia de IA são particularmente adequadas para ajudar nas seguintes operações:

  • Tradução e migração de código: ajuda você a entender e converter o código legado da API Content for Shopping para o novo formato da API Merchant. Isso inclui mapear os atributos do produto para a nova estrutura e atualizar os arquivos de gerenciamento de dependências.
  • Conhecimento da documentação da API: fornece explicações claras sobre os recursos, métodos, campos, cotas e práticas recomendadas da API Merchant com base no contexto oficial da documentação da API do Google.
  • Geração de código: gera snippets de código para várias tarefas da API Merchant em linguagens como Python, Java, PHP, entre outras.
  • Solução de problemas: ajuda a diagnosticar e corrigir erros comuns da API.

Escolha a opção que melhor se adapta ao seu ambiente de desenvolvimento e caso de uso específico. Use a integração de API e o kit de ferramentas do Code Assist para adaptar a configuração ao seu fluxo de trabalho preferido:

O diagrama a seguir ilustra as opções de configuração para uma migração de código assistida por IA nos ambientes de desenvolvimento integrado (IDEs) mais usados com frequência, como Antigravity, Visual Studio Code, Cursor ou Copilot. É possível configurar assistentes de programação, como Gemini, Claude, ChatGPT e Grok, e capacitá-los com o servidor MCP da documentação para desenvolvedores da API Merchant ou com as habilidades de agente da API Merchant para que sejam mais fundamentados e aumentem a velocidade de integração.

Diagrama do Assistente de Código de Integração de IA (API Merchant)

Servidor MCP da documentação para desenvolvedores da API Merchant

Receba inteligência contextual sobre a API Merchant do assistente de programação que você preferir. No seu ambiente de desenvolvimento integrado, agora é possível acessar a documentação para desenvolvedores usando o serviço do Protocolo de Contexto de Modelo (MCP). Esse serviço fornece ao assistente de programação informações importantes da documentação oficial da API do Google. Para mais informações sobre o protocolo, consulte o padrão do Protocolo de Contexto de Modelo.

Como funciona

Quando você faz uma pergunta sobre a API Merchant ao assistente de programação do IDE com MCP, o serviço recupera os snippets de texto e código mais relevantes dos recursos oficiais e os retorna como contexto para o assistente de programação usando um back-end especializado de geração aumentada por recuperação (RAG). Um sistema de RAG melhora a qualidade das respostas de LLMs ao conectá-los a fontes de conhecimento externas e atualizadas. Assim, o assistente pode fornecer respostas precisas e atualizadas sem que você precise sair do ambiente de desenvolvimento.

Exemplo de fluxo de trabalho:

  1. Você faz uma pergunta no seu assistente de programação ou agente compatível com o MCP (por exemplo, uma pergunta em linguagem natural, uma solicitação de exemplo de código ou uma tradução de código).
  2. Seu assistente de programação envia uma solicitação de contexto para o endpoint do MCP.
  3. O serviço MCP pesquisa a coleção indexada de documentação, guias e exemplos de código oficiais da API Merchant.
  4. O serviço retorna snippets confiáveis como contexto para seu assistente de programação.
  5. Seu assistente de programação usa esse contexto para gerar uma resposta fundamentada ou uma tarefa de tradução de código.

Primeiros passos

Para integrar e usar o MCP, siga estas etapas:

1. Usar uma ferramenta compatível

Abra um ambiente de desenvolvimento integrado ou um assistente de programação que ofereça suporte ao Protocolo de Contexto de Modelo com transporte HTTP de streaming.

2. Configurar o endpoint

Para conectar seu ambiente de desenvolvimento integrado ou assistente de programação ao MCP, use os detalhes do endpoint remoto fornecidos, que podem exigir que você insira o URL de serviço direto ou a definição do MCP, dependendo da configuração da ferramenta:

Configurações:

Antigravity

Siga as instruções na documentação do Antigravity.

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

Visual Studio Code

Siga as instruções na documentação do Visual Studio Code.

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

3. Adicionar instruções do agente (opcional)

Para permitir que o agente traduza o código diretamente usando o MCP, forneça as Instruções do sistema: protocolo do agente integrador do Merchant. Essas instruções orientam o agente sobre como usar corretamente o MCP para tradução de código. Dependendo da ferramenta, é possível fornecer essas instruções na configuração de instruções do sistema ou como um arquivo de contexto adicional para o agente.

Exemplos de cenários de uso

O MCP pode acelerar seu fluxo de trabalho nos seguintes casos de uso comuns:

Cenário 1: migrar o código do products.insert

Peça ao agente para migrar diretamente um código de integração da API Content for Shopping products.insert para a API Merchant.

Comando do usuário:

"Migrar o código products.insert para a API Merchant"

Ao fornecer instruções do sistema e acesso ao MCP, seu agente pode traduzir o código da API Content for Shopping para o código da API Merchant diretamente no seu ambiente de desenvolvimento integrado. Nesse caso, ela vai identificar productInputs.insert como a chamada equivalente e mapear os atributos do produto do formato antigo para o novo formato exigido pela API Merchant. Ele também pode atualizar as importações necessárias e o arquivo de gerenciamento de dependências (por exemplo, requirements.txt, pom.xml ou package.json). Você pode instruir o agente a fazer as mudanças no local ou criar uma nova pasta.

Cenário 2: encontrar uma funcionalidade equivalente

Você tem um aplicativo que usa a API Content for Shopping e precisa atualizá-lo. Você pode perguntar sobre um método legado específico para receber detalhes sobre a nova implementação e um exemplo de código relevante.

Comando do usuário:

"Qual é o equivalente da API Merchant para o método accountstatuses.get na API Content for Shopping?"

O serviço MCP fornece contexto dos guias de migração oficiais e da documentação de referência, permitindo que o assistente responda com uma resposta detalhada, incluindo o novo nome da API, accounts.issues.

Cenário 3: encontrar um exemplo de código

Você está implementando um novo recurso e precisa de um exemplo prático para seguir.

Comando do usuário:

"Mostre um exemplo de código Python para adicionar um novo serviço de frete usando a API Merchant."

O serviço MCP recupera exemplos de código relevantes dos repositórios oficiais do Google no GitHub e dos guias para desenvolvedores. O assistente pode apresentar um bloco de código completo, pronto para ser adaptado.

Cenário 4: entender os conceitos de API

Você se depara com um novo conceito ou quer entender a estrutura de um recurso ou o padrão geral da API Merchant.

Comando do usuário:

"Como faço para atualizar o inventário de um produto usando a API Merchant?"

O serviço MCP retorna o contexto da documentação de recursos dos produtos e dos guias relevantes. O assistente pode explicar como usar o método accounts.productInputs.insert e fornecer o recurso de produto parcial que contém apenas o productId e os campos relacionados ao inventário que você precisa atualizar.

"Como autorizo as chamadas do meu aplicativo com a API Merchant?"

O serviço MCP recupera o contexto dos guias de autenticação oficiais, que abrangem diferentes métodos de autorização. O assistente pode explicar as principais opções disponíveis, como usar uma conta de serviço para interações de servidor para servidor ou um ID do cliente OAuth 2.0 ao agir em nome de um usuário.

Cenário 5: adaptação às mudanças na API

A API Merchant apresenta novos padrões, como solicitações em lote, que são diferentes da API Content for Shopping. A API Content for Shopping usa métodos custombatch específicos, enquanto a API Merchant usa um recurso de lote HTTP genérico integrado.

Comando do usuário:

"Qual é a nova maneira de fazer um products.custombatch na API Merchant?"

O serviço MCP recupera o contexto de Refatorar o código para solicitações simultâneas, explicando que os métodos custombatch dedicados não existem na API Merchant. Em vez disso, ela fornece documentação sobre o uso de lotes HTTP com um Content-Type de multipart. O assistente pode explicar como criar uma única solicitação HTTP com várias chamadas de API, enviada para o endpoint https://merchantapi.googleapis.com/batch/{sub-api}/v1, e fornecer um exemplo de como estruturar a solicitação de várias partes. Isso transforma uma tarefa de migração potencialmente confusa em um processo guiado.

Cenário 6: traduzir uma consulta de relatório

Você pode pedir ao agente para traduzir uma consulta de relatórios da API Content for Shopping para a API Merchant.

Comando do usuário:

"Migre esta consulta de relatórios da API Content para a API Merchant: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

O serviço MCP recupera a documentação de referência de relatórios, os guias para desenvolvedores e os guias de migração mais recentes. Com base nessas informações, ele transforma a consulta na nova estrutura e atualiza os campos com os novos nomes e valores.

Habilidades do agente da API Merchant

A especificação de habilidades do agente é um padrão aberto adotado em todas as ferramentas para desenvolvedores de IA. Use as habilidades do agente para melhorar sua experiência de desenvolvedor e otimizar a migração da API Content for Shopping e a criação de novas integrações. Os pacotes de habilidades de agente da API Merchant reúnem conhecimento e ferramentas específicos de um domínio para aprimorar os recursos dos agentes de IA e oferecem assistência especializada sob demanda para consultas de documentação, geração de código e solução de problemas.

As habilidades do agente da API Merchant são compatíveis com várias ferramentas de linha de comando e ambientes de desenvolvimento integrado com tecnologia de IA, como o Antigravity e o Claude Code.

Como funciona

As habilidades de agente da API Merchant oferecem um pacote de conhecimento especializado baseado no padrão aberto de habilidades de agente. Nossa habilidade de agente mapi-developer-assistant atua como uma camada inteligente entre suas ferramentas para desenvolvedores de IA e o servidor MCP da API Merchant. Ele incorpora conhecimento de domínio e orientação procedimental, com as seguintes propriedades:

  • Configuração zero: gerencia automaticamente as conexões do servidor MCP, eliminando a necessidade de configuração manual de endpoints.
  • Fluxos de trabalho especializados: refinam os comandos do usuário em consultas otimizadas para buscar as informações mais relevantes de maneira eficaz.
  • Gerenciamento de contexto e eficiência de tokens: usa a "divulgação progressiva" para carregar informações sob demanda e preservar a janela de contexto da IA.
  • Formatação de saída aprimorada: fornece instruções para formatar e estruturar a saída para respostas acionáveis, legíveis e consistentes.

Exemplo de fluxo de trabalho:

  1. Você faz uma pergunta sobre a API Merchant em uma ferramenta para desenvolvedores de IA.
  2. A habilidade de agente da API Merchant analisa sua intenção, formula uma consulta precisa e aplica o conhecimento processual à solicitação.
  3. A habilidade do agente envia uma solicitação de contexto para o servidor MCP da documentação para desenvolvedores da API Merchant, localizado em merchantapi.googleapis.com/devdocs/mcp/.
  4. O serviço MCP pesquisa a coleção indexada de documentação, guias e exemplos de código oficiais da API Merchant.
  5. Seu agente de IA usa essas informações para fornecer uma resposta sintetizada e acionável.

Primeiros passos

O README das habilidades do agente da API Merchant oferece orientações detalhadas sobre:

  • Pré-requisitos para ferramentas como a ferramenta de linha de comando Antigravity.
  • Ativar o suporte às habilidades do agente na ferramenta escolhida.
  • Instalar a habilidade mapi-developer-assistant do repositório do GitHub conforme orientado pelo README.
  • Verifique a instalação.
  • Comandos básicos de gerenciamento de habilidades.

Para instruções detalhadas de instalação e configuração de várias ferramentas de IA, incluindo a ferramenta de linha de comando Antigravity, o Claude Code e outras, siga as orientações do arquivo README.

Exemplos de comandos

Depois de instalada e ativada nas suas ferramentas para desenvolvedores de IA, a habilidade mapi-developer-assistant geralmente é ativada automaticamente quando você faz perguntas relacionadas à API Merchant.

"Como faço para inserir um produto usando a API Merchant em Python?"

"Qual é o equivalente da API Merchant para o método accountstatuses.get da API Content?"

"Mostre um exemplo em Java para processar a autenticação com a API Merchant."

"Estou recebendo um erro '400 Bad Request' com um erro de validação ao chamar productInputs.insert. Como resolvo esse problema?"

"Qual é a diferença entre ProductInput e Product na API Merchant?"

Fontes da base de conhecimento

O serviço do MCP cria a base de conhecimento exclusivamente com fontes públicas e oficiais para garantir que o contexto fornecido seja preciso e confiável. O serviço indexa todo o conteúdo do site oficial para desenvolvedores e do repositório de exemplos de código, incluindo: