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'applicazione client API Google Ads di accedere all'account Google Ads di un utente senza dover gestire o memorizzare 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 a 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 l'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. La libreria Python è configurata come segue:

  • Se utilizzi un file google-ads.yaml o una stringa YAML, aggiungi quanto segue alla configurazione per impostare il percorso del file JSON della chiave privata nell'ambiente locale:

    json_key_file_path: JSON_KEY_FILE_PATH

    Quindi chiama i metodi load_from_storage o load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

  • Se utilizzi un dict per configurare la libreria, includi la seguente coppia chiave-valore e chiama il metodo load_from_dict, passando la configurazione dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "json_key_file_path": JSON_KEY_FILE_PATH
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

    Quindi chiama il metodo load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()
  ```

Se l'opzione di configurazione json_key_file_path è presente in uno di questi metodi di configurazione e l'opzione use_application_default_credentials è False o non è impostata, la libreria autorizzerà automaticamente l'utilizzo del flusso dell'account di servizio.

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 uno strumento come gcloud CLI o l'generate_user_credentialsesempio di codice per autorizzare la tua app a gestire tutti i suoi account Google Ads per suo conto.

La libreria può essere inizializzata utilizzando le credenziali OAuth 2.0 dell'utente come segue:

Se utilizzi lo strumento gcloud CLI (consigliato)

  1. Segui la documentazione Genera credenziali per configurare le credenziali predefinite dell'applicazione (ADC) nel tuo ambiente locale.

  2. Aggiungi la seguente configurazione alla stringa google-ads.yaml o YAML:

    use_application_default_credentials: true

    Quindi chiama il metodo load_from_storage o load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Se utilizzi un dict per configurare la libreria, includi la seguente coppia chiave-valore e chiama il metodo load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "use_account_default_credentials": True
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true

    Quindi chiama il metodo load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Se gestisci direttamente i token OAuth

  1. Segui i passaggi per configurare un progetto della console e scarica il file JSON che include l'ID client e il client secret del tuo progetto.

  2. Clona la libreria client Python sulla tua macchina e passa alla relativa directory:

    $ git clone https://github.com/googleads/google-ads-python.git
$ cd google-ads-python

  3. Esegui l'esempio fornendo un percorso assoluto al file JSON scaricato nel passaggio 1:

    $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON

    Al termine, nella console viene stampato un token di aggiornamento. Copialo e salvalo per il passaggio successivo.

  4. Configura la libreria aggiungendo le seguenti impostazioni alla configurazione che preferisci:

    Aggiungi la seguente configurazione alla stringa google-ads.yaml o YAML:

    client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_REFRESH_TOKEN_HERE

    Quindi chiama il metodo load_from_storage o load_from_string:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_storage()

    Se utilizzi un dict per configurare la libreria, includi le seguenti coppie chiave-valore e chiama il metodo load_from_dict:

    from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
  "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
  "refresh_token": INSERT_REFRESH_TOKEN_HERE
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

    export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE

    Quindi chiama il metodo load_from_env:

    from google.ads.googleads.client import GoogleAdsClient
client = GoogleAdsClient.load_from_env()

Per saperne di più, consulta la guida al flusso di lavoro per l'autenticazione di 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. La tua app crea e gestisce le credenziali utente OAuth 2.0. La libreria può essere inizializzata utilizzando le credenziali dell'utente come segue, il che presuppone che la tua applicazione ottenga le credenziali in fase di runtime, eseguendo un flusso di autorizzazione o caricandole da un datastore:

Un dict è il meccanismo di configurazione più semplice da utilizzare per ottenere le credenziali in fase di runtime:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

Autenticazione manuale

Puoi generare credenziali di autenticazione con qualsiasi approccio e fornirle a GoogleAdsClient creando un'istanza della classe client direttamente. Supponendo che l'oggetto delle credenziali che crei sia un'istanza di google.auth.credentials.Credentials, puoi passarlo come segue:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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 Python fornisce i seguenti esempi di codice che illustrano come gestire questi casi.

  1. L'esempio di codice get_account_hierarchy mostra come recuperare l'elenco di tutti gli account in un account amministratore Google Ads.
  2. L'esempio di codice list_accessible_customers 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 login_customer_id.