Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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, comprendi come funziona il modello di accesso Google Ads. Consulta la guida al modello di accesso a 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 workflow consigliato se 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. Per configurare questa opzione, 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 rappresentare 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 memorizzare queste informazioni in un file e utilizzare variabili di ambiente, puoi impostare GOOGLE_ADS_JSON_KEY_FILE_PATH (e GOOGLE_ADS_IMPERSONATED_EMAIL facoltativo):

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'email con rappresentazione facoltativa) 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 il gem 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 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:

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.
L'utente esegue uno strumento a riga di comando come lo strumento a riga di comando Google Cloud o l'GenerateUserCredentials esempio di codice 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 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 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 trasmettere 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 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, con la specifica di login_customer_id.

È consigliabile utilizzare un file di configurazione. Copia il file google_ads_config.rb nella tua home directory e modificalo in modo che includa 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 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 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 trasmettere 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 per l'autenticazione multiutente. La libreria client Ruby include un esempio di codice come riferimento. L'esempio di codice GenerateUserCredentials della riga di comando mostra 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

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

L'esempio di codice GetAccountHierarchy mostra come recuperare l'elenco di tutti gli account in un account amministratore Google Ads.
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 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). Consente di impostare le credenziali predefinite per l'applicazione senza dover configurare le informazioni OAuth 2.0 all'interno della 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 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, memorizza le credenziali in una posizione standard. Dopodiché, devi 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 memorizzare queste informazioni in un file e utilizzare 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 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 Configurazione.