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

L'assistente per sviluppatori dell'API Google Ads porta competenze approfondite sul dominio dell'API Google Ads direttamente nel tuo ambiente di codifica 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 di integrazione.

L'assistente è stato creato 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 robusti e pipeline di convalida automatizzate.

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 della 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 piattaforma di destinazione. Per impostazione predefinita, è inclusa la libreria client Python. Puoi includere facoltativamente librerie client aggiuntive (--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) si trovi 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 controllare 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 di 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: poni domande sulle funzionalità dell'API Google Ads, sulle regole architetturali, sulle best practice o su risorse specifiche. L'assistente basa le risposte sulle definizioni ufficiali dell'API anziché affidarsi esclusivamente all'addestramento LLM generale.

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

  • Generazione di codice della libreria client basata su dati reali: 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 programmatica delle query GAQL: esegui automaticamente una prova e convalida le query complesse rispetto ai metadati dell'API, alla compatibilità dei campi, alle regole di zero impression e alla segmentazione per data prima dell'esecuzione.

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

  • Ispezione di oggetti e schemi 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 sovraccarico di metadati remoti.

    • Claude Code: /inspect-object <resource_or_enum>
    • Linguaggio naturale: "Inspect campaign resource"

  • Report live ad hoc ed esportazione CSV: chiedi i dati sul rendimento in inglese semplice. L'assistente crea, convalida ed esegue query GAQL direttamente sul tuo account, trasmettendo in streaming tabelle formattate live nel terminale.

    • "Show top 5 keywords by cost last month for customer 123-456-7890."
    • "Save the results as a CSV file." (Esporta in saved/csv/).

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

    • Di' all'assistente: "Run the code" o "Execute the script".
    • Sicurezza delle mutazioni: per motivi di sicurezza, le operazioni di mutazione (creazione, aggiornamento, eliminazione) vengono generate in saved/code/, ma non vengono mai eseguite direttamente dall'assistente. Esaminale ed eseguile manualmente al di fuori dell'assistente.

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

    • Claude Code: /troubleshoot-conversions
    • Linguaggio naturale: "Troubleshoot conversions for customer 123-456-7890." (I report vengono salvati in saved/data/).

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

    • Claude Code: /get-cids <manager_cid>
    • Linguaggio naturale: "Recupera tutti gli ID cliente dell'intermediazione sotto il gestore 123-456-7890"

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

    • Claude Code: /pmax-filter
    • Linguaggio naturale: "Crea filtri di esclusione per 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 ai 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 competenze 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 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 PMax. /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 di Claude Code attiva:

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

Oppure dal terminale:

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

(Facoltativo) Rimuovi il registro del marketplace locale:

claude plugin marketplace remove google-ads-assistant-local

Community e assistenza

Linee guida per i contributi

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

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