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 le informazioni di accesso dell'utente.

Questa guida spiega come configurare la libreria client Java per l'autenticazione dell'API Google Ads utilizzando i tre flussi OAuth 2.0 più comuni, oltre a spiegare le credenziali necessarie.

Per un approfondimento del modello di accesso all'API Google Ads, consulta la guida al modello di accesso a Google Ads.

Credenziali

L'accesso all'API Google Ads richiede un token sviluppatore, credenziali OAuth 2.0 e, in alcuni casi, un ID cliente di accesso.

Token sviluppatore

Il token sviluppatore è collegato a un account amministratore e può essere trovato nell'interfaccia web di Google Ads.

Sebbene il token sviluppatore sia collegato a un account amministratore, non fornisce l'accesso a questo account. Il token sviluppatore concede invece l'accesso all'API in generale e l'accesso a livello di account viene configurato tramite OAuth 2.0.

Nella libreria client, il token sviluppatore viene specificato dalla chiave api.googleads.developerToken nel file ads.properties.

Credenziali OAuth 2.0

Per autorizzare gli utenti dell'Account Google con accesso agli account Google Ads, devi fornire un insieme di credenziali OAuth 2.0. Il tipo di credenziali richieste varia a seconda del flusso OAuth 2.0 utilizzato.

La libreria supporta tre flussi:

  • Flusso del service account
  • Flusso di autenticazione per un singolo utente
  • Flusso di autenticazione multiutente

Per informazioni dettagliate sui flussi OAuth dell'API Google Ads, consulta la panoramica di OAuth e segui le istruzioni per il flusso più adatto alle tue esigenze per ottenere le credenziali richieste.

ID cliente di accesso

(Facoltativo) Specifica l'ID cliente di un account amministratore che fornisce l'accesso all'account di pubblicazione. Questa opzione deve essere specificata se l'accesso all'account cliente avviene tramite un account amministratore. Non è necessario specificare tutti gli account amministratore nel percorso dell'ID cliente, ma solo l'ID amministratore di livello superiore che utilizzi per le autorizzazioni di accesso. Per ulteriori dettagli, consulta la documentazione correlata.

Nella libreria client, l'ID cliente di accesso viene specificato dalla chiave api.googleads.loginCustomerId nel file ads.properties.

Configurazione

Puoi configurare la libreria client con un file ads.properties, variabili di ambiente o in modo programmatico. Questa guida si concentra sull'utilizzo di un file ads.properties. Per informazioni dettagliate su tutte le opzioni, consulta la guida alla configurazione.

Se utilizzi un file ads.properties, inseriscilo nella directory home: ~/ads.properties.

Flussi di lavoro OAuth

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

Flusso del service account

Questo è il flusso di lavoro consigliato se il tuo flusso di lavoro 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.

Una volta ottenuto il file JSON della chiave privata, aggiungi quanto segue al file ads.properties:

api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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 un account amministratore dell'API Google Ads e collegare tutti gli account Google Ads a questo account amministratore.
  2. L'utente esegue uno strumento a riga di comando come gcloud o l'esempio di codice GenerateUserCredentials per autorizzare l'app a gestire tutti i suoi account Google Ads per suo conto.

Una volta ottenute queste credenziali, aggiungi quanto segue al file ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

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. Il GenerateUserCredentials è un esempio di codice da riga di comando che illustra come ottenere l'autenticazione utente in fase di runtime per gestire i propri account Google Ads per loro conto. Puoi utilizzare questo esempio di codice come riferimento per creare app desktop che richiedono l'autenticazione utente.

Aggiungi quanto segue al file ads.properties:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

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

Cosa succede se l'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 Java fornisce i seguenti esempi di codice che illustrano come gestire questi casi.

  1. L'esempio di codice GetAccountHierarchy mostra come recuperare l'elenco di tutti gli account in un account amministratore Google Ads.
  2. L'esempio di codice ListAccessibleCustomers mostra come recuperare l'elenco di tutti gli account a cui un utente ha accesso diretto. Questi account possono essere utilizzati come valori validi per l'impostazione LoginCustomerId.

Credenziali predefinite dell'applicazione

La libreria client Java supporta anche l'autenticazione con le credenziali predefinite dell'applicazione.

Questo è particolarmente utile per lo sviluppo locale o per lo sviluppo con diverse API di Google, in quanto puoi riutilizzare le stesse credenziali, a condizione che possano accedere agli ambiti OAuth 2.0 corretti.

Per l'API Google Ads, assicurati che le credenziali predefinite dell'applicazione possano accedere all'ambito OAuth 2.0 https://www.googleapis.com/auth/adwords.

Per utilizzare le credenziali predefinite dell'applicazione, imposta l'opzione api.googleads.useApplicationDefaultCredentials su true nel file ads.properties. Quando utilizzi le credenziali predefinite dell'applicazione, l'ID client, il client secret e il token di aggiornamento non devono essere impostati.