Integrazione API e toolkit Code Assist

Utilizza il toolkit di integrazione API e Code Assist per accelerare la migrazione all'API Merchant e creare nuove integrazioni con strumenti di sviluppo basati sull'AI.

Panoramica

Quando esegui la migrazione dall'API Content for Shopping all'API Merchant o crei una nuova integrazione, devi comprendere le nuove strutture dei servizi, i nomi delle risorse e i metodi. Gli strumenti di sviluppo basati sull'AI sono particolarmente adatti per assistere nelle seguenti operazioni:

  • Traduzione e migrazione del codice: ti aiuta a comprendere e convertire il codice legacy dell'API Content for Shopping nel nuovo formato dell'API Merchant. Sono inclusi il mapping degli attributi di prodotto alla nuova struttura e l'aggiornamento dei file di gestione delle dipendenze.
  • Competenza nella documentazione delle API: fornisce spiegazioni chiare di risorse, metodi, campi, quote e best practice dell'API Merchant in base al contesto autorevole della documentazione ufficiale delle API di Google.
  • Generazione del codice: genera snippet di codice per varie attività dell'API Merchant in linguaggi tra cui Python, Java, PHP e altri.
  • Risoluzione dei problemi: consente di diagnosticare e correggere gli errori API comuni.

Scegli l'opzione più adatta al tuo ambiente di sviluppo e al tuo caso d'uso specifico. Utilizza il toolkit di integrazione API e Code Assist per personalizzare la configurazione in base al tuo flusso di lavoro preferito:

Il seguente diagramma illustra le opzioni di configurazione per una migrazione del codice assistita dall'AI negli ambienti di sviluppo integrati (IDE) di uso comune, come Antigravity, Visual Studio Code, Cursor o Copilot. È possibile configurare assistenti alla programmazione come Gemini, Claude, ChatGPT, Grok e potenziarli con il server MCP della documentazione per sviluppatori dell'API Merchant o con le competenze dell'agente dell'API Merchant per renderli più affidabili e aumentare la velocità di integrazione.

(API Merchant) Diagramma di AI Integration Code Assist

Server MCP per la documentazione per gli sviluppatori dell'API Merchant

Ricevi informazioni contestuali sull'API Merchant dall'assistente alla codifica che preferisci. All'interno dell'IDE, ora puoi accedere alla documentazione per gli sviluppatori utilizzando il servizio Model Context Protocol (MCP). Questo servizio fornisce al tuo assistente alla codifica le informazioni chiave dalla documentazione dell'API ufficiale di Google. Per ulteriori informazioni sul protocollo, consulta lo standard Model Context Protocol.

Come funziona

Quando poni una domanda sull'API Merchant all'assistente alla programmazione dell'IDE abilitato per MCP, il servizio recupera gli snippet di testo e codice più pertinenti dalle risorse ufficiali e li restituisce come contesto all'assistente alla programmazione utilizzando un backend di Retrieval-Augmented Generation (RAG) specializzato. Un sistema RAG migliora la qualità delle risposte degli LLM collegandoli a fonti di conoscenza esterne e aggiornate. In questo modo, l'assistente può fornire risposte accurate e aggiornate senza che tu debba mai uscire dal tuo ambiente di sviluppo.

Flusso di lavoro di esempio:

  1. Poni una domanda nell'assistente alla programmazione o nell'agente compatibile con MCP (ad es. domanda in linguaggio naturale, richiesta di un campione di codice o traduzione di codice).
  2. L'assistente alla codifica invia una richiesta di contesto all'endpoint MCP.
  3. Il servizio MCP esegue ricerche nella raccolta indicizzata di documentazione, guide ed esempi di codice ufficiali dell'API Merchant.
  4. Il servizio restituisce snippet autorevoli come contesto per l'assistente alla codifica.
  5. Il tuo assistente alla programmazione sfrutta questo contesto per generare una risposta fondata o un'attività di traduzione del codice.

Per iniziare

Per integrare e utilizzare MCP, segui questi passaggi:

1. Utilizzare uno strumento compatibile

Apri un IDE o un assistente alla codifica che supporti il Model Context Protocol con il trasporto HTTP trasmissibile.

2. Configura l'endpoint

Per connettere l'IDE o l'assistente per la programmazione a MCP, utilizza i dettagli dell'endpoint remoto forniti, che potrebbero richiedere l'inserimento dell'URL del servizio diretto o della definizione MCP, a seconda della configurazione dello strumento:

Configurazioni:

Antigravity

Segui le istruzioni riportate nella documentazione di Antigravity.

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

Visual Studio Code

Segui le istruzioni riportate nella documentazione di Visual Studio Code.

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

3. (Facoltativo) Aggiungi istruzioni per l'agente

Per consentire all'agente di tradurre direttamente il codice utilizzando MCP, fornisci le istruzioni di sistema: protocollo dell'agente di integrazione del commerciante. Queste istruzioni guidano l'agente su come utilizzare correttamente MCP per la traduzione del codice. A seconda dello strumento, puoi fornire queste istruzioni nella configurazione delle istruzioni di sistema o come file di contesto aggiuntivo per l'agente.

Scenari di utilizzo di esempio

MCP può accelerare il tuo flusso di lavoro nei seguenti casi d'uso comuni:

Scenario 1: esegui la migrazione del codice products.insert

Puoi chiedere all'agente di eseguire direttamente la migrazione di un codice di integrazione dell'API Content for Shopping products.insert all'API Merchant.

Prompt dell'utente:

"Esegui la migrazione del codice products.insert all'API Merchant"

Fornendo all'agente istruzioni di sistema e accesso a MCP, l'agente può tradurre il codice dell'API Content for Shopping in codice dell'API Merchant direttamente nell'IDE. In questo caso, identificherà productInputs.insert come chiamata equivalente e mapperà gli attributi prodotto dal vecchio formato al nuovo formato richiesto dall'API Merchant. Può anche aggiornare le importazioni richieste e il file di gestione delle dipendenze (ad esempio requirements.txt, pom.xml o package.json). Puoi chiedere all'agente di apportare le modifiche sul posto o di creare una nuova cartella.

Scenario 2: trova funzionalità equivalenti

Hai un'applicazione esistente che utilizza l'API Content per Shopping e devi aggiornarla. Puoi chiedere informazioni su un metodo legacy specifico per ottenere dettagli sulla nuova implementazione e un esempio di codice pertinente.

Prompt dell'utente:

"Qual è l'equivalente dell'API Merchant per il metodo accountstatuses.get nell'API Content for Shopping?"

Il servizio MCP fornisce il contesto delle guide alla migrazione ufficiali e della documentazione di riferimento, consentendo all'assistente di rispondere con una risposta dettagliata, incluso il nuovo nome dell'API, accounts.issues.

Scenario 3: trovare un esempio di codice

Stai implementando una nuova funzionalità e hai bisogno di un esempio pratico da seguire.

Prompt dell'utente:

"Mostrami un esempio di codice Python per aggiungere un nuovo servizio di spedizione utilizzando l'API Merchant."

Il servizio MCP recupera esempi di codice pertinenti dai repository GitHub ufficiali di Google e dalle guide per sviluppatori. L'assistente può quindi presentare un blocco di codice completo e pronto per essere adattato.

Scenario 4: comprendere i concetti delle API

Ti imbatti in un nuovo concetto o vuoi comprendere la struttura di una risorsa o il pattern generale dell'API Merchant.

Prompt dell'utente:

"Come faccio ad aggiornare l'inventario di un prodotto utilizzando l'API Merchant?"

Il servizio MCP restituisce il contesto dalla documentazione delle risorse dei prodotti e dalle guide pertinenti. L'assistente può quindi spiegare come utilizzare il metodo accounts.productInputs.insert e fornire la risorsa prodotto parziale contenente solo productId e i campi correlati all'inventario che devi aggiornare.

"Come faccio ad autorizzare le chiamate della mia applicazione con l'API Merchant?"

Il servizio MCP recupera il contesto dalle guide di autenticazione ufficiali, che coprono diversi metodi di autorizzazione. L'assistente può quindi spiegare le opzioni principali disponibili, ad esempio l'utilizzo di un service account per le interazioni da server a server o di un ID client OAuth 2.0 quando agisce per conto di un utente.

Scenario 5: adattamento alle modifiche dell'API

L'API Merchant introduce nuovi pattern, come le richieste batch, diversi dall'API Content for Shopping. L'API Content for Shopping utilizza metodi custombatch specifici, mentre l'API Merchant utilizza una funzionalità batch HTTP generica integrata.

Prompt dell'utente:

"Qual è il nuovo modo di eseguire un'operazione products.custombatch nell'API Merchant?"

Il servizio MCP recupera il contesto da Refactor code for concurrent requests spiegando che i metodi custombatch dedicati non esistono nell'API Merchant. Fornisce invece la documentazione sull'utilizzo del batch HTTP con un Content-Type di multipart. L'assistente può quindi spiegarti come creare una singola richiesta HTTP contenente più chiamate API, inviata all'endpoint https://merchantapi.googleapis.com/batch/{sub-api}/v1, e fornire un esempio di come strutturare la richiesta in più parti. In questo modo, un'attività di migrazione potenzialmente confusa si trasforma in un processo guidato.

Scenario 6: traduci una query di report

Puoi chiedere all'agente di tradurre una query di reporting dall'API Content for Shopping all'API Merchant.

Prompt dell'utente:

"Esegui la migrazione di questa query di reporting dall'API Content all'API Merchant: SELECT metrics.impressions, metrics.clicks, metrics.ctr FROM MerchantPerformanceView WHERE segments.date BETWEEN '2020-12-01' AND '2020-12-30'"

Il servizio MCP recupera la documentazione di riferimento più recente per i report, le guide per gli sviluppatori e le guide alla migrazione. In base a queste informazioni, trasforma la query nella nuova struttura e aggiorna i campi con i nuovi nomi e valori.

Merchant API Agent Skills

La specifica Agent Skills è uno standard aperto adottato in tutti gli strumenti di sviluppo dell'AI. Utilizza le competenze dell'agente per migliorare la tua esperienza di sviluppo e ottimizzare entrambi, eseguendo la migrazione dall'API Content for Shopping e creando nuove integrazioni. Pacchetti di competenze dell'agente API Merchant conoscenze e strumenti specifici del dominio per migliorare le funzionalità degli agenti AI e fornisce assistenza on demand da parte di esperti per domande sulla documentazione, generazione di codice e risoluzione dei problemi.

Le competenze dell'agente API Merchant sono compatibili con vari strumenti da riga di comando e IDE basati sull'AI, come Antigravity e Claude Code.

Come funziona

Le skill dell'agente API Merchant forniscono un pacchetto di competenze specializzate basato sullo standard aperto delle skill dell'agente. La nostra skill dell'agente mapi-developer-assistant funge da livello intelligente tra gli strumenti di sviluppo dell'AI e il server MCP Merchant API Dev Doc sottostante. Incorpora competenze di dominio e indicazioni procedurali, con le seguenti proprietà:

  • Configurazione zero: gestisce automaticamente le connessioni al server MCP, eliminando la necessità di configurare manualmente l'endpoint.
  • Expert Workflows: perfeziona i prompt degli utenti in query ottimizzate per recuperare le informazioni più pertinenti in modo efficace.
  • Gestione del contesto ed efficienza dei token: utilizza la "divulgazione progressiva" per caricare le informazioni su richiesta e preservare la finestra contestuale dell'AI.
  • Formattazione avanzata dell'output: fornisce istruzioni per formattare e strutturare l'output per risposte fruibili, leggibili e coerenti.

Flusso di lavoro di esempio:

  1. Poni una domanda sull'API Merchant in uno strumento di sviluppo dell'AI.
  2. La skill dell'agente API Merchant analizza l'intent, formula una query precisa e applica le sue conoscenze procedurali alla richiesta.
  3. L'agente Skill invia una richiesta di contesto al server MCP della documentazione per gli sviluppatori dell'API Merchant situato all'indirizzo merchantapi.googleapis.com/devdocs/mcp/.
  4. Il servizio MCP esegue ricerche nella raccolta indicizzata di documentazione, guide ed esempi di codice ufficiali dell'API Merchant.
  5. Il tuo agente AI sfrutta queste informazioni per fornire una risposta sintetica e strategica.

Per iniziare

Il file README delle competenze dell'agente dell'API Merchant fornisce una guida passo passo su:

  • Prerequisiti per strumenti come lo strumento a riga di comando Antigravity.
  • Abilitare il supporto delle competenze dell'agente nello strumento scelto.
  • Installare la skill mapi-developer-assistant dal repository GitHub come indicato nel file README.
  • Verifica dell'installazione in corso…
  • Comandi di base per la gestione delle skill.

Per istruzioni dettagliate di installazione e configurazione per vari strumenti di AI, inclusi lo strumento a riga di comando Antigravity, Claude Code e altri, segui le indicazioni del file README.

Prompt di esempio

Una volta installata e abilitata negli strumenti di sviluppo dell'AI, la skill mapi-developer-assistant viene in genere attivata automaticamente quando poni domande relative all'API Merchant.

"Come faccio a inserire un prodotto utilizzando l'API Merchant in Python?"

"Qual è l'equivalente dell'API Merchant per il metodo dell'API Content accountstatuses.get?"

"Mostrami un esempio Java per la gestione dell'autenticazione con l'API Merchant."

"Ricevo un errore "400 Bad Request" con un errore di convalida quando chiamo productInputs.insert. Come faccio a risolvere il problema?"

"Qual è la differenza tra ProductInput e Product nell'API Merchant?"

Fonti della knowledge base

Il servizio MCP crea la sua knowledge base esclusivamente da fonti pubbliche e ufficiali per garantire che il contesto fornito sia accurato e affidabile. Il servizio indicizza l'intero contenuto del sito ufficiale per sviluppatori e del repository di esempi di codice, tra cui: