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, limiti di sicurezza solidi 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. Se vuoi, puoi includere 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. 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 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 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:poni domande sulle funzionalità dell'API Google Ads, sulle best practice o su risorse specifiche.

  • 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 su definizioni API ufficiali anziché basarsi esclusivamente sull'addestramento generale degli 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 usa?"
    • Comandi slash di Claude Code:/explain, /step-by-step, /assistant-tutorial

  • Generazione di codice della libreria client basata su dati reali:genera codice testato e idiomatico 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 generale e convalida query complesse rispetto a metadati API, compatibilità dei campi, regole per le impressioni zero e segmentazione per data prima dell'esecuzione.

    • Codice di Claude: /validate-gaql
    • Natural Language: 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 sovraccarico di metadati remoti.

    • Codice di Claude: /inspect-object <resource_or_enum>
    • Linguaggio naturale: "Inspect campaign resource" (Ispeziona risorsa campagna)

  • Report in tempo reale ad hoc ed esportazione CSV: chiedi i dati sul rendimento in inglese semplice. L'assistente crea, convalida ed esegue query GAQL direttamente nel 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 mutazioni:esegui script di sola lettura generati direttamente in un ambiente virtuale gestito.

    • Basta dire all'assistente: "Esegui il codice" o "Esegui lo script".
    • Mutate Safety: per 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.

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

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

    • Codice di Claude: /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 di pagine web per i gruppi di asset.

    • Codice di Claude: /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: 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 con barra incorporati. 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à chiave:

Comando slash Finalità Esempio
/validate-gaql Convalida la sintassi, la compatibilità e le regole GAQL. /validate-gaql
/inspect-object Ispeziona campi, tipi ed 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: 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 attiva di Claude Code: 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?