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

Guida rapida

Questa guida rapida ti aiuta a effettuare la tua prima chiamata API all'API Google Ads.

Concetti fondamentali

Progetto Google Cloud: un progetto Google Cloud costituisce la base per creare, abilitare e utilizzare tutti i servizi Google, tra cui la gestione delle API e delle credenziali API OAuth 2.0. Puoi crearne uno dalla console Google Cloud.
Livello di accesso all'API: il livello di accesso all'API del tuo progetto Google Cloud controlla il numero di chiamate API che puoi effettuare al giorno e gli ambienti in cui puoi effettuare chiamate API. Il livello di accesso all'API del tuo progetto è elencato nella pagina Panoramica dell'API Google Ads del progetto.
Account amministratore Google Ads: un account amministratore Google Ads viene utilizzato per gestire altri account Google Ads, che potrebbero essere una raccolta di account cliente Google Ads o altri account amministratore Google Ads.
Account cliente Google Ads: l'account Google Ads utilizzato per pubblicare gli annunci che vuoi scegliere come target con le chiamate API.
ID cliente: il numero di 10 cifre che identifica un account cliente Google Ads. Se hai copiato questo ID dall'interfaccia utente di Google Ads, assicurati di rimuovere i trattini.
OAuth 2.0: OAuth 2.0 è un protocollo standard di settore per l'autorizzazione, utilizzato da tutte le API di Google. Per generare le credenziali OAuth 2.0 per effettuare chiamate API, devi disporre di un service account e di una chiave.
Service account: un tipo speciale di Account Google che appartiene alla tua applicazione anziché a un singolo utente. Viene utilizzato per autenticare la tua applicazione nell'API Google Ads. Per ottenere un service account, devi avere un progetto Google Cloud.
Chiave del service account: un file JSON di credenziali dell'app che contiene la chiave privata del tuo service account. Viene utilizzato per generare credenziali OAuth 2.0 per autenticare un service account quando viene effettuata una chiamata API Google Ads. Per ottenere una chiave del service account, devi disporre di un service account.

Prerequisiti

Per effettuare una chiamata API Google Ads, devi completare i seguenti passaggi.

Configura il progetto Cloud per l'accesso all'API Google Ads

Il progetto Google Cloud viene utilizzato per gestire le API di Google e le credenziali API OAuth 2.0. Puoi trovare i tuoi progetti Google Cloud esistenti o crearne uno visitando la console Google Cloud.

Inizia abilitando l'API Google Ads nel tuo progetto:

Abilita l'API Google Ads

Poi, visita la pagina Panoramica dell'API Google Ads. La pagina mostra il tuo livello di accesso all'API attuale. Se il tuo livello di accesso all'API attuale è Test, espandi la sezione Fai l'upgrade del livello di accesso. Segui le istruzioni per richiedere il livello di accesso Explorer.

Una volta completata la richiesta, Google la esaminerà automaticamente e, nella maggior parte dei casi, eseguirà l'upgrade a Explorer. Se non ti è stato concesso l'accesso Explorer, non preoccuparti: questa guida fornirà le istruzioni appropriate per la configurazione del tuo account cliente Google Ads.

Crea un account di servizio

Per effettuare chiamate API, devi disporre di un service account e di una chiave del service account. Se utilizzi già un'altra API di Google e hai creato un service account e una chiave OAuth 2.0, puoi saltare questo passaggio e riutilizzare le credenziali esistenti.

Come creare un service account e una chiave

Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.
Vai a Service account
Seleziona il tuo service account.
Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
Seleziona JSON, quindi fai clic su Crea.
Viene generata e scaricata sul tuo computer una nuova coppia di chiavi pubblica/privata sotto forma di nuovo file. Salva il file JSON scaricato come credentials.json nella directory di lavoro. Questo file è l'unica copia di questa chiave. Non eseguire il commit di credentials.json nel controllo della versione (ad esempio, aggiungilo al file .gitignore).
Fai clic su Chiudi.

Configura l'account cliente Google Ads

Inizia identificando l'account Google Ads per cui stai effettuando le chiamate API. Il tipo di account per cui puoi effettuare chiamate API dipende dal livello di accesso all'API del tuo progetto Google Cloud. Controlla la pagina Panoramica dell'API Google Ads per scoprire il tuo livello di accesso all'API.

Livelli di accesso Explorer, Basic e Standard

Puoi effettuare chiamate al tuo account di produzione Google Ads. Tuttavia, se necessario, puoi creare un account di prova Google Ads seguendo le istruzioni nella scheda Accesso di prova.

Controlla l'accesso

Il tuo progetto Google Cloud non può essere utilizzato per effettuare chiamate API a un account di produzione Google Ads. Puoi effettuare chiamate API solo per gli account di prova Google Ads.

Come creare un account di prova Google Ads

Le seguenti istruzioni creano un account amministratore di test Google Ads e un account inserzionista di test Google Ads al suo interno.

Fai clic sul pulsante blu per creare un account amministratore di prova Google Ads. Se richiesto, accedi con un Account Google non collegato al tuo account amministratore di produzione Google Ads. Se non ne hai uno, utilizza il pulsante Crea account in quella pagina per creare un nuovo Account Google.

Crea un account amministratore di test Google Ads
Nell'account amministratore di prova Google Ads, crea un account cliente di prova Google Ads: fai clic su Account > > Crea nuovo account e compila il modulo. Tutti gli account Google Ads che crei dal tuo account amministratore di test Google Ads sono automaticamente account di test Google Ads.
Facoltativamente, crea alcune campagne nell'account cliente di test Google Ads dalla pagina Google Ads.

Per effettuare una chiamata API a un cliente Google Ads, devi concedere l'accesso e le autorizzazioni appropriate al tuo service account per l'account cliente Google Ads. Per farlo, devi disporre dell'accesso amministrativo all'account cliente.

Come concedere al service account l'accesso al tuo account Google Ads

Per iniziare, accedi al tuo account Google Ads come amministratore.
Vai ad Amministratore > Accesso e sicurezza.
Fai clic sul pulsante nella scheda Utenti.
Digita l'indirizzo email del service account nella casella di immissione Email. Seleziona il livello di accesso all'account appropriato e fai clic sul pulsante Aggiungi account. Tieni presente che il livello di accesso Email non è supportato per i service account.
Al service account viene concesso l'accesso.
[Facoltativo] Non puoi concedere l'accesso amministrativo a un service account durante la configurazione iniziale. Se le tue chiamate API richiedono l'accesso amministratore, puoi eseguire l'upgrade dell'accesso come segue.
1. Fai clic sulla freccia menu a discesa accanto al livello di accesso del service account nella colonna Livello di accesso.
2. Seleziona Amministratore dall'elenco a discesa.

Scarica strumenti e librerie client

Puoi scegliere di scaricare una libreria client o un client HTTP a seconda di come vuoi effettuare le chiamate API.

Utilizza una libreria client

Scarica e installa una libreria client di tua scelta.

Utilizza il client HTTP (REST)

curl

Scarica e installa curl, lo strumento a riga di comando per il trasferimento di dati tramite un URL.

Interfaccia a riga di comando Google Cloud

Segui la guida all'installazione di Google Cloud CLI per installare gcloud CLI.

Le istruzioni per il resto di questa guida sono state verificate per funzionare con la seguente versione dello strumento gcloud e potrebbero non funzionare con le versioni precedenti a causa di differenze nel comportamento dell'applicazione o nelle opzioni della riga di comando.

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

Esegui una chiamata API

Seleziona il client che preferisci per istruzioni su come effettuare una chiamata API:

Java

Gli artefatti della libreria client vengono pubblicati nel repository Maven Central.

Per gestire le versioni delle dipendenze ed evitare conflitti, consulta la guida alla distinta base (BOM) dell'API Google Ads.

Se non utilizzi la distinta base, aggiungi la libreria client direttamente al tuo progetto utilizzando uno dei seguenti strumenti di build:

Maven: aggiungi la seguente dipendenza al file pom.xml:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>48.1.0</version>
</dependency>

Gradle: aggiungi la seguente dipendenza al file build.gradle:

implementation 'com.google.api-ads:google-ads:48.1.0'

Crea un file ads.properties nella tua home directory (~/ads.properties su Linux e macOS o %USERPROFILE%\ads.properties su Windows) con i seguenti contenuti:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Prima di eseguire le richieste API, crea un'istanza GoogleAdsClient. Per impostazione predefinita, fromPropertiesFile() carica le credenziali dal file ads.properties che si trova nella tua home directory:

GoogleAdsClient googleAdsClient;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
  System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
  throw new RuntimeException("Initialization failed", e);
}

Poi, genera un report sulle campagne utilizzando GoogleAdsService.SearchStream per trasmettere in streaming in modo efficiente set di risultati di grandi dimensioni e recuperare le campagne nel tuo account:

    private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}GetCampaigns.java

C#

I pacchetti della libreria client vengono pubblicati nel repository NuGet.org. Inizia aggiungendo un riferimento al pacchetto NuGet al pacchetto Google.Ads.GoogleAds:

dotnet add package Google.Ads.GoogleAds --version 27.6.0

Per effettuare chiamate API, crea un oggetto GoogleAdsConfig dalle impostazioni di configurazione (ad esempio appsettings.json, variabili di ambiente o impostazioni personalizzate) e passalo per inizializzare un'istanza GoogleAdsClient:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Poi, genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non illustra i dettagli dei report.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}GetCampaigns.cs

PHP

I pacchetti della libreria client vengono pubblicati nel repository Packagist. Assicurati di avere una versione PHP compatibile e Composer installato, quindi passa alla directory root del progetto ed esegui questo comando per installare la libreria e le relative dipendenze nella directory vendor/ del progetto:

composer require googleads/google-ads-php:35.3.0

Crea una copia del file google_ads_php.ini dal repository GitHub, salvala nella home directory o nella directory root del progetto e modificala in modo da includere le tue credenziali:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Crea un'istanza GoogleAdsClient utilizzando il file di configurazione google_ads_php.ini:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V26\GoogleAdsClientBuilder;

$oauth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oauth2Credential)
    ->build();

Poi, genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account:

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}GetCampaigns.php

Python

La libreria client dell'API Google Ads per Python è distribuita su PyPI. Assicurati di aver installato una versione di Python supportata, quindi installa la libreria utilizzando pip:

python -m pip install google-ads==35.0.0

Per autenticare le chiamate API, configura un file google-ads.yaml:

Scarica una copia del file di esempio google-ads.yaml dal repository GitHub.
Salva il file nella directory home (~/google-ads.yaml) o in un percorso personalizzato.
Apri google-ads.yaml e aggiornalo in modo da includere le tue credenziali:
```
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH
```
Configura il logging prima di inizializzare il client in modo che la libreria acquisisca eventuali avvisi di inizializzazione o configurazione. L'esempio seguente configura il logger della libreria in modo che restituisca i log INFO nell'output standard (stdout):

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))

Crea un'istanza GoogleAdsClient chiamando il metodo GoogleAdsClient.load_from_storage e passando il percorso al file google-ads.yaml:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Se ometti l'argomento del percorso, per impostazione predefinita load_from_storage() cerca il file di configurazione nella tua home directory (~/google-ads.yaml).

Poi, genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account:

    def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )get_campaigns.py

Ruby

Le gemme Ruby per la libreria client sono pubblicate su RubyGems. Assicurati di aver installato una versione di Ruby supportata e utilizza Bundler per installare la libreria:

Aggiungi la gemma al file Gemfile della tua applicazione:
```
gem 'google-ads-googleads', '~> 46.1.0'
```
Installa il gem eseguendo:
```
bundle install
```

Per configurare le credenziali:

Copia il file google_ads_config.rb di esempio dal repository GitHub.
Salva il file nella directory root del progetto o nella directory home (~).
Apri google_ads_config.rb e sostituisci i valori segnaposto con le tue credenziali dell'API Google Ads:
```
Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end
```
Crea un'istanza GoogleAdsClient passando il percorso del file di configurazione (google_ads_config.rb):

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

Poi, genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account:

    def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
endget_campaigns.rb

Perl

La libreria client Perl è distribuita su CPAN e richiede Perl 5.28 o versioni successive e il gestore di pacchetti cpan o cpanm.

Clona il repository google-ads-perl nella directory che preferisci:
```
git clone https://github.com/googleads/google-ads-perl.git
```
Passa alla directory google-ads-perl ed esegui i seguenti comandi per installare le dipendenze richieste e creare la libreria:
```
cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps
perl Build
perl Build install
```

Per configurare le credenziali:

Copia il file di configurazione di esempio googleads.properties dal repository GitHub nella tua home directory (~/googleads.properties):
```
cp googleads.properties ~/googleads.properties
```
Modifica ~/googleads.properties per includere le tue credenziali:
```
jsonKeyFilePath=JSON_KEY_FILE_PATH
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
```
Crea un'istanza Client passando il percorso al file googleads.properties configurato (ad esempio ~/googleads.properties):

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => "/path/to/googleads.properties"
});

Poi, genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account:

    sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}get_campaigns.pl

Quando viene eseguito, lo script trasmette in streaming le righe corrispondenti e stampa l'ID e il nome di ogni campagna nel tuo account.

curl

Inizia impostando il service account come credenziali attive in gcloud CLI.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

Successivamente, recupera un token di accesso OAuth 2.0 per l'API Google Ads.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

Crea un file denominato query.json contenente la richiesta Google Ads Query Language (GAQL):

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

Genera un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account:

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

Se riscontri errori durante la prima chiamata, consulta Gestisci gli errori dell'API per indicazioni sulla risoluzione dei problemi.

Guida rapida Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Concetti fondamentali

Prerequisiti

Configura il progetto Cloud per l'accesso all'API Google Ads

Crea un account di servizio

Come creare un service account e una chiave

Configura l'account cliente Google Ads

Livelli di accesso Explorer, Basic e Standard

Controlla l'accesso

Come creare un account di prova Google Ads

Come concedere al service account l'accesso al tuo account Google Ads

Scarica strumenti e librerie client

Utilizza una libreria client

Utilizza il client HTTP (REST)

Esegui una chiamata API

Java

C#

PHP

Python

Ruby

Perl

curl

Guida rapida