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

Nota: questo strumento è un progetto open source e non un prodotto Google ufficiale.

Prerequisiti

Prima di iniziare, assicurati di disporre di quanto segue:

1. Accesso all'API Google Ads:

   • Un token sviluppatore dell'API Google Ads.
   • Un file di configurazione di Google Ads configurato con il token sviluppatore, le credenziali OAuth 2.0 e l' ID cliente, che si trova nella directory home. Consulta la guida alla configurazione della libreria client.
   • Familiarità con i concetti e l'autenticazione dell'API Google Ads.

2. Software:

   • Python 3.10 o versioni successive. Python è la lingua predefinita, quindi devi averlo installato e nel percorso.
   • Strumento a riga di comando Google Antigravity installato.
   • jq (processore JSON a riga di comando). Lo script di installazione tenterà di installarlo se manca.

3. Repository:

   • Una clonazione locale del google-ads-api-developer-assistant repository da GitHub.

Inizia

1. Vai alla directory del progetto:

   cd <full path>/google-ads-api-developer-assistant
   

   (Nota: se hai attivato l'integrazione della shell Antigravity, l'inserimento di questa directory inizializzerà automaticamente la sessione dell'assistente).

2. Esegui lo script di installazione: questo script inizializza l'ambiente di sviluppo e clona le librerie client di Google Ads richieste (Python è installato per impostazione predefinita).

   ./install.sh
   

   Se utilizzi Windows, esegui lo script di PowerShell install.ps1.

3. Configura le credenziali: assicurati che il file google-ads.yaml (o l'equivalente in lingua) sia nella directory home.

4. Interagisci con l'assistente: una volta attivata la sessione, puoi interagire con l'assistente utilizzando il linguaggio naturale 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.

  • "Quali sono i tipi di campagna disponibili?"
  • "Come faccio a filtrare per data in GAQL?"
  • "Spiega la differenza tra click_view e impression_view."

• Generazione del codice: genera query GAQL e snippet di codice Python eseguibili.

  • "Mostrami le campagne con il maggior numero di conversioni negli ultimi 30 giorni."
  • "Recupera tutti i nomi dei gruppi di annunci attivati per l'ID campagna 12345."
  • "Trova gli annunci non approvati in tutte le campagne." Il codice generato viene sottoposto automaticamente a linting utilizzando ruff e salvato nella directory saved/code/.

• Esecuzione diretta dell'API: esegui gli script Python di sola lettura generati direttamente in un ambiente virtuale isolato (.venv) e visualizza i risultati formattati come tabelle nel terminale.

  • Basta dire all'assistente: "Esegui il codice" o "Esegui lo script".
  • Per motivi di sicurezza, le operazioni di mutazione (creazione, aggiornamento, eliminazione) vengono generate, ma mai eseguite.

• Esportazione CSV: salva i risultati tabulari delle chiamate API in un file CSV.

  • "Salva i risultati in un file CSV." I file vengono salvati nella directory saved/csv/.

• Diagnostica e risoluzione dei problemi avanzate: ricevi assistenza per i messaggi di errore, il comportamento imprevisto dell'API o i problemi di conversione offline.

  • "Perché non vedo risultati per la mia query?"
  • "Risolvi i problemi relativi alle conversioni per il cliente 123-456-7890." (Genera un report diagnostico dettagliato in saved/data/).

• Contesto aggiuntivo: aggiungi il tuo codebase o le librerie personalizzate per il contesto.

  • Utilizza lo script update.sh con l'opzione --context_path per registrare i file di progetto: none ./update.sh --context_path /path/to/your/codebase
  • In questo modo, l'assistente può includere la logica dell'applicazione nel suo ragionamento quando crea risposte o genera codice nella lingua che preferisci.

Esempi di casi d'uso

• Report:
  • "Recupera le prime 5 parole chiave per costo per il mese scorso per il cliente 12345678."
• Struttura dell'account:
  • "Elenca tutti i nomi delle campagne e i relativi ID."
• Risoluzione dei problemi:
  • "Ho caricato 100 conversioni, ma nell'interfaccia utente ne vengono visualizzate solo 78. Come posso eseguire il debug utilizzando l'API?"
• Apprendimento:
  • "/explain what a shared set is"
• Generazione del codice:
  • "Write code to create a Performance Max campaign for company name."

Community e assistenza

• Problemi di GitHub: segnala bug, suggerisci funzionalità o chiedi assistenza nella scheda Problemi del repository.
• Discord: partecipa alla discussione nel canale #ads-api-ai-tools sul server Discord della community Google Advertising and Measurement.
• Feedback: condividi il tuo feedback tramite questo modulo di sondaggio.

Linee guida per i contributi

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