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

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

Visão geral

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

  • Tradução e migração de código: ajuda a entender e converter o código legado da API Content for Shopping para o novo formato da API Merchant. Isso inclui o mapeamento de atributos de produtos para a nova estrutura e a atualização de arquivos de gerenciamento de dependências.
  • Conhecimento da documentação da API: fornece explicações claras dos recursos, métodos, campos, cotas e práticas recomendadas da API Merchant com base no contexto confiável da documentação oficial da API Google.
  • Geração de código: gera snippets de código para várias tarefas da API Merchant em linguagens como Python, Java, PHP e 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 o kit de ferramentas de integração de API e Code Assist para personalizar a configuração de acordo com 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, Grok, e capacitá-los com o servidor MCP da documentação para desenvolvedores da API Merchant ou as habilidades do agente da API Merchant para serem mais fundamentados e aumentar a velocidade de integração.

(API Merchant) Diagrama do Gemini Code Assist para integração de IA

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

Receba inteligência contextual sobre a API Merchant do assistente de programação de sua escolha. 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, na sigla em inglês). Esse serviço alimenta seu assistente de programação com informações importantes da documentação oficial da API 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 ambiente de desenvolvimento integrado ativado pelo MCP, o serviço recupera os snippets de texto e código mais relevantes de 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 RAG é aquele que melhora a qualidade das respostas dos LLMs conectando-os a fontes de conhecimento externas e atualizadas. Isso permite que seu assistente forneça respostas precisas e atualizadas sem que você precise sair do ambiente de desenvolvimento.

Exemplo de fluxo de trabalho:

  1. Você faz uma pergunta no assistente de programação ou agente compatível com MCP (por exemplo, uma pergunta em linguagem natural, uma solicitação de exemplo de código ou uma tradução de código).
  2. O 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 o assistente de programação.
  5. O assistente de programação aproveita 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 transmitível.

2. Configurar o endpoint

Para conectar seu ambiente de desenvolvimento integrado (IDE) ou assistente de programação ao MCP, use os detalhes do endpoint remoto fornecidos, que podem exigir que você insira o URL do 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 comerciante. Essas instruções orientam o agente sobre como usar corretamente o MCP para tradução de código. Dependendo da ferramenta, você pode 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 products.insert

Você pode pedir ao agente para migrar diretamente um código de integração products.insert da API Content for Shopping 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, o 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, ele 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 a criar uma nova pasta.

Cenário 2: encontrar funcionalidades equivalentes

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 GitHub do Google e dos guias para desenvolvedores. O assistente pode apresentar um bloco de código completo e pronto para adaptação.

Cenário 4: entender os conceitos da API

Você encontra 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 de produtos e 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 faço para autorizar 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: adaptar-se às mudanças da 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 do código de refatoração para solicitações simultâneas explicando que métodos custombatch dedicados não existem na API Merchant. Em vez disso, ele fornece documentação sobre como usar o lote HTTP com um Content-Type de multipart. O assistente pode explicar como construir uma única solicitação HTTP que contenha várias chamadas de API, enviadas para o endpoint https://merchantapi.googleapis.com/batch/{sub-api}/v1, e fornecer um exemplo de como estruturar a solicitação multipart. 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ório da API Content for Shopping para a API Merchant.

Comando do usuário:

"Migre esta consulta de relatório 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, guias para desenvolvedores e guias de migração mais recentes. Com base nessas informações, ele transforma a consulta na nova estrutura e atualiza os campos para os novos nomes e valores.

Habilidades do agente da API Merchant

A especificação de habilidades do agente é um padrão aberto adotado em ferramentas de desenvolvimento de IA. Use as habilidades do agente para melhorar a experiência do desenvolvedor e otimizar a migração da API Content for Shopping e a criação de novas integrações. Os pacotes de habilidades do agente da API Merchant contêm conhecimento e ferramentas específicos do domínio para melhorar os recursos dos agentes de IA e fornecer 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 Gemini e o Claude Code.

Como funciona

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

  • Configuração zero: gerencia automaticamente as conexões do servidor MCP, eliminando a necessidade de configuração manual do endpoint.
  • Fluxos de trabalho especializados: refina 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 token: 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 de desenvolvimento de IA.
  2. A habilidade do 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. O agente de IA aproveita essas informações para fornecer uma resposta sintetizada e acionável.

Primeiros passos

O arquivo README das habilidades do agente da API Merchant fornece orientações passo a passo sobre:

  • Pré-requisitos para ferramentas como a ferramenta de linha de comando do Gemini.
  • Como ativar o suporte a habilidades do agente na ferramenta escolhida.
  • Como instalar a habilidade mapi-developer-assistant do repositório do GitHub, conforme orientado pelo arquivo README.
  • Como verificar 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 do Gemini, o Claude Code e outras, siga as orientações do arquivo README.

Exemplos de comandos

Depois de instalada e ativada nas ferramentas de desenvolvimento 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 no 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 faço para corrigir isso?"

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

Fontes da base de conhecimento

O serviço 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: