Guida alle operazioni preliminari dell'API Google Ads

Questa guida descrive la procedura end-to-end per l'onboarding, l'autenticazione e la prima chiamata all'API Google Ads.

1. Prerequisiti e gerarchia degli account

Prima di interagire con l'API Google Ads, devi comprendere la gerarchia degli account e disporre della struttura dell'account di primo livello corretta.

  • Account amministratore (Centro clienti): un account amministratore Google Ads (in precedenza Centro clienti) è un account principale utilizzato per visualizzare e gestire più account cliente. Devi disporre di un account amministratore per richiedere un token sviluppatore dell'API Google Ads.
  • Account cliente: l'account standard in cui vengono creati campagne, gruppi di annunci e annunci e viene configurata la fatturazione.

Elemento di azione: se non hai un account amministratore, creane uno in Account amministratore Google Ads.

2. Ottieni un token sviluppatore

Il token sviluppatore identifica in modo univoco la tua applicazione nell'API Google Ads e controlla il livello di accesso al volume di chiamate.

Passaggi per presentare la domanda di adesione

  1. Accedi all'account amministratore Google Ads.
  2. Vai a Strumenti e impostazioni > Configurazione > Centro API (o Amministratore > Centro API).
  3. Compila il modulo con i dettagli dello sviluppatore e accetta i Termini di servizio dell'API.
  4. Invia la tua richiesta.

Livelli di accesso

  • In attesa di approvazione: i token appena creati ricevono immediatamente lo stato "In attesa". Puoi utilizzare un token in attesa per connetterti immediatamente agli account di test, ma non funzionerà con gli account di produzione.
  • Accesso di base: consente fino a 15.000 operazioni API al giorno una volta approvato.
  • Accesso standard: operazioni API giornaliere illimitate per le applicazioni che soddisfano le Funzionalità minime obbligatorie (RMF).

3. Configura gli account di test

Lo sviluppo e il test con gli account di produzione comportano il rischio di una spesa pubblicitaria e di modifiche alle campagne indesiderate. È consigliabile eseguire tutto lo sviluppo attivo con gli account di test.

Crea un account amministratore di test

  1. Vai alla pagina di creazione dell'account amministratore di test di Google Ads.
  2. Accedi con un Account Google non ancora collegato al tuo account amministratore Google Ads di produzione.
  3. Inserisci un nome descrittivo per l'account (ad es. MyCompany Test MCC).
  4. Seleziona l'utilizzo principale come Gestisci gli account di altre persone.
  5. Scegli il paese di fatturazione, il fuso orario e la valuta. Fai clic su Salva e continua.

Crea un account cliente di test

Una volta creato l'account amministratore di test, devi creare almeno un account cliente secondario per eseguire campagne di test.

  1. Accedi all'account amministratore di test appena creato.
  2. Nel menu di navigazione a sinistra, fai clic su Account, quindi seleziona Impostazioni subaccount (o Rendimento).
  3. Fai clic sul pulsante blu + (più) e seleziona Crea nuovo account.
  4. Seleziona Account Google Ads.
  5. Inserisci un nome account (ad es. Test Client Account A).
  6. Seleziona un fuso orario e una valuta, quindi fai clic su Salva e continua.
  7. Prendi nota dell'ID cliente a 10 cifre (ad es. 1234567890 senza trattini) di questo nuovo account cliente.

Regole importanti per gli account di test

  • Utilizzo del token sviluppatore: non richiedere un token sviluppatore dal tuo account amministratore di test. Utilizza sempre il token sviluppatore in attesa o approvato dal tuo account amministratore di produzione.
  • Fatturazione: gli account di test non pubblicano annunci effettivi, quindi non devi inserire dati di fatturazione reali.

4. Configurazione del progetto Google Cloud

Tutte le richieste API devono essere autenticate utilizzando un progetto Google Cloud con l'API Google Ads abilitata.

Passaggi per abilitare l'API

  1. Vai alla console Google Cloud.
  2. Crea un nuovo progetto o seleziona un progetto esistente.
  3. Vai ad API e servizi > Libreria.
  4. Cerca API Google Ads e fai clic su Abilita.

Prezzi e fatturazione

  • Nessun costo per l'API: la creazione di un progetto Google Cloud, l'abilitazione dell'API Google Ads e la generazione delle credenziali OAuth 2.0 sono completamente senza costi. Google non addebita alcun costo per le chiamate o l'utilizzo dell'API Google Ads.
  • Altre risorse cloud: i costi di Google Cloud verranno addebitati solo se utilizzi attivamente altri servizi Google Cloud fatturabili (come Compute Engine, Cloud Run o BigQuery) oltre i limiti del livello senza costi per ospitare la tua applicazione o archiviare i dati degli annunci.

5. Configurazione dell'autenticazione OAuth 2.0

L'API Google Ads utilizza OAuth 2.0 per autenticare e autorizzare le richieste.

Passaggi per il flusso dell'applicazione desktop

  1. Nel progetto Google Cloud, vai ad API e servizi > Schermata consenso OAuth e configura la schermata per il consenso. Aggiungi il tuo indirizzo email alla sezione Utenti di test mentre l'app è in stato di test per evitare errori di accesso durante l'autorizzazione.
  2. Vai ad API e servizi > Credenziali.
  3. Fai clic su Crea credenziali > ID client OAuth.
  4. Seleziona il tipo di applicazione App desktop.
  5. Fai clic su Crea, quindi scarica il file delle credenziali OAuth come client_secret.json (o copia Client ID e Client Secret).

Genera un token di aggiornamento

Una volta ottenuti l'ID client e il client secret, devi generare un token di aggiornamento. Puoi farlo utilizzando Google OAuth 2.0 Playground o uno script della libreria client.

Metodo A: utilizza Google OAuth 2.0 Playground

  1. Vai a Google OAuth 2.0 Playground.
  2. Fai clic sull'icona a forma di ingranaggio (configurazione OAuth 2.0) nell'angolo in alto a destra.
  3. Seleziona la casella Utilizza le tue credenziali OAuth.
  4. Inserisci Client ID e Client Secret OAuth2, quindi fai clic su Chiudi.
  5. Nel passaggio 1 (Seleziona e autorizza le API) a sinistra, inserisci l'ambito dell'API Google Ads nel campo "Inserisci i tuoi ambiti": https://www.googleapis.com/auth/adwords
  6. Fai clic su Autorizza API. Quando ti viene richiesto, accedi con l'Account Google che ha accesso al tuo account amministratore Google Ads (o account di test).
  7. Fai clic su Continua nella schermata per il consenso.
  8. Nel passaggio 2 (Scambia codice di autorizzazione per i token), fai clic sul pulsante blu Scambia codice di autorizzazione per i token.
  9. Il tuo Refresh token e il tuo Access token verranno visualizzati nel riquadro della risposta. Copia e salva il Refresh token.

Metodo B: utilizza lo script della libreria client (esempio in Python)

La libreria client Python ufficiale fornisce uno script helper integrato per generare le credenziali. In alternativa, puoi scaricare client_secret.json dalla console Google Cloud ed eseguire il seguente script Python autonomo:

  1. Installa la libreria OAuth richiesta:
pip install google-auth-oauthlib
  1. Crea uno script denominato generate_refresh_token.py nella stessa directory di client_secret.json ed eseguilo:
from google_auth_oauthlib.flow import InstalledAppFlow

CLIENT_SECRETS_FILE = "client_secret.json"
SCOPES = ["https://www.googleapis.com/auth/adwords"]

def main():
    flow = InstalledAppFlow.from_client_secrets_file(
        CLIENT_SECRETS_FILE, SCOPES
    )
    credentials = flow.run_local_server(port=0)
    
    print("\nAuthorization Successful!\n")
    print(f"Refresh Token: {credentials.refresh_token}")

if __name__ == "__main__":
    main()

6. Configurazione della libreria client e delle credenziali

Google fornisce librerie client supportate ufficialmente che gestiscono l'autenticazione, la serializzazione e la comunicazione con gli endpoint gRPC.

Lingue supportate

  • Python: pip install google-ads
  • Java: disponibile tramite Maven o Gradle
  • PHP: composer require googleads/google-ads-php
  • .NET: Install-Package Google.Ads.GoogleAds
  • Ruby: gem install google-ads-googleads
  • Perl: cpanm Google::Ads::GoogleAds::Client

File di configurazione (google-ads.yaml)

Crea un file di configurazione contenente le tue credenziali. Per impostazione predefinita, il metodo di inizializzazione della libreria client (ad es. GoogleAdsClient.load_from_storage()) cercherà automaticamente google-ads.yaml in due posizioni:

  1. La directory di lavoro corrente da cui viene eseguito lo script.
  2. La directory home dell'utente (~ su Linux/macOS o %HOMEPATH% su Windows).

Se memorizzi il file in una posizione personalizzata, puoi passare esplicitamente il percorso a il metodo di inizializzazione (ad es. load_from_storage("path/to/google-ads.yaml")).

developer_token: "INSERT_YOUR_DEVELOPER_TOKEN_HERE"
client_id: "INSERT_YOUR_OAUTH2_CLIENT_ID_HERE"
client_secret: "INSERT_YOUR_OAUTH2_CLIENT_SECRET_HERE"
refresh_token: "INSERT_YOUR_OAUTH2_REFRESH_TOKEN_HERE"
login_customer_id: "INSERT_YOUR_MANAGER_ACCOUNT_ID_HERE"

7. Esegui la prima chiamata API

Per verificare la configurazione dell'onboarding, esegui uno script di avvio rapido per recuperare le campagne esistenti dal tuo account di test.

Esempio di script Python (quickstart.py)

import sys
from google.ads.googleads.client import GoogleAdsClient
from google.ads.googleads.errors import GoogleAdsException

def main(client, customer_id):
    ga_service = client.get_service("GoogleAdsService")
    query = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id
    """
    
    # Issues a search request
    stream = ga_service.search_stream(customer_id=customer_id, query=query)
    for batch in stream:
        for row in batch.results:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f"'{row.campaign.name}' was found."
            )

if __name__ == "__main__":
    # Initialize client from google-ads.yaml
    # By default, load_from_storage() searches for 'google-ads.yaml' in the
    # current working directory or the user's home directory (~). You can
    # also pass an explicit path: load_from_storage("path/to/google-ads.yaml")
    try:
        googleads_client = GoogleAdsClient.load_from_storage()
        # Replace with your test client account ID (without hyphens) from
        # Section 3, NOT your manager account ID (which belongs in
        # google-ads.yaml).
        test_customer_id = "1234567890" 
        main(googleads_client, test_customer_id)
    except GoogleAdsException as ex:
        print(
            f"Request failed with status {ex.error.code().name} and "
            f"includes the following errors:"
        )
        for error in ex.failure.errors:
            print(f"\tError with message '{error.message}'.")
            if error.location:
                for field_path_element in error.location.field_path_elements:
                    print(f"\t\tOn field: {field_path_element.field_name}")
        sys.exit(1)

8. Best practice e risorse

  • Registrazione: abilita la registrazione dettagliata nella libreria client per acquisire gli ID di richiesta e risposta (request-id), che sono essenziali quando richiedi assistenza a Google.
  • Gestione degli errori: implementa una gestione degli errori efficace per GoogleAdsException, in particolare la gestione dei limiti di frequenza (RESOURCE_TEMPORARILY_EXHAUSTED).
  • Documentazione ufficiale: Documentazione per gli sviluppatori dell'API Google Ads
  • Librerie client ed esempi di codice: Repository Google Ads su GitHub
Indietro
Presentazione
Avanti
Guida rapida