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

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

L'assistente è 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, confini 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, la libreria client Python è inclusa. 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. Configurare 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 ID cliente direttamente in config/customer_id.txt (ad esempio, 1234567890). Puoi anche ispezionare 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 Claude Code attiva, esegui /reload-plugins o riavvia claude.

5. Interagire 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 su funzionalità, regole architetturali, best practice o risorse specifiche dell'API Google Ads. L'assistente basa le risposte su definizioni API ufficiali anziché basarsi esclusivamente sull'addestramento LLM generale.

    • "Quali sono i tipi di campagna disponibili?"
    • "Come faccio a filtrare per data in GAQL?"
    • "Explain the difference between click_view and impression_view."
    • "Che cos'è un insieme condiviso e come si usa?"
    • 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."
    • "Get all enabled ad group names for customer 123-456-7890." (Ottieni 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 query complesse rispetto a metadati API, compatibilità dei campi, regole per le impressioni zero e segmentazione per data prima dell'esecuzione.

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

  • Ispezione dello schema di oggetti e 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: "Inspect campaign resource" (Esamina risorsa campagna)

  • Report live ad hoc ed esportazione in formato 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 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". (Esporta in saved/csv/).

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

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

  • Diagnostica avanzata e risoluzione dei problemi relativi alle conversioni: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 su saved/data/).

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

    • Claude Code: /get-cids <manager_cid>
    • Linguaggio naturale: "Get all client customer IDs under manager 123-456-7890"

  • Filtri ed esclusioni delle schede Performance Max:genera alberi di partizioni dei prodotti ed esclusioni di URL delle 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 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 competenza 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 le enumerazioni Protobuf. /inspect-object Campaign
/get-cids Risolve le gerarchie MCC 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 per le schede PMax. /pmax-filter
/explain Fornisce una spiegazione strutturata in quattro 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 attiva di Cloud Code:

/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?