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 API: fornisce spiegazioni chiare di risorse, metodi, campi, quote e 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 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) più comunemente utilizzati, 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 abilità dell'agente dell'API Merchant per renderli più affidabili e aumentare la velocità di integrazione.

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

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 programmazione informazioni chiave dalla documentazione ufficiale delle API 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 generazione aumentata dal recupero (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'agente o nell'assistente alla programmazione 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. L'assistente alla programmazione sfrutta 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. Utilizzare uno strumento compatibile

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

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 di 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 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 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 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 della risorsa prodotti e dalle guide pertinenti. L'assistente potrà quindi spiegarti come utilizzare il metodo accounts.productInputs.insert e fornirti 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. La Content API for Shopping utilizza metodi custombatch specifici, mentre l'API Merchant utilizza una funzionalità di batch HTTP generica e 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 spiegare 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 per i 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 l'esperienza degli sviluppatori e ottimizzare entrambi, eseguendo la migrazione dall'API Content per Shopping e creando nuove integrazioni. I pacchetti di competenze dell'agente API Merchant offrono conoscenze e strumenti specifici per il dominio per migliorare le funzionalità degli agenti AI e forniscono assistenza esperta su richiesta per query 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 Gemini e Claude Code.

Come funziona

Le competenze dell'agente API Merchant forniscono un pacchetto di competenze specialistiche basato sullo standard aperto delle competenze 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.
  • Flussi di lavoro esperti: 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 competenza dell'agente API Merchant analizza l'intent, formula una query precisa e applica le sue conoscenze procedurali alla richiesta.
  3. L'agente 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 pratica.

Per iniziare

Il file README delle competenze dell'agente 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 skill mapi-developer-assistant dal repository GitHub come indicato nel file README.
  • Verifica dell'installazione.
  • Comandi di base per la gestione delle skill.

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 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 che fornisce sia accurato e affidabile. Il servizio indicizza l'intero contenuto del sito ufficiale per sviluppatori e del repository di esempi di codice, tra cui: