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 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 dell'account di servizio

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 account di servizio al proprio account Google Ads. L'app può quindi utilizzare le credenziali dell'account di servizio per gestire l'account Google Ads dell'utente. Per configurare questa opzione, crea e scarica il file di chiave JSON nella console Google Cloud, quindi copia google_ads_config.rb nella directory home e modificalo per specificare il percorso del file di chiave del service account e l'indirizzo email dell'utente di cui eseguire l'impersonificazione:

  # 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'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Se preferisci non archiviare queste informazioni in un file e utilizzare invece le variabili di ambiente, puoi impostare rispettivamente GOOGLE_ADS_JSON_KEY_FILE_PATH e GOOGLE_ADS_IMPERSONATED_EMAIL.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Puoi anche passare le informazioni in modo programmatico in fase di runtime utilizzando il gem googleauth per creare le credenziali da un file JSON dell'account di servizio:

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 = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  # Inject the service account credentials
  config.oauth2_client = credentials
end

Per saperne di più, consulta la guida al flusso di lavoro dell'account di servizio.

Flusso di autenticazione per un singolo utente

Questo flusso di lavoro può essere utilizzato se non puoi utilizzare gli account di servizio. 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 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 come l'interfaccia a riga di comando gcloud o l' esempio di codiceGenerateUserCredentials per autorizzare l'app a gestire tutti i suoi account Google Ads per suo conto.

Le credenziali OAuth 2.0 possono essere configurate per Ruby copiando il google_ads_config.rb nella directory home 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 leggerà automaticamente il file di configurazione dalla directory home 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 lo hai salvato:

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 tutte:

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 runtime:

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 autorizzare la tua app 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, ma con anche login_customer_id specificato.

Ti consigliamo di utilizzare un file di configurazione. Copia il google_ads_config.rb nella directory home 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 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 leggerà automaticamente il file di configurazione dalla directory home 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 lo hai salvato:

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 tutte:

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 runtime:

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 per saperne di più. La libreria client Ruby include un esempio di codice come riferimento. Il GenerateUserCredentials è un esempio di codice a riga di comando che illustra come ottenere l'autenticazione utente in fase di runtime per gestire gli account Google Ads per conto dell'utente. Puoi utilizzare questo esempio di codice come riferimento per creare app desktop che richiedono l'autenticazione utente.

Cosa succede se l'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 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 essere utilizzati come valori validi per l'impostazione LoginCustomerId.

Credenziali predefinite dell'applicazione

La libreria client Ruby supporta anche l'autenticazione con le credenziali predefinite dell'applicazione application default (ADC). Ti consente di impostare le credenziali predefinite per la tua applicazione, senza dover configurare le informazioni OAuth 2.0 nella configurazione dell'applicazione.

Questa opzione è 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 corretti.

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

gcloud auth application-default login

Questo comando aprirà un browser web per completare il flusso di autenticazione per il tuo Account Google. Una volta autorizzate, le credenziali vengono archiviate in una posizione standard. Dovrai quindi aggiornare l'applicazione per utilizzare ADC.

Ti consigliamo di utilizzare un file di configurazione. Copia il file google_ads_config.rb nella directory home, 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 passare le informazioni in modo programmatico in fase di runtime. Quando inizializzi il client nel codice Ruby, non fornire credenziali OAuth2 esplicite. La libreria rileverà e utilizzerà automaticamente le credenziali configurate dallo strumento a riga di comando gcloud.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # 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 oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

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