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 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 di Google Ads

Per lavorare in modo efficace con l'API Google Ads, devi comprendere come funziona il modello di accesso di Google Ads. Consulta la guida al modello di accesso di Google Ads.

Flussi di lavoro OAuth

Esistono tre workflow comuni utilizzati quando si lavora con l'API Google Ads.

Flusso del service account

Questo è il flusso di lavoro consigliato se non richiede alcuna interazione umana. Questo workflow 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. Per configurarlo, crea e scarica il file della chiave JSON nella console Google Cloud, quindi copia google_ads_config.rb nella tua home directory e modificalo per specificare la posizione del file della chiave dell'account di servizio (e l'indirizzo email facoltativo dell'utente da impersonare quando utilizzi la delega a livello di dominio di Google Workspace):

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Se preferisci non archiviare queste informazioni in un file e preferisci utilizzare le variabili di ambiente, puoi impostare GOOGLE_ADS_JSON_KEY_FILE_PATH (e facoltativamente GOOGLE_ADS_IMPERSONATED_EMAIL):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Puoi anche passare il percorso del file della chiave del service account (e l'indirizzo email facoltativo di cui è stata eseguita la simulazione) in modo programmatico in fase di runtime:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

In alternativa, puoi utilizzare la gemma googleauth per creare le credenziali del service account e passare credentials.updater_proc a config.authentication:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

Per saperne di più, consulta la guida al flusso di lavoro dei service account.

Flusso di autenticazione per un singolo utente

Questo flusso di lavoro può essere utilizzato se non puoi utilizzare i service account. Questo workflow 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 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, ad esempio lo strumento a riga di comando Google Cloud o l' esempio di codice GenerateUserCredentials, per autorizzare la tua app a gestire tutti i suoi account Google Ads per suo conto.

Le credenziali OAuth 2.0 possono essere configurate per Ruby copiando il file google_ads_config.rb nella tua home directory e modificandolo in modo da includere l'ID client, il client secret e il token di aggiornamento:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

Il client legge automaticamente il file di configurazione dalla home directory se viene creata un'istanza senza argomenti:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

In alternativa, se preferisci archiviare il file altrove, puoi creare un'istanza del client passando il percorso in cui conservi il file:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Se preferisci non archiviare queste informazioni in un file e utilizzare invece le variabili di ambiente, puoi impostarle singolarmente:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Puoi anche passare le informazioni in modo programmatico in fase di esecuzione:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

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 autorizzarla a gestire i loro account Google Ads per loro conto. La tua app crea e gestisce le credenziali utente OAuth 2.0. Questo flusso di lavoro può essere configurato in modo simile al flusso per un singolo utente, con l'aggiunta di login_customer_id.

Ti consigliamo di utilizzare un file di configurazione. Copia il file google_ads_config.rb nella tua home directory e modificalo in modo da includere l'ID client, il client secret, il token di aggiornamento e l'ID cliente:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

Il client legge automaticamente il file di configurazione dalla home directory se viene creata un'istanza senza argomenti:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

In alternativa, se preferisci archiviare il file altrove, puoi creare un'istanza del client passando il percorso in cui conservi il file:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Se preferisci non archiviare queste informazioni in un file e utilizzare invece le variabili di ambiente, puoi impostarle singolarmente:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Puoi anche passare le informazioni in modo programmatico in fase di esecuzione:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Per saperne di più, consulta la guida al flusso di lavoro di autenticazione multiutente. La libreria client Ruby include un esempio di codice come riferimento. L'esempio di codice della riga di comando GenerateUserCredentials illustra come ottenere l'autenticazione dell'utente in fase di runtime per gestire i suoi account Google Ads per suo conto. Puoi utilizzare questo esempio di codice come riferimento per creare app desktop che richiedono l'autenticazione utente.

Gestire più account

È comune 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 Ruby 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 di 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 quindi essere utilizzati come valori validi per l'impostazione login_customer_id.

Credenziali predefinite dell'applicazione

La libreria client Ruby (v36.1.0 e successive) supporta anche l'autenticazione con le Credenziali predefinite dell'applicazione (ADC). Ti consente di impostare le credenziali predefinite per la tua applicazione senza dover configurare le informazioni OAuth 2.0 all'interno della configurazione 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 richiesti.

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, utilizza lo strumento a riga di comando Google Cloud ed esegui l'autenticazione per ADC:

gcloud auth application-default login

Questo comando apre un browser web per completare il flusso di autenticazione per il tuo Account Google. Una volta autorizzato, archivia le credenziali in una posizione standard. Devi quindi aggiornare l'applicazione per utilizzare ADC.

Copia il file google_ads_config.rb nella tua home directory e imposta use_application_default_credentials su true:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

Se preferisci non archiviare queste informazioni in un file e utilizzare invece le variabili di ambiente, puoi impostare GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Puoi anche trasmettere le informazioni in modo programmatico in fase di runtime. Quando inizializzi il client nel codice Ruby, imposta config.use_application_default_credentials = true e non fornire credenziali OAuth 2.0 esplicite. La libreria rileva e utilizza automaticamente le credenziali configurate dallo strumento a riga di comando di Google Cloud:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

Per ulteriori dettagli sulle opzioni disponibili per configurare la libreria client Ruby, consulta la pagina di configurazione.