Autenticazione e autorizzazione

Come altre API di Google, l'API Google Ads utilizza il protocollo OAuth 2.0 per l'autenticazione e l'autorizzazione. OAuth 2.0 consente all'app client dell'API Google Ads di accedere all'account Google Ads di un utente senza dover gestire o archiviare i dati di accesso dell'utente.

Informazioni sul modello di accesso a Google Ads

Per lavorare in modo efficace con l'API Google Ads, devi comprendere come funziona il modello di accesso di Google Ads. Ti consigliamo di leggere la guida al modello di accesso di Google Ads.

Flussi di lavoro OAuth

Esistono tre flussi di lavoro comuni utilizzati quando si lavora con l'API Google Ads.

Flusso service account

Questo è il flusso di lavoro consigliato se non richiede alcuna interazione umana. Questo flusso di lavoro richiede un passaggio di configurazione, in cui l'utente aggiunge un service account al proprio account Google Ads. L'app può quindi utilizzare le credenziali del service account per gestire l'account Google Ads dell'utente.

Ecco come configurare OAuth2 per l'accesso API utilizzando le tue credenziali con un service account nella libreria client Perl:

1. Crea le credenziali OAuth2:

   Segui le istruzioni per generare un service account e un file *.JSON.

2. Configura la libreria client:

   Imposta il percorso JSON della chiave privata nella configurazione. Se utilizzi un file googleads.properties, aggiungi quanto segue:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   

   Se utilizzi variabili di ambiente, aggiungi quanto segue alla configurazione o all'ambiente Bash:

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
   

   Punto chiave: durante il caricamento delle configurazioni, la libreria cerca prima le credenziali dai flussi delle app web o desktop OAuth2 e le utilizza se le trova. Pertanto, se vuoi utilizzare un service account per l'autenticazione, assicurati che le credenziali per gli altri flussi non siano presenti nella configurazione.

   Per saperne di più, consulta la guida al flusso di lavoro del service account.

Flusso di autenticazione per un singolo utente

Questo flusso di lavoro può essere utilizzato se non puoi utilizzare i service account. Questo flusso di lavoro richiede due passaggi di configurazione:

1. Concedi a un singolo utente l'accesso a tutti gli account da gestire utilizzando l'API Google Ads. Un approccio comune consiste nel concedere all'utente l'accesso a un account amministratore API Google Ads e collegare tutti gli account Google Ads a questo account amministratore.
2. L'utente esegue l'generate_user_credentials.pl esempio di codice per autorizzare la tua app a gestire tutti i suoi account Google Ads per suo conto.

I seguenti passaggi eseguono un esempio di codice interattivo, che richiede quindi di fornire input.

1. In un terminale, esegui l'esempio generate_user_credentials.pl nella directory examples. Puoi modificare i valori di INSERT_XXX_HERE nell'esempio prima dell'esecuzione o utilizzare gli argomenti della riga di comando -client_id per l'ID client e -client_secret per il client secret.

   perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}
   

2. Questo esempio di codice ti chiede di visitare un URL in cui devi autorizzare l'app ad accedere al tuo account Google Ads per tuo conto.

   Paste this url in your browser:
   https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...
   

   Vai all'URL in una sessione di navigazione privata o in una finestra di navigazione in incognito. Accedi con l'Account Google che utilizzi per accedere a Google Ads. In genere, si tratta di un account email che ha accesso a un account amministratore Google Ads che contiene tutti gli account che devi gestire nella sua gerarchia di account. Fai clic su Continua nella schermata per il consenso OAuth 2.0.

   

   Verrà visualizzata una pagina con un messaggio che indica che l'autorizzazione è andata a buon fine.

   Authorization code was successfully retrieved.
   

3. Torna alla console in cui stai eseguendo l'esempio di codice. Vedrai che l'esempio di codice è stato completato e mostra il token di aggiornamento e alcune istruzioni, seguite dalle istruzioni che dovrai seguire per configurare la libreria client:

   Replace the following keys and values in your googleads.properties configuration file:
   
   clientId==***********************apps.googleusercontent.com
   clientSecret=****
   refreshToken=****
   

4. Premi Ctrl + C per terminare la procedura. Poi copia il token di aggiornamento generato insieme all'ID client e al client secret nel file googleads.properties o salvalo altrove per utilizzarlo se istanzi la libreria in fase di runtime.

La libreria può essere inizializzata utilizzando le credenziali OAuth 2.0 dell'utente impostando quanto segue in googleads.properties:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

In alternativa, utilizza le variabili di ambiente:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

Per saperne di più, consulta la guida al flusso di lavoro per l'autenticazione utente singolo.

Flusso di autenticazione multiutente

Questo è il flusso di lavoro consigliato se la tua app consente agli utenti di accedere e autorizzare la tua app a gestire i propri account Google Ads per loro conto. La tua app crea e gestisce le credenziali utente OAuth 2.0.

Per Perl, in genere implementi un flusso di applicazione web in cui la tua applicazione gestisce il reindirizzamento OAuth 2.0 e la gestione dei token. L'utente esegue l'autenticazione tramite la tua applicazione, che memorizza e utilizza il token di aggiornamento dell'utente per effettuare chiamate API per suo conto.

La configurazione per l'utilizzo delle credenziali ottenute è la stessa del flusso di autenticazione per un singolo utente:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID

In alternativa, utilizza le variabili di ambiente:

export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

Per saperne di più, consulta la guida al flusso di lavoro per l'autenticazione multiutente.

Cosa succede se il mio utente gestisce più account?

È normale che un utente gestisca più di un account Google Ads, tramite l'accesso diretto agli account o tramite un account amministratore Google Ads. La libreria client Perl fornisce esempi che illustrano come gestire questi casi.

1. L'esempio get_account_hierarchy.pl mostra come recuperare l'elenco di tutti gli account in un account amministratore Google Ads.
2. L'esempio list_accessible_customers.pl mostra come recuperare l'elenco di tutti gli account a cui un utente ha accesso diretto. Questi account possono poi essere utilizzati come valori validi per l'impostazione LoginCustomerId nel file googleads.properties o per la variabile di ambiente GOOGLE_ADS_LOGIN_CUSTOMER_ID.