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 dell'API Google Ads di accedere all'account Google Ads di un utente senza dover gestire o archiviare le informazioni 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 a 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 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. 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 il di 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 le 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 del service account.

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 come gcloud CLI o l'esempio di codice generate_user_credentials per autorizzare l'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 le 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 scaricare il file JSON che include l'ID client e il client secret del tuo progetto.

  2. Clona la libreria client Python sul tuo computer 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 le 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 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. La tua app crea e gestisce le credenziali utente OAuth 2.0. La libreria può essere inizializzata utilizzando le credenziali dell'utente come segue, presupponendo che l'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 quando si ottengono 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 di autenticazione multiutente.

Autenticazione manuale

Puoi generare le credenziali di autenticazione con qualsiasi approccio e fornirle manualmente a GoogleAdsClient creando direttamente un'istanza della classe client. Supponendo che l'oggetto delle credenziali creato 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 di un account amministratore Google Ads.
  2. L' esempiolist_accessible_customers di codice 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 login_customer_id.