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

L'Assistente sviluppatore dell'API Google Ads porta la profonda competenza nel 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 contratti AGENTS.md e CLAUDE.md, comandi slash integrati e 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: ```bash ./install.sh agy

Oppure includi librerie client aggiuntive:

./install.sh agy --java --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type agy

Oppure includi librerie client aggiuntive:

.\install.ps1 -Type agy -Java -Dotnet ```

Claude Code

Linux / macOS: ```bash ./install.sh claude

Oppure includi librerie client aggiuntive:

./install.sh claude --php --dotnet ```

Windows (PowerShell): ```powershell .\install.ps1 -Type claude

Oppure includi librerie client aggiuntive:

.\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 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 o su risorse specifiche. L'assistente basa le risposte sulle definizioni API ufficiali anziché affidarsi esclusivamente all'addestramento LLM generale.

    • "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 insieme condiviso e come faccio a utilizzarlo?"
    • Comandi slash di Claude Code: /explain, /step-by-step, /assistant-tutorial

  • Generazione di codice della libreria client basato su dati: 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 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 API attiva senza overhead dei metadati remoti.

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

  • Report live ad hoc ed esportazione CSV: richiedi 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.

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

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

    • Basta dire all'assistente: "Esegui il codice" o "Esegui lo script".
    • Sicurezza delle modifiche: per motivi di sicurezza, le operazioni di modifica (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 di diagnostica dettagliati.

    • Claude Code: /troubleshoot-conversions
    • Linguaggio naturale: "Risolvi i problemi di conversione per il cliente 123-456-7890." (I report vengono salvati in saved/data/).

  • Mappatura della gerarchia degli account Centro clienti: 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 dei clienti sotto l'amministratore 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 delle pagine web per la mia campagna PMax"

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

    • Linux / macOS: bash ./update.sh agy --context_dir /path/to/your/codebase # Or for Claude Code: ./update.sh claude --context_dir /path/to/your/codebase
    • Windows (PowerShell): 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 del Centro clienti 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 di 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: bash ./update.sh agy # Update Antigravity plugin ./update.sh agy --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type agy .\update.ps1 -Type agy -All

Claude Code

Linux / macOS: bash ./update.sh claude # Update Claude Code plugin ./update.sh claude --all # Include all client libraries

Windows (PowerShell): powershell .\update.ps1 -Type claude .\update.ps1 -Type claude -All

Disinstallazione

Per disinstallare il plug-in dell'assistente:

Antigravity

Linux / macOS: bash rm -rf ~/.gemini/config/plugins/google-ads-api-developer-assistant

Windows (PowerShell): 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: none /plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

Oppure dal terminale: bash claude plugin uninstall google-ads-api-developer-assistant@google-ads-assistant-local

(Facoltativo) Rimuovi il registro del marketplace locale: bash 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?