Flusso di lavoro per l'autenticazione di un singolo utente

Nota: questa guida presuppone che tu abbia familiarità con il modello di accesso di Google Ads. In caso contrario, ti consigliamo di leggere la guida al modello di accesso di Google Ads per acquisire familiarità con i concetti. Per il corretto funzionamento dell'API Google Ads, devi anche configurare le credenziali OAuth utilizzando lo stesso progetto cloud Google Cloud in cui hai attivato l'API Google Ads e richiesto un livello di accesso API appropriato.

Attenzione: Google consiglia di utilizzare il workflow dell'account di servizio anziché il workflow di autenticazione per utente singolo. Utilizza il workflow di autenticazione per un singolo utente solo quando non è possibile utilizzare i service account.

Analogamente al flusso di lavoro dell'account di servizio, il flusso di autenticazione per 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 propri account Google Ads per suo conto, concedendo così all'app l'accesso a tutti gli account Google Ads.

Poiché è coinvolto un solo utente, puoi fare affidamento su 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 workflow è quando è possibile accedere ai tuoi account tramite un numero limitato di accessi utente (ad esempio, 3-4 utenti), per cui l'impegno di sviluppo per creare un workflow di autenticazione multiutente OAuth completo non è giustificato rispetto all'impegno per ottenere l'autorizzazione per 3-4 utenti utilizzando uno strumento a riga di comando come gcloud CLI.

Svantaggi

Questo flusso presenta alcuni svantaggi rispetto al flusso di lavoro del service account:

• Il workflow di autenticazione utente richiede la creazione di un ID client e un secret OAuth 2.0 nella console API di Google, il che richiede più passaggi di configurazione rispetto alla creazione di un service account e di una chiave.
• Se l'utente autorizzato lascia il team o l'azienda, l'app potrebbe smettere di funzionare se rimuovi l'utente dai tuoi account o disattivi il suo account utente. I service account non sono legati a singoli utenti, quindi questo rischio viene evitato.
• Per proteggersi dalla compromissione dell'account dovuta a malware o phishing, l'utente che autorizza l'account Google Ads deve eseguire l'autenticazione con una passkey durante la generazione dei token di aggiornamento OAuth 2.0. I service account non richiedono passkey e sono meno vulnerabili agli attacchi mirati agli utenti, come il phishing.

Genera credenziali

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

1. Configura 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 Configura 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 clic sul pulsante Scarica JSON nella finestra di dialogo di conferma. Salva il file come credentials.json.

3. Identifica un account utente che ha accesso a tutti gli account Google Ads che vuoi gestire utilizzando la tua app. Se esistono account senza accesso, concedi l'accesso all'account a quell'utente. Assicurati che questo account utente abbia configurato una passkey (prima che una passkey appena creata diventi affidabile, potrebbe essere previsto un ritardo di sicurezza di 7 giorni).

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 è 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
   

5. Genera un token di aggiornamento OAuth 2.0 eseguendo lo strumento gcloud CLI con il file credentials.json del passaggio precedente. Il passaggio del parametro --client-id-file è obbligatorio per l'emissione del token di aggiornamento nel progetto della console API di Google anziché nel progetto predefinito di 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

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. Accedi come utente selezionato nei passaggi precedenti e verifica la tua identità utilizzando una passkey. Se la tua app non è verificata, potresti visualizzare una schermata di avviso. In questi casi, puoi fare clic sul link Avanzate e poi sull'opzione Vai a PROJECT_NAME (non sicuro).

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, a indicare 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]
   

   Apri il file application_default_credentials.json. I contenuti sono 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. Se l'utente autorizzato accede agli account cliente tramite un account amministratore Google Ads, imposta login-customer-id (o loginCustomerId) sull'ID cliente di 10 cifre di quell'account amministratore senza trattini.

Java

Configura le seguenti chiavi nel file ads.properties.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Per ulteriori opzioni, consulta la guida alla configurazione.

.NET

Imposta le credenziali OAuth 2.0 nell'istanza GoogleAdsConfig e utilizzale per inizializzare l'oggetto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

Per ulteriori 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_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

Per ulteriori opzioni, consulta la guida alla configurazione.

PHP

Configura le seguenti chiavi nel file 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 ulteriori 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_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Per ulteriori 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 ulteriori 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://oauth2.googleapis.com/token

Puoi utilizzare il token di accesso nelle chiamate API. L'esempio seguente mostra come generare un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non illustra i dettagli dei report.

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_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"
}