Flusso di lavoro di autenticazione di un singolo utente

Nota: questa guida presuppone che tu conosca il modello di accesso a Google Ads. In caso contrario, ti consigliamo di leggere la guida al modello di accesso a Google Ads per acquisire familiarità con i concetti.

Attenzione: Google consiglia di utilizzare il workflow dell'account di servizio anziché quello di autenticazione di un singolo utente. Il flusso di lavoro di autenticazione di un singolo utente deve essere utilizzato solo quando non è possibile utilizzare gli account di servizio.

Analogamente al flusso di lavoro dell'account di servizio, il flusso di autenticazione di un singolo utente utilizza le funzionalità di autorizzazione e gestione degli utenti offerte dalla UI di Google Ads per concedere all'app l'accesso a tutti gli account necessari. Questo flusso di lavoro di autenticazione prevede due passaggi:

• Concedi a un singolo utente l'accesso a tutti gli account Google Ads che devono essere gestiti dall'app.
• L'utente autorizza la tua app a gestire i suoi account Google Ads per suo conto, concedendo così all'app l'accesso a tutti gli account Google Ads.

Poiché è coinvolto un solo utente, puoi utilizzare strumenti come gcloud CLI o l' esempio di codice GenerateUserCredential anziché creare il tuo flusso di autenticazione utente OAuth 2.0.

Un caso d'uso correlato per questo flusso di lavoro si verifica quando è possibile accedere ai tuoi account tramite una manciata di accessi utente (ad es. 3-4 utenti), quindi lo sforzo di sviluppo per creare un flusso di lavoro diautenticazione utente OAuth completo non è giustificato rispetto allo sforzo per ottenere l'autorizzazione per 3-4 utenti utilizzando uno strumento da riga di comando come gcloud CLI.

Svantaggi

Rispetto al workflow dell'account di servizio, questo flusso presenta alcuni svantaggi:

1. Il workflow di autenticazione utente richiede la creazione di un ID client e un client secret OAuth 2.0 nella console Google Cloud, il che richiede più passaggi di configurazione rispetto alla creazione di un account di servizio e di una chiave.
2. La tua app potrebbe dover essere sottoposta a un'ulteriore procedura di verifica dell'app Google Cloud processo.
3. Se l'utente autorizzato lascia il team o l'azienda, la tua app potrebbe smettere di funzionare se rimuovi l'utente dai tuoi account o disattivi l'account utente. Gli account di servizio non sono collegati a singoli utenti, quindi questo rischio viene evitato.
4. L'utente che autorizza l'account Google Ads deve adottare ulteriori precauzioni come attivare l'autenticazione a due fattori per proteggere il proprio Account Google da compromissioni dovute a sicurezza insufficiente, malware o phishing. Gli account di servizio sono meno vulnerabili a questo problema, poiché alcune di queste modalità di attacco non si applicano direttamente a loro.

Generare le credenziali

Nota: questa guida utilizza App desktop come tipo di app OAuth durante la creazione delle credenziali OAuth, poiché funziona meglio con gcloud CLI. Quando utilizzi il flusso di lavoro di autenticazione di un singolo utente, questo tipo di app OAuth può essere utilizzato indipendentemente dal tipo di applicazione che stai creando. Se scegli App web, devi utilizzare l'OAuth Playground per generare un token di aggiornamento. Per istruzioni, consulta il video per istruzioni.

1. Segui le istruzioni per configurare una schermata per il consenso OAuth per la tua applicazione e aggiungi https://www.googleapis.com/auth/adwords come ambito OAuth 2.0. Per maggiori dettagli, consulta Configurare la schermata per il consenso OAuth.

2. Crea un ID client e un client secret seguendo le istruzioni. Dopo aver creato il client OAuth 2.0, scarica il file JSON del client facendo prima clic sulla relativa icona Scarica client OAuth e poi sul pulsante SCARICA JSON nella schermata successiva. Salva il file come credentials.json.

3. Identifica un account utente che abbia accesso a tutti gli account Google Ads che vuoi gestire utilizzando la tua app. Se mancano accessi ad alcuni account, allora segui le istruzioni per concedere gli accessi necessari.

4. Scarica e installa gcloud CLI. Una volta installato, verifica che lo strumento funzioni correttamente eseguendo il comando gcloud version da un prompt della riga di comando. L'output potrebbe essere simile al seguente.

   :~$ gcloud version
   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   gsutil 5.30

5. Genera un token di aggiornamento OAuth 2.0 eseguendo lo strumento gcloud CLI:

   gcloud auth application-default 
   
     login --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform 
   
     --client-id-file=<path_to_credentials.json>

   Il file credentials.json è del passaggio precedente.

6. Il comando gcloud apre una finestra di accesso all'Account Google in una nuova finestra del browser e ti guida attraverso i passaggi di autenticazione OAuth 2.0. Assicurati di accedere come utente selezionato nei passaggi precedenti. Se la tua app non è verificata, potresti visualizzare una schermata di avviso. In questi casi, puoi fare clic sul link Mostra opzioni avanzate e sull'opzione Vai a PROJECT_NAME (non verificato).

   

7. Dopo aver verificato gli ambiti, fai clic sul pulsante Continua per concedere l'autorizzazione. Il browser passa a https://cloud.google.com/sdk/auth_success, indicando che l'autenticazione è andata a buon fine. La pagina mostra il seguente messaggio:

   Authorization code granted. Close this tab.

   Il comando gcloud stampa il seguente messaggio:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

   Ora apri il file application_default_credentials.json. I contenuti dovrebbero essere simili ai seguenti:

   {
   "account": "",
   "client_id": "******.apps.googleusercontent.com",
   "client_secret": "******",
   "refresh_token": "******",
   "type": "authorized_user",
   "universe_domain": "googleapis.com"
   }
   

Configurazione della libreria client

Seleziona la scheda corrispondente al tuo linguaggio di programmazione per istruzioni su come configurare la libreria client.

Java

Configura le seguenti chiavi nel 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.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Per altre opzioni, consulta la guida alla configurazione.

.NET

Puoi inizializzare l'istanza GoogleAdsClient in fase di runtime utilizzando le credenziali che hai ottenuto dall'utente per i cui account stai effettuando chiamate API.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN",
    ...
};
GoogleAdsClient client = new GoogleAdsClient(config);

Per altre opzioni, consulta la guida alla configurazione.

Python

Configura le seguenti chiavi nel file google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE

Per altre opzioni, consulta la guida alla configurazione.

PHP

Configura le seguenti chiavi in google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Per altre opzioni, consulta la guida alla configurazione.

Ruby

Configura le seguenti chiavi nel file google_ads_config.rb.

  Google::Ads::GoogleAds::Config.new do |c|
     c.client_id = 'INSERT_CLIENT_ID_HERE'
     c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
     c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
     c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
     c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  end

Per altre opzioni, consulta la guida alla configurazione.

Perl

Configura le seguenti chiavi nel file googleads.properties.

 clientId=INSERT_OAUTH2_CLIENT_ID_HERE
 clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
 refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
 loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
 

Per altre opzioni, consulta la guida alla configurazione.

curl

Inizia utilizzando un client HTTP per recuperare un token di accesso OAuth 2.0. Questa guida utilizza il comando curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Ora puoi utilizzare il token di accesso nelle chiamate API. L'esempio seguente mostra come eseguire un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non tratta i dettagli della generazione di report.

curl -i -X POST https://googleads.googleapis.com/v24/customers/CUSTOMER_ID/googleAds:searchStream \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer ACCESS_TOKEN" \
   -H "developer-token: DEVELOPER_TOKEN" \
   -H "login-customer-id: LOGIN_CUSTOMER_ID" \
   --data-binary "@query.json"

I contenuti di query.json sono i seguenti:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}