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

Use o kit de ferramentas de integração de API e assistência de código para acelerar sua 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, é necessário entender novas estruturas de serviço, nomes de recursos e métodos. As ferramentas de desenvolvimento com tecnologia de IA são especialmente 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 no novo formato da API Merchant. Isso inclui mapear atributos de produtos para a nova estrutura e atualizar arquivos de gerenciamento de dependências.
  • Experiência em documentação de API: fornece explicações claras sobre recursos, métodos, campos, cotas e práticas recomendadas da API Merchant com base em contexto confiável da documentação oficial 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 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 assistência de código 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 integrados (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 com as habilidades do agente da API Merchant para aumentar a integração e a velocidade.

(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 da sua escolha. No seu IDE, agora é possível acessar a documentação do desenvolvedor usando o serviço Protocolo de Contexto de Modelo (MCP). Esse serviço alimenta seu assistente de programação com informações importantes da documentação da API oficial 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 para o assistente de programação do seu ambiente de desenvolvimento integrado (IDE) ativado para 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, na sigla em inglês). Um sistema de RAG melhora a qualidade das respostas dos LLMs conectando-os a fontes de conhecimento externas e atualizadas. Isso permite que o 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 seu assistente de programação ou agente compatível com MCP (por exemplo, uma pergunta em linguagem natural, um pedido 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 na 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 IDE ou 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 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 sua 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 para o agente (opcional)

Para permitir que o agente traduza o código diretamente usando o MCP, forneça a ele as Instruções do sistema: protocolo do agente integrador de comerciantes. 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 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 IDE. 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 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 Google no GitHub e dos guias para desenvolvedores. Em seguida, o assistente pode apresentar um bloco de código completo e pronto para adaptação.

Cenário 4: entender os conceitos de 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. Em seguida, 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 oficiais de autenticação, que abordam diferentes métodos de autorização. Em seguida, 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 loteamento 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 código 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 o uso de agrupamento em lote HTTP com um Content-Type de multipart. Em seguida, o assistente pode explicar como criar uma única solicitação HTTP que contenha várias chamadas de API, enviada ao 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ório 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 Habilidades do agente é um padrão aberto adotado em todas as ferramentas de desenvolvimento de IA. Use as habilidades do agente para melhorar sua experiência de desenvolvedor e otimizar ambas, migrando da API Content para Shopping e criando novas integrações. Os pacotes de habilidades do agente da API Merchant reúnem conhecimento e ferramentas específicos do 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 (IDEs) com tecnologia de IA, como Gemini e Claude Code.

Como funciona

As habilidades do agente da API Merchant oferecem um pacote de experiência especializada criado com base no padrão aberto de habilidades do agente. Nossa habilidade do agente mapi-developer-assistant atua como uma camada inteligente entre suas ferramentas de desenvolvimento de IA e o servidor MCP da documentação para desenvolvedores da API Merchant. Ele incorpora experiência no domínio e orientação procedimental, tendo 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: 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 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 práticas, 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 ao servidor MCP do documento para desenvolvedores da API Merchant, localizado em merchantapi.googleapis.com/devdocs/mcp/.
  4. O serviço MCP pesquisa na 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 de habilidades do agente da API Merchant fornece orientações detalhadas sobre:

  • Pré-requisitos para ferramentas como a ferramenta de linha de comando do Gemini.
  • Ativar o suporte a habilidades do agente na ferramenta escolhida.
  • Instalar a habilidade mapi-developer-assistant do repositório do GitHub conforme orientado pelo README.
  • Verificando 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 suas ferramentas de desenvolvimento de IA, a skill mapi-developer-assistant geralmente é ativada automaticamente quando você faz perguntas relacionadas à API Merchant.

"Como 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 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: