Integrazione API e toolkit Code Assist

Utilizza l'integrazione dell'API e il toolkit Code Assist per accelerare la migrazione all'API Merchant e creare nuove integrazioni con strumenti per sviluppatori 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 per sviluppatori 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. Ciò include la mappatura degli attributi del prodotto 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 di Google.
  • Generazione del codice: genera snippet di codice per varie attività dell'API Merchant in linguaggi come Python, Java, PHP e altri.
  • Risoluzione dei problemi: aiuta a diagnosticare e correggere gli errori API più comuni.

Scegli l'opzione più adatta al tuo ambiente di sviluppo e al tuo caso d'uso specifico. Utilizza l'API Integration and Code Assist Toolkit 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 al coding come Gemini, Claude, ChatGPT, Grok e potenziarli con il server MCP della documentazione per lo sviluppo dell'API Merchant o con le competenze dell'agente dell'API Merchant per essere più precisi e aumentare la velocità di integrazione.

Diagramma di Code Assist per l'integrazione dell'AI (API Merchant)

Server MCP per la documentazione per lo sviluppo dell'API Merchant

Ricevi informazioni contestuali sull'API Merchant dall'assistente al coding che preferisci. All'interno dell'IDE, ora puoi accedere alla documentazione per lo sviluppo utilizzando il servizio Model Context Protocol (MCP). Questo servizio fornisce all'assistente al coding informazioni chiave dalla documentazione ufficiale dell'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 al coding 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 al coding 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 lasciare l'ambiente di sviluppo.

Esempio di flusso di lavoro:

  1. Fai una domanda all'assistente al coding o all'agente compatibile con MCP (ad es. una domanda in linguaggio naturale, una richiesta di un esempio di codice o una traduzione di codice).
  2. L'assistente al coding invia una richiesta di contesto all'endpoint MCP.
  3. Il servizio MCP esegue una ricerca 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 al coding.
  5. L'assistente al coding sfrutta questo contesto per generare una risposta fondata o un'attività di traduzione di codice.

Per iniziare

Per integrare e utilizzare l'MCP, segui questi passaggi:

1. Utilizza uno strumento compatibile

Apri un IDE o un'assistenza al coding che supporti il Model Context Protocol con il trasporto HTTP trasmissibile in streaming.

2. Configura l'endpoint

Per connettere l'IDE o l'assistenza al coding all'MCP, utilizza i dettagli dell'endpoint remoto forniti, che potrebbero richiedere l'inserimento dell'URL del servizio diretto o della definizione dell'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 con Merchant. Queste istruzioni guidano l'agente su come utilizzare correttamente l'MCP per la traduzione di 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 workflow 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 l'accesso a MCP, l'agente può tradurre il codice dell'API Content for Shopping nel codice dell'API Merchant direttamente nel tuo IDE. In questo caso, identificherà productInputs.insert come chiamata equivalente e mapperà gli attributi del 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 indicare all'agente di apportare le modifiche in loco o di creare una nuova cartella.

Scenario 2: trova una funzionalità equivalente

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 e della documentazione di riferimento ufficiali, consentendo all'assistente di rispondere con una risposta dettagliata, incluso il nuovo nome dell'API, accounts.issues.

Scenario 3: ricerca di 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: comprendere i concetti delle API

Incontri 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 parziale del prodotto 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 dalle guide ufficiali all'autenticazione, 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 server-server o 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, che differiscono dall'API Content for Shopping. L'API Content for Shopping utilizza metodi custombatch specifici, mentre l'API Merchant utilizza una funzionalità di raggruppamento 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 Rifattorizza il codice per le richieste in parallelo spiegando che i metodi custombatch dedicati non esistono nell'API Merchant. Fornisce invece la documentazione sull'utilizzo del raggruppamento 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 multiparte. In questo modo, un'attività di migrazione potenzialmente confusa si trasforma in un processo guidato.

Scenario 6: traduci una query di reporting

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 report 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. Sulla base di queste informazioni, trasforma la query nella nuova struttura e aggiorna i campi con i nuovi nomi e valori.

Skill dell'agente dell'API Merchant

La specifica Agent Skills è uno standard aperto adottato in tutti gli strumenti per sviluppatori dell'AI. Utilizza le competenze degli agenti per migliorare la tua esperienza di sviluppo e ottimizzare sia la migrazione dall'API Content for Shopping sia la creazione di nuove integrazioni. Le competenze degli agenti dell'API Merchant pacchettizzano conoscenze e strumenti specifici del dominio per migliorare le funzionalità degli agenti AI e forniscono assistenza on demand di esperti per query sulla documentazione, generazione di codice e risoluzione dei problemi.

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

Come funziona

Le skill dell'agente dell'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 i tuoi strumenti di sviluppo AI e il server MCP della documentazione per sviluppatori dell'API Merchant 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 gli 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 on demand e preservare la finestra contestuale dell'AI.
  • Formattazione dell'output migliorata: fornisce istruzioni per formattare e strutturare l'output per risposte fruibili, leggibili e coerenti.

Esempio di flusso di lavoro:

  1. Fai una domanda sull'API Merchant in uno strumento per sviluppatori AI.
  2. L'agente con skill API Merchant analizza l'intento, formula una query precisa e applica le sue conoscenze procedurali alla richiesta.
  3. L'Agent Skill invia una richiesta di contesto al server MCP della documentazione per gli sviluppatori dell'API Merchant, che si trova all'indirizzo merchantapi.googleapis.com/devdocs/mcp/.
  4. Il servizio MCP esegue una ricerca nella raccolta indicizzata di documentazione, guide ed esempi di codice ufficiali dell'API Merchant.
  5. L'agente AI sfrutta queste informazioni per fornire una risposta sintetizzata e utilizzabile.

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 Antigravity.
  • Abilitazione del supporto delle skill dell'agente nello strumento scelto.
  • Installazione dello 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 sulla configurazione di vari strumenti AI, tra cui 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 per sviluppatori AI, la skill mapi-developer-assistant viene in genere attivata automaticamente quando fai 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 dell'API Content?"

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