Guida rapida

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

Concetti fondamentali

  • Token sviluppatore: un token sviluppatore è una stringa alfanumerica di 22 caratteri che identifica la tua app sui server dell'API Google Ads. È necessario per effettuare chiamate API.
  • Livello di accesso API: il livello di accesso API del tuo token sviluppatore controlla il numero di chiamate API che puoi effettuare al giorno e gli ambienti a cui puoi effettuare chiamate API.
  • Account amministratore Google Ads:un account amministratore Google Ads viene utilizzato per gestire altri account Google Ads. Un account amministratore Google Ads può essere utilizzato per gestire account cliente Google Ads o altri account amministratore Google Ads. Per ottenere un token sviluppatore, devi disporre di un account amministratore Google Ads.
  • Account cliente Google Ads:l'account Google Ads su cui stai effettuando chiamate API.
  • ID cliente cliente:il numero a 10 cifre che identifica un account cliente Google Ads.
  • OAuth 2.0: OAuth 2.0 è un protocollo standard di settore per l'autorizzazione, utilizzato da tutte le API di Google. Per generare credenziali OAuth 2.0 per effettuare chiamate API, devi disporre di un service account e di una chiave.
  • Progetto Google Cloud:un progetto Google Cloud è la base per creare, abilitare e utilizzare tutti i servizi Google, inclusa la gestione delle API e delle credenziali API OAuth 2.0. Puoi crearne uno dalla console Google Cloud.
  • 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 account di servizio, devi disporre di un progetto Google Cloud.
  • Chiave dell'account di servizio:un file delle credenziali dell'app JSON 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 all'API Google Ads. Per ottenere una chiave del service account, devi avere un service account.

Prerequisiti

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

Ottenere il token sviluppatore

Se hai richiesto un token sviluppatore in passato, puoi trovarlo visitando il Centro API dopo aver eseguito l'accesso al tuo account amministratore Google Ads.

Accedere al Centro API

Se non hai un token sviluppatore, puoi registrarti per ottenerne uno nel Centro API.

Come registrarsi per un token sviluppatore

  1. Vai al Centro API nel browser web. Se richiesto, accedi al tuo account amministratore Google Ads. Crea un account amministratore Google Ads se non ne hai uno.
  2. Compila il modulo di accesso all'API e accetta i Termini e condizioni.
    • Assicurati che le informazioni siano corrette e che l'URL del sito web della tua azienda funzioni. Se il sito web non è attivo, Google potrebbe non essere in grado di elaborare la tua richiesta e respingerla.
    • Assicurati che l'email di contatto API che fornisci porti a una casella di posta in arrivo monitorata regolarmente. Il team di conformità delle API di Google potrebbe contattare questo indirizzo email durante la procedura di revisione per chiarimenti. Se non riesci a rispondere, Google potrebbe non continuare con la tua richiesta.
    • Puoi modificare l'email di contatto API in API Center. Mantieni aggiornate queste informazioni, anche dopo la procedura di richiesta, in modo che Google possa inviarti importanti annunci di servizio.

Una volta completata la procedura di richiesta, il token sviluppatore viene visualizzato nel Centro API con lo stato In attesa di approvazione. Il tuo token sviluppatore ora ha il livello di accesso Test Account Access.

Configurare il progetto della console API di Google

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

Apri la console Google API

Inizia attivando l'API Google Ads nel tuo progetto:

Abilitare l'API Google Ads

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

Come creare un service account e una chiave

  1. Nella console Google Cloud, vai a Menu > IAM e amministrazione > Service account.

    Vai a Service account

  2. Seleziona il tuo service account.
  3. Fai clic su Chiavi > Aggiungi chiave > Crea nuova chiave.
  4. Seleziona JSON, quindi fai clic su Crea.

    Una nuova coppia di chiavi pubblica/privata viene generata e scaricata sul tuo computer come nuovo file. Salva il file JSON scaricato come credentials.json nella directory di lavoro. Questo file è l'unica copia di questa chiave.

  5. Fai clic su Chiudi.

Inizia identificando l'account Google Ads su cui stai effettuando chiamate API. Il tipo di account a cui puoi effettuare chiamate API dipende dal livello di accesso API del tuo token sviluppatore. Controlla il Centro API per scoprire il tuo livello di accesso API.

Accesso di base e standard

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

Accesso all'account di prova

Il token sviluppatore non può essere utilizzato per effettuare chiamate API a un account di produzione Google Ads. Puoi effettuare chiamate API solo su account di test Google Ads.

Come creare un account di test Google Ads

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

  1. Fai clic sul pulsante blu per creare un account amministratore test 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.

    Creare un account amministratore test Google Ads

  2. Nell'account amministratore Google Ads Test Manager, crea un account cliente di test Google Ads: fai clic su Account > > Crea nuovo account e compila il modulo. Tutti gli account Google Ads che crei dall'account amministratore di test Google Ads sono automaticamente account di test Google Ads.
  3. Se vuoi, 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 all'account di servizio l'accesso al tuo account Google Ads

  1. Per iniziare, accedi al tuo account Google Ads come amministratore.
  2. Vai ad Amministrazione > Accesso e sicurezza.
  3. Fai clic sul pulsante nella scheda Utenti.
  4. Digita l'indirizzo email del service account nella casella di input 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.
  5. All'account di servizio viene concesso l'accesso.
  6. [Facoltativo] Per impostazione predefinita, non puoi concedere l'accesso amministratore a un service account. 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 dell'account di servizio 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.

Utilizzare una libreria client

Scarica e installa una libreria client a tua scelta.

Utilizzare il client HTTP (REST)

curl

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

Google Cloud CLI

Segui le istruzioni per installare gcloud CLI.

È stato verificato che le istruzioni per il resto di questa guida funzionano 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 centrale Maven. Aggiungi la libreria client come dipendenza al tuo progetto nel seguente modo:

La dipendenza Maven è:

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

La dipendenza Gradle è:

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

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

Crea un oggetto GoogleAdsClient nel seguente modo:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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 nuget al pacchetto Google.Ads.GoogleAds.

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

Crea un oggetto GoogleAdsConfig con le impostazioni pertinenti e utilizzalo per creare un oggetto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};
GoogleAdsClient client = new GoogleAdsClient(config);

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V21.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. Passa alla directory principale del progetto ed esegui il comando seguente per installare la libreria e tutte le relative dipendenze nella directory vendor/ della directory principale del progetto.

composer require googleads/google-ads-php:31.0.0

Crea una copia del file google_ads_php.ini dal repository GitHub e modificalo in modo da includere le tue credenziali.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

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

Crea un'istanza dell'oggetto GoogleAdsClient.

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

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

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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 è distribuita su PyPI e può essere installata utilizzando il comando pip come segue:

python -m pip install google-ads==21.3.0

Crea una copia del file google-ads.yaml dal repository GitHub e modificalo in modo da includere le tue credenziali.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Crea un'istanza GoogleAdsClient chiamando il metodo GoogleAdsClient.load_from_storage. Passa il percorso al tuo google-ads.yaml come stringa al metodo quando lo chiami:

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

Aggiungi un gestore al logger della libreria per indicare dove stampare i log. Il seguente codice indica al logger della libreria di stampare sulla console (stdout).

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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 gem di Ruby per la libreria client vengono pubblicate sul sito di hosting di gem Rubygems. Il metodo consigliato per l'installazione è l'utilizzo di Bundler. Aggiungi una riga al Gemfile:

gem 'google-ads-googleads', '~> 35.2.0'

Dopodiché, esegui:

bundle install

Crea una copia del file google_ads_config.rb dal repository GitHub e modificalo in modo da includere le tue credenziali.

Google::Ads::GoogleAds::Config.new do |c|
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end

Crea un'istanza GoogleAdsClient passando il percorso in cui conservi questo file.

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

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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
end
get_campaigns.rb

Perl

La libreria viene distribuita su CPAN. Inizia clonando 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 il seguente comando al prompt dei comandi per installare tutte le dipendenze necessarie per utilizzare la libreria.

cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps

Crea una copia del file googleads.properties dal repository GitHub e modificalo in modo da includere le tue credenziali.

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Crea un'istanza Client passando il percorso in cui conservi questo file.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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

curl

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

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

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'

Successivamente, esegui un report sulle campagne utilizzando il metodo GoogleAdsService.SearchStream per recuperare le campagne nel tuo account. Questa guida non copre i dettagli della segnalazione.

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

I contenuti di query.json sono i seguenti:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Indietro
Presentazione
Avanti
Errori comuni