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, in genere 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 è il linguaggio predefinito, quindi devi averlo installato e nel percorso.
   • gemini-cli installato.
   • jq (processore JSON da 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
   

2. Esegui lo script di configurazione: questo script configura gemini-cli per utilizzare i file di contesto GEMINI.md dell'assistente e gli strumenti necessari.

   ./install.sh
   

   Se utilizzi Windows, esegui lo script PowerShell setup.ps1.

3. Avvia gemini-cli:

   gemini
   

4. Interagisci con l'assistente: ora puoi porre domande o dare comandi in linguaggio naturale.

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 salvato nella directory saved_code/.

• Esecuzione diretta dell'API: esegui gli script Python di sola lettura generati direttamente da gemini-cli e visualizza i risultati formattati nel terminale. Dopo che l'assistente ha generato il codice, riceverai un prompt sullo schermo:

To run this script, you will need to replace YOUR_CUSTOMER_ID with your actual
Google Ads customer ID and execute the following command in
your shell: <command>

Inserisci run e lo script verrà eseguito nel contesto dell'assistente se la lingua predefinita è Python, Ruby o PHP. I linguaggi compilati non verranno eseguiti a causa delle norme di sicurezza.

• 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/.

• Assistenza per la risoluzione dei problemi: ricevi assistenza per i messaggi di errore o per il comportamento imprevisto dell'API.

  • "Ho ricevuto l'errore 'AuthenticationError.OAUTH_TOKEN_INVALID'. Che cosa devo fare?"
  • "Perché non vedo risultati per la mia query?"

• Contesto aggiuntivo: aggiungi la tua codebase per il contesto.

  • A partire dalla versione 2.3.0, utilizza il flag context_dir per includere i file del progetto: ./update.sh --context_dir /path/to/your/codebase In questo modo, l' assistente può includere la logica dell'applicazione nel suo ragionamento durante la creazione delle risposte.
  • Questa funzionalità consente all'assistente di produrre esempi di codice salvati nella lingua scelta, fornendo assistenza anche quando non è disponibile una libreria client ufficiale.
  • Prima di richiedere l'output del codice, comunica all'assistente: write saved code examples in <language of your application>

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:
  • "Scrivi il codice per creare una campagna Performance Max per 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.