Integrazione API e toolkit Code Assist

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

Panoramica

Quando esegui la migrazione da 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 di API Content for Shopping nel nuovo formato dell'API Merchant. Sono inclusi il mapping degli attributi dei prodotti alla nuova struttura e l'aggiornamento dei file di gestione delle dipendenze.
  • Competenza nella documentazione dell'API: fornisce spiegazioni chiare delle risorse, dei metodi, dei campi, delle quote e delle best practice dell'API Merchant in base al contesto autorevole della documentazione ufficiale dell'API Google.
  • Generazione del codice: genera snippet di codice per varie attività dell'API Merchant in linguaggi come Python, Java, PHP e altri linguaggi.
  • Risoluzione dei problemi: aiuta a diagnosticare e correggere gli errori comuni dell'API.

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

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 gli sviluppatori dell'API Merchant o le competenze dell'agente dell'API Merchant per renderli più affidabili e al contempo aumentare la velocità di integrazione.

(API Merchant) Diagramma dell'assistente alla programmazione per l'integrazione dell'AI

Server MCP della documentazione per gli sviluppatori dell'API Merchant

Ottieni informazioni contestuali sull'API Merchant dall'assistente alla programmazione 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 di programmazione informazioni chiave dalla documentazione ufficiale dell'API Google. Per ulteriori informazioni sul protocollo stesso, 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 specializzato di Retrieval-Augmented Generation (RAG). Un sistema RAG è un sistema che 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 dall'ambiente di sviluppo.

Flusso di lavoro di esempio :

  1. Poni una domanda all'assistente alla programmazione o all'agente compatibile con MCP (ad es. domanda in linguaggio naturale, richiesta di un esempio di codice o traduzione del codice).
  2. L'assistente alla programmazione invia una richiesta di contesto all'endpoint MCP.
  3. Il servizio MCP cerca nella raccolta indicizzata di documentazione, guide ed esempi di codice ufficiali dell'API Merchant.
  4. Il servizio restituisce snippet autorevoli come contesto all'assistente alla programmazione.
  5. L'assistente alla programmazione utilizza questo contesto per generare una risposta basata su dati reali o un'attività di traduzione del codice.

Per iniziare

Per integrare e utilizzare MCP, segui questi passaggi:

1. Utilizza uno strumento compatibile

Apri un IDE o un assistente alla programmazione che supporti il Model Context Protocol con trasporto HTTP in streaming.

2. Configura l'endpoint

Per connettere l'IDE o l'assistente alla 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 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 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 integratore Merchant. 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 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 products.insert di Content API for Shopping 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 di API Content for Shopping in codice dell'API Merchant direttamente nell'IDE. In questo caso, identificherà productInputs.insert come chiamata equivalente ed eseguirà il mapping degli attributi dei prodotti dal vecchio formato al nuovo formato richiesto dall'API Merchant. Può anche aggiornare le importazioni richieste e il file di gestione delle dipendenze (ad es. requirements.txt, pom.xml o package.json). Puoi chiedere all'agente di apportare le modifiche in loco o di creare una nuova cartella.

Scenario 2: trova funzionalità equivalenti

Hai un'applicazione esistente che utilizza l'API Content for 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 in API Content for Shopping?

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

Scenario 3: trova 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 gli sviluppatori. L'assistente può quindi presentare un blocco di codice completo e pronto per essere adattato.

Scenario 4: comprendi i concetti dell'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 della documentazione delle risorse dei prodotti e delle guide pertinenti. L'assistente può quindi spiegare come utilizzare il metodo accounts.productInputs.insert e fornire la risorsa del prodotto parziale contenente solo productId e i campi relativi all'inventario che devi aggiornare.

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

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

Scenario 5: adattati alle modifiche dell'API

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

Prompt dell'utente :

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

Il servizio MCP recupera il contesto da Refactor code for concurrent requests spiegando che nell'API Merchant non esistono metodi custombatch dedicati. Fornisce invece la documentazione sull'utilizzo del batch HTTP con un Content-Type di multipart. L'assistente può quindi spiegare come costruire 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 multipart. In questo modo, un'attività di migrazione potenzialmente confusa diventa una procedura guidata.

Scenario 6: traduci una query di reporting

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

Prompt dell'utente :

Esegui la migrazione di questa query di reporting da 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, le guide per gli sviluppatori e le guide alla migrazione più recenti per il reporting. In base a queste informazioni, trasforma la query nella nuova struttura e aggiorna i campi con i nuovi nomi e valori.

Competenze dell'agente dell'API Merchant

La specifica delle competenze dell'agente è uno standard aperto adottato negli strumenti di sviluppo dell'AI. Utilizza le competenze dell'agente per migliorare l'esperienza degli sviluppatori e ottimizzare sia la migrazione da Content API for Shopping sia la creazione di nuove integrazioni. I pacchetti di competenze dell'agente dell'API Merchant contengono strumenti e conoscenze specifiche del dominio per migliorare le funzionalità degli agenti AI e forniscono assistenza esperta su richiesta per le query di documentazione, la generazione di codice e la risoluzione dei problemi.

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

Come funziona

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

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

Flusso di lavoro di esempio :

  1. Poni una domanda sull'API Merchant in uno strumento di sviluppo dell'AI.
  2. La competenza dell'agente dell'API Merchant analizza la tua intenzione, formula una query precisa e applica le sue conoscenze procedurali alla richiesta.
  3. La competenza dell'agente invia una richiesta di contesto al server MCP della documentazione per gli sviluppatori dell'API Merchant all'indirizzo merchantapi.googleapis.com/devdocs/mcp/.
  4. Il servizio MCP cerca nella raccolta indicizzata di documentazione, guide ed esempi di codice ufficiali dell'API Merchant.
  5. L'agente AI utilizza queste informazioni per fornire una risposta sintetizzata e pratica.

Per iniziare

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

  • Prerequisiti per strumenti come lo strumento a riga di comando Gemini.
  • Abilitazione del supporto delle competenze dell'agente nello strumento scelto.
  • Installazione della competenza mapi-developer-assistant dal repository GitHub come indicato nel file README.
  • Verifica dell'installazione.
  • Comandi di base per la gestione delle competenze.

Per istruzioni dettagliate sull'installazione e la configurazione di vari strumenti di AI, tra cui lo strumento a riga di comando Gemini, 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 competenza 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 accountstatuses.get di Content API?

"Mostrami un esempio di 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 gli sviluppatori e del repository di esempi di codice, tra cui: