Installare e utilizzare l'assistente sviluppatore dell'API Google Ads

L'assistente per sviluppatori dell'API Google Ads porta l'esperienza approfondita nel dominio dell'API Google Ads direttamente nel tuo ambiente di programmazione AI. Utilizza prompt in linguaggio naturale e comandi slash integrati per creare query, generare codice della libreria client, eseguire chiamate API di sola lettura, trasmettere report ad hoc e risolvere i problemi delle integrazioni.

L'assistente è progettato per i framework degli agenti Google Antigravity e Claude Code (v4.0.0) come plug-in modulare. Utilizza i contratti AGENTS.md e CLAUDE.md, i comandi slash integrati e le competenze di dominio specializzate per mantenere un contesto persistente, limiti di sicurezza solidi e pipeline di convalida automatizzate. Per una panoramica dell'architettura e del design, consulta Che cos'è l'assistente per sviluppatori dell'API Google Ads?

Prerequisiti

Prima di iniziare, assicurati di disporre di quanto segue:

  1. Accesso all'API Google Ads:

  2. Software:

Inizia

Segui questi passaggi per clonare il repository, eseguire lo script di installazione specifico per la piattaforma, configurare le credenziali e attivare il plug-in.

1. Clona il repository

Clona il repository sulla tua macchina locale e vai alla directory del progetto:

git clone https://github.com/googleads/google-ads-api-developer-assistant
cd google-ads-api-developer-assistant

2. Esegui lo script di installazione

Esegui lo script di installazione per la tua piattaforma di destinazione. Per impostazione predefinita, è inclusa la libreria client Python. Se vuoi, puoi includere altre librerie client (--php, --ruby, --java, --dotnet o --all).

Antigravity

Linux / macOS:

./install.sh agy
# Or include additional client libraries:
./install.sh agy --java --dotnet

Windows (PowerShell):

.\install.ps1 -Type agy
# Or include additional client libraries:
.\install.ps1 -Type agy -Java -Dotnet

Claude Code

Linux / macOS:

./install.sh claude
# Or include additional client libraries:
./install.sh claude --php --dotnet

Windows (PowerShell):

.\install.ps1 -Type claude
# Or include additional client libraries:
.\install.ps1 -Type claude -Php -Dotnet

3. Configura le credenziali

Assicurati che il file di configurazione dell'API (ad esempio google-ads.yaml, google_ads_php.ini o google_ads_config.rb) sia inserito nella directory $HOME.

(Facoltativo) Per configurare un ID cliente predefinito, inserisci il numero dell'ID cliente direttamente in config/customer_id.txt (ad esempio, 1234567890). Puoi anche ispezionare o bloccare la versione dell'API attiva in config/api_version.txt.

4. Attiva il plug-in

  • Antigravity: riavvia la sessione host di Antigravity / agy per caricare il plug-in.
  • Claude Code:in una sessione Claude Code attiva, esegui /reload-plugins o riavvia claude.

5. Interagisci con l'assistente

Puoi interagire con l'assistente utilizzando prompt in linguaggio naturale o comandi slash dedicati direttamente nel terminale.

Funzionalità principali

  • Domande e risposte in linguaggio naturale e indicazioni concettuali: fai domande sulle funzionalità dell'API Google Ads, sulle regole di architettura, sulle best practice o su risorse specifiche. L'assistente basa le risposte sulle definizioni ufficiali dell'API, anziché affidarsi esclusivamente all'addestramento generale dell'LLM.

    • "Quali sono i tipi di campagna disponibili?"
    • "Come faccio a filtrare per data in GAQL?"
    • "Spiega la differenza tra click_view e impression_view."
    • "Che cos'è un set condiviso e come si utilizza?"
    • Comandi slash di Claude Code:/explain, /step-by-step, /assistant-tutorial

  • Generazione di codice della libreria client con grounding:genera codice idiomatico testato utilizzando le librerie client ufficiali di Google Ads (Python, Java, PHP, .NET e Ruby).

    • "Mostrami le campagne con il maggior numero di conversioni negli ultimi 30 giorni."
    • "Recupera tutti i nomi dei gruppi di annunci attivati per il cliente 123-456-7890."
    • "Scrivi il codice per creare una campagna Performance Max." Il codice generato viene salvato nella directory saved/code/.

  • Convalida delle query GAQL programmatiche:esegui automaticamente il dry run e convalida le query complesse rispetto ai metadati dell'API, alla compatibilità dei campi, alle regole per le impressioni pari a zero e alla segmentazione delle date prima dell'esecuzione.

    • Claude Code: /validate-gaql
    • Linguaggio naturale: validate: SELECT campaign.id FROM campaign

  • Ispezione degli schemi di oggetti e Protobuf: ispeziona dinamicamente le strutture delle risorse, i campi nidificati, i tipi di dati e i valori enum per qualsiasi versione dell'API attiva senza l'overhead dei metadati remoti.

    • Claude Code: /inspect-object <resource_or_enum>
    • Linguaggio naturale: "Ispeziona la risorsa della campagna"

  • Report in tempo reale ad hoc ed esportazione in formato CSV:richiedi i dati sul rendimento in un linguaggio semplice. L'assistente crea, convalida ed esegue query GAQL direttamente sul tuo account, trasmettendo in streaming tabelle formattate in tempo reale nel terminale.

    • "Mostra le prime 5 parole chiave per costo del mese scorso per il cliente 123-456-7890."
    • "Salva i risultati come file CSV." (Esportazioni in saved/csv/).

  • Esecuzione diretta dell'API e sicurezza delle modifiche: esegui gli script di sola lettura generati direttamente in un ambiente virtuale gestito.

    • Di' all'assistente: "Esegui il codice" o "Esegui lo script".
    • Sicurezza delle mutazioni: per sicurezza, le operazioni di mutazione (creazione, aggiornamento, eliminazione) vengono generate in saved/code/, ma mai eseguite direttamente dall'assistente. Esaminali ed eseguili manualmente al di fuori dell'assistente.

  • Diagnostica avanzata e risoluzione dei problemi di conversione:esamina gli errori di caricamento delle conversioni offline, pre-convalida i file di caricamento e genera report diagnostici dettagliati.

    • Claude Code: /troubleshoot-conversions
    • Linguaggio naturale: "Risolvi i problemi relativi alle conversioni per il cliente 123-456-7890." (Report salvati in saved/data/).

  • Mappatura della gerarchia degli account amministratore:recupera gli ID cliente dei subaccount e mappa le gerarchie degli account in un account amministratore.

    • Claude Code: /get-cids <manager_cid>
    • Linguaggio naturale: "Recupera tutti gli ID cliente secondario nell'account amministratore 123-456-7890"

  • Filtri ed esclusioni delle schede Performance Max:genera alberi di partizione dei prodotti ed esclusioni di URL di pagine web per i gruppi di asset.

    • Claude Code: /pmax-filter
    • Linguaggio naturale: "Crea filtri di esclusione delle pagine web per la mia campagna Performance Max"

  • Contesto aggiuntivo del codebase: registra la logica dell'applicazione e l'architettura personalizzata nel ragionamento dell'assistente.

    • Linux / macOS:

      ./update.sh agy --context_dir /path/to/your/codebase
# Or for Claude Code:
./update.sh claude --context_dir /path/to/your/codebase

    • Windows (PowerShell):

      .\update.ps1 -Type agy -ContextDir C:\path\to\your\codebase

Riferimento per i comandi slash di Claude Code

Quando utilizzi Claude Code, sono disponibili i seguenti comandi slash integrati. In Google Antigravity, richiama queste stesse funzionalità utilizzando prompt in linguaggio naturale o nomi di strumenti di skill come validate_gaql e inspect_object, come descritto in Funzionalità principali:

Comando slash Finalità Esempio
/validate-gaql Convalida la sintassi, la compatibilità e le regole GAQL. /validate-gaql
/inspect-object Ispeziona i campi, i tipi e gli enum di Protobuf. /inspect-object Campaign
/get-cids Risolve le gerarchie degli account amministratore e gli ID cliente. /get-cids 1234567890
/troubleshoot-conversions Esegue la diagnostica del caricamento delle conversioni offline. /troubleshoot-conversions
/pmax-filter Genera filtri ed esclusioni delle schede Performance Max. /pmax-filter
/explain Fornisce una spiegazione strutturata in 4 parti. /explain shared set
/step-by-step Formula un piano di esecuzione delle attività in più fasi. /step-by-step upload conversions
/assistant-tutorial Esegue una procedura dettagliata interattiva in 11 passaggi. /assistant-tutorial

Manutenzione e aggiornamenti

Per aggiornare il repository, l'installazione del plug-in e le librerie client:

Antigravity

Linux / macOS:

./update.sh agy          # Update Antigravity plugin
./update.sh agy --all    # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type agy
.\update.ps1 -Type agy -All

Claude Code

Linux / macOS:

./update.sh claude       # Update Claude Code plugin
./update.sh claude --all # Include all client libraries

Windows (PowerShell):

.\update.ps1 -Type claude
.\update.ps1 -Type claude -All

Disinstallazione

Per disinstallare il plug-in dell'assistente:

Antigravity

Linux / macOS:

rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell):

Remove-Item -Recurse -Force `
  "$HOME\.gemini\config\plugins\google-ads-api-developer-assistant"

Poi riavvia la sessione host di Antigravity.

Claude Code

In una sessione Claude Code attiva:

/plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

In alternativa, dal terminale:

claude plugin uninstall \
  google-ads-api-developer-assistant@google-ads-assistant-local

(Facoltativo) Rimuovi il registry del marketplace locale:

claude plugin marketplace remove google-ads-assistant-local

Community e assistenza

Linee guida per i contributi

I contributi sono benvenuti. Per le linee guida, consulta il file CONTRIBUTING.md nel repository GitHub.

Passaggi successivi

Indietro
Che cos'è l'assistente per sviluppatori dell'API Google Ads?