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 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. Per configurare questa impostazione, crea e scarica il file della chiave JSON nella console Google Cloud, poi copia google_ads_config.rb nella tua home directory e modificalo per specificare la posizione del file della chiave del service account e l'indirizzo email dell'utente da simulare:

  # 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 variabili di ambiente, puoi impostare GOOGLE_ADS_JSON_KEY_FILE_PATH e GOOGLE_ADS_IMPERSONATED_EMAIL rispettivamente.

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 trasmettere le informazioni in modo programmatico in fase di runtime utilizzando la 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|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

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 a riga di comando come gcloud 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 directory home e modificandolo in modo da includere il token sviluppatore, l'ID client, il client secret e il token di aggiornamento:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 home directory se viene istanziato 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 conservi:

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

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

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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 trasmettere le informazioni in modo programmatico in fase di esecuzione:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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 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. Questo flusso di lavoro può essere configurato in modo simile al flusso per un singolo utente, ma con login_customer_id specificato.

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

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 home directory se viene istanziato 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 conservi:

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

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

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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 trasmettere le informazioni in modo programmatico in fase di esecuzione:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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 per l'autenticazione multiutente. La libreria client Ruby include un esempio di codice come riferimento. GenerateUserCredentials è un esempio di codice della riga di comando che 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 dell'utente.

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 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 in 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 poi 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 (ADC). Consente di impostare le credenziali predefinite per l'applicazione senza dover configurare le informazioni OAuth 2.0 nella configurazione dell'applicazione.

Ciò è particolarmente utile per lo sviluppo locale o per lo sviluppo con API di Google diverse, 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 e di eseguire l'autenticazione per le credenziali predefinite dell'applicazione:

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, memorizza le credenziali in una posizione standard. Dopodiché, devi aggiornare l'applicazione per utilizzare ADC.

Ti consigliamo di utilizzare un file di configurazione. Copia il file google_ads_config.rb nella directory home, poi aggiungi il token sviluppatore e imposta use_application_default_credentials su true:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 variabili di ambiente, puoi impostare GOOGLE_ADS_DEVELOPER_TOKEN e GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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, non fornire credenziali OAuth2 esplicite. La libreria rileverà e utilizzerà automaticamente le credenziali impostate dallo strumento a riga di comando Google Cloud. Dovrai comunque specificare il tuo token sviluppatore.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # 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 relativa alla configurazione.