Krótkie wprowadzenie

Ten przewodnik pomoże Ci wykonać pierwsze wywołanie interfejsu Google Ads API.

Kluczowych pojęć

  • Token programisty: token programisty to ciąg alfanumeryczny o długości 22 znaków, który identyfikuje Twoją aplikację na serwerach interfejsu Google Ads API. Jest on wymagany do wykonywania wywołań interfejsu API.
  • Poziom dostępu do interfejsu API: poziom dostępu do interfejsu API Twojego tokena dewelopera określa liczbę wywołań interfejsu API, które możesz wykonać dziennie, oraz środowiska, w których możesz wywoływać interfejs API.
  • Konto menedżera Google Ads: konto menedżera Google Ads służy do zarządzania innymi kontami Google Ads. Konto menedżera Google Ads może służyć do zarządzania kontami klientów Google Ads lub innymi kontami menedżera Google Ads. Aby uzyskać token programisty, musisz mieć konto menedżera Google Ads.
  • Konto klienta Google Ads: konto Google Ads, na którym wykonujesz wywołania interfejsu API.
  • Identyfikator klienta klienta: 10-cyfrowy numer identyfikujący konto klienta Google Ads.
  • OAuth 2.0: OAuth 2.0 to standardowy protokół autoryzacji używany przez wszystkie interfejsy API Google. Aby generować dane logowania OAuth 2.0 do wywoływania interfejsów API, potrzebujesz konta usługi i klucza.
  • Projekt Google Cloud: projekt Google Cloud stanowi podstawę do tworzenia, włączania i używania wszystkich usług Google, w tym do zarządzania interfejsami API i danymi logowania do interfejsu OAuth 2.0 API. Możesz go utworzyć w konsoli Google Cloud.
  • Konto usługi:specjalny rodzaj konta Google, które należy do aplikacji, a nie do użytkownika. Służy on do uwierzytelniania aplikacji w interfejsie Google Ads API. Aby uzyskać konto usługi, musisz mieć projekt Google Cloud.
  • Klucz konta usługi: plik JSON z danymi logowania aplikacji, który zawiera klucz prywatny konta usługi. Służy do generowania danych logowania OAuth 2.0 na potrzeby uwierzytelniania konta usługi podczas wywoływania interfejsu Google Ads API API. Aby uzyskać klucz konta usługi, musisz mieć konto usługi.

Wymagania wstępne

Aby wykonać wywołanie interfejsu Google Ads API, wykonaj te czynności.

Uzyskiwanie tokena programisty

Jeśli masz już token programisty, możesz go znaleźć, otwierając Centrum interfejsów API po zalogowaniu się na konto menedżera Google Ads.

Centrum interfejsów API

Jeśli nie masz tokenu programisty, możesz go uzyskać w Centrum interfejsów API.

Jak zarejestrować się, aby otrzymać token programisty

  1. W przeglądarce otwórz API Center. W razie potrzeby zaloguj się na konto menedżera Google Ads. Utwórz konto menedżera Google Ads, jeśli jeszcze go nie masz.
  2. Wypełnij formularz dostępu do interfejsu API i zaakceptuj Warunki korzystania z usługi.
    • Upewnij się, że informacje są prawidłowe, a adres URL witryny Twojej firmy działa. Jeśli witryna nie jest aktywna, Google może nie być w stanie przetworzyć Twojego zgłoszenia i je odrzucić.
    • Upewnij się, że podany adres e-mail osoby kontaktowej ds. interfejsu API prowadzi do skrzynki odbiorczej, która jest regularnie sprawdzana. Podczas procesu sprawdzania zespół ds. zgodności interfejsu API Google może skontaktować się z Tobą na ten adres e-mail, aby uzyskać wyjaśnienia. Jeśli nie będziemy mogli się z Tobą skontaktować, możemy nie kontynuować rozpatrywania Twojego zgłoszenia.
    • Adres e-mail kontaktu w sprawie interfejsu API możesz edytować w Centrum interfejsów API. Aktualizuj te informacje nawet po zakończeniu procesu składania wniosku, aby Google mogło wysyłać Ci ważne powiadomienia o usługach.

Po zakończeniu procesu składania wniosku token programisty pojawi się w Centrum interfejsu API ze stanem Oczekuje na zatwierdzenie. Twój token dewelopera ma teraz poziom dostępu Dostęp do konta testowego.

Konfigurowanie projektu w Konsoli interfejsów API Google

Projekt w Konsoli interfejsów API Google służy do zarządzania interfejsami API Google i danymi logowania interfejsu OAuth 2.0 API. Istniejące projekty w Konsoli interfejsów API Google możesz znaleźć lub utworzyć nowy, otwierając Konsolę interfejsów API Google.

Otwórz konsolę interfejsów API Google

Zacznij od włączenia interfejsu Google Ads API w projekcie:

Włączanie interfejsu Google Ads API

Następnie musisz utworzyć konto usługi i klucz konta usługi, aby wywoływać interfejs API. Jeśli korzystasz już z innego interfejsu API Google i masz utworzone konto usługi OAuth 2.0 oraz klucz, możesz pominąć ten krok i ponownie użyć dotychczasowych danych logowania.

Jak utworzyć konto usługi i klucz

  1. W konsoli Google Cloud otwórz Menu > Administracja > Konta usługi.

    Otwórz stronę Konta usługi

  2. Wybierz konto usługi.
  3. Kliknij Klucze > Dodaj klucz > Utwórz nowy klucz.
  4. Wybierz JSON, a potem kliknij Utwórz.

    Nowa para kluczy publicznych/prywatnych zostanie wygenerowana i pobrana na Twoje urządzenie jako nowy plik. Zapisz pobrany plik JSON jako credentials.json w katalogu roboczym. Jest to jedyna kopia tego klucza.

  5. Kliknij Zamknij.

Zacznij od określenia konta Google Ads, na którym wykonujesz wywołania interfejsu API. Rodzaj konta, do którego możesz wywoływać interfejs API, zależy od poziomu dostępu do interfejsu API Twojego tokena programisty. Aby sprawdzić poziom dostępu do interfejsu API, otwórz Centrum interfejsów API.

Dostęp podstawowy i standardowy

Możesz wykonywać połączenia z produkcyjnym kontem Google Ads. W razie potrzeby możesz utworzyć testowe konto Google Ads, postępując zgodnie z instrukcjami na karcie Dostęp do konta testowego.

Dostęp do konta testowego

Tokenu programisty nie można używać do wywoływania interfejsu API na koncie produkcyjnym Google Ads. Wywołania interfejsu API możesz kierować tylko na testowe konta Google Ads.

Jak utworzyć testowe konto Google Ads

Poniższe instrukcje umożliwiają utworzenie testowego konta menedżera Google Ads i testowego konta reklamodawcy Google Ads.

  1. Kliknij niebieski przycisk, aby utworzyć testowe konto menedżera Google Ads. Jeśli pojawi się taka prośba, zaloguj się na konto Google, które nie jest połączone z Twoim produkcyjnym kontem menedżera Google Ads. Jeśli nie masz konta, kliknij przycisk Utwórz konto na tej stronie, aby utworzyć nowe konto Google.

    Tworzenie testowego konta menedżera Google Ads

  2. Na koncie menedżera testowego Google Ads utwórz testowe konto klienta Google Ads: kliknij Konta >  > Utwórz nowe konto i wypełnij formularz. Wszystkie konta Google Ads utworzone na koncie testowym Google Ads są automatycznie kontami testowymi Google Ads.
  3. Opcjonalnie utwórz kilka kampanii na koncie testowym klienta Google Ads na stronie Google Ads.

Aby wywołać interfejs API klienta Google Ads, musisz przyznać kontu usługi dostęp do konta klienta Google Ads i odpowiednie uprawnienia. Aby to zrobić, musisz mieć dostęp administracyjny do konta klienta.

Przyznawanie kontu usługi dostępu do konta Google Ads

  1. Zacznij od zalogowania się na konto Google Ads jako administrator.
  2. Kliknij Administracja > Dostęp i bezpieczeństwo.
  3. Na karcie Użytkownicy kliknij przycisk .
  4. Wpisz adres e-mail konta usługi w polu E-mail. Wybierz odpowiedni poziom dostępu do konta i kliknij przycisk Dodaj konto. Pamiętaj, że poziom dostępu do poczty e-mail nie jest obsługiwany w przypadku kont usługi.
  5. Konto usługi otrzymuje dostęp.
  6. [Opcjonalnie] Domyślnie nie możesz przyznać dostępu administratora do konta usługi. Jeśli wywołania interfejsu API wymagają dostępu administratora, możesz go uzyskać w ten sposób:
    1. W kolumnie Poziom dostępu kliknij strzałkę w dół obok poziomu dostępu konta usługi.
    2. Z menu wybierz Administracja.

Pobieranie narzędzi i bibliotek klienta

Możesz pobrać bibliotekę klienta lub klienta HTTP w zależności od tego, jak chcesz wywoływać interfejs API.

Korzystanie z biblioteki klienta

Pobierz i zainstaluj wybraną bibliotekę klienta.

Używanie klienta HTTP (REST)

curl

Pobierz i zainstaluj curl, narzędzie wiersza poleceń do przesyłania danych za pomocą adresu URL.

Google Cloud CLI

Aby zainstalować interfejs wiersza poleceń gcloud, postępuj zgodnie z instrukcjami.

Instrukcje w pozostałej części tego przewodnika zostały sprawdzone pod kątem działania z tą wersją narzędzia gcloud i mogą nie działać w przypadku starszych wersji ze względu na różnice w działaniu aplikacji lub opcjach wiersza poleceń.

:~$ 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

Wywoływanie interfejsu API

Aby dowiedzieć się, jak wykonać wywołanie interfejsu API, wybierz klienta:

Java

Artefakty biblioteki klienta są publikowane w centralnym repozytorium Maven. Dodaj bibliotekę klienta jako zależność do projektu w ten sposób:

Zależność Maven to:

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

Zależność Gradle to:

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

Utwórz obiekt GoogleAdsClient w ten sposób:

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);
}

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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#

Pakiety biblioteki klienta są publikowane w repozytorium Nuget.org. Zacznij od dodania odwołania do pakietu NuGet do pakietu Google.Ads.GoogleAds.

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

Utwórz obiekt GoogleAdsConfig z odpowiednimi ustawieniami i użyj go do utworzenia obiektu GoogleAdsClient.

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

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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

Pakiety biblioteki klienta są publikowane w repozytorium Packagist. Przejdź do katalogu głównego projektu i uruchom to polecenie, aby zainstalować bibliotekę i wszystkie jej zależności w katalogu vendor/ w katalogu głównym projektu.

composer require googleads/google-ads-php:31.0.0

Utwórz kopię pliku google_ads_php.ini z repozytorium GitHub i zmodyfikuj go, aby uwzględnić swoje dane logowania.

[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"

Utwórz instancję obiektu 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();

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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

Biblioteka klienta jest rozpowszechniana w PyPI i można ją zainstalować za pomocą polecenia pip:

python -m pip install google-ads==21.3.0

Utwórz kopię pliku google-ads.yaml z repozytorium GitHub i zmodyfikuj ją, aby uwzględnić swoje dane logowania.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Utwórz instancję GoogleAdsClient, wywołując metodę GoogleAdsClient.load_from_storage. Podczas wywoływania metody przekaż ścieżkę do google-ads.yaml jako ciąg znaków:

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

Dodaj do rejestratora biblioteki moduł obsługi, który określa, gdzie mają być drukowane logi. Poniższy kod spowoduje, że rejestrator biblioteki będzie zapisywać dane w konsoli (stdout).

import logging
import sys

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

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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

Gemy Ruby dla biblioteki klienta są publikowane w witrynie hostingowej gemów Rubygems. Zalecany sposób instalacji to użycie narzędzia bundler. Dodaj wiersz do pliku Gemfile:

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

Następnie uruchom polecenie:

bundle install

Utwórz kopię pliku google_ads_config.rb z repozytorium GitHub i zmodyfikuj go, aby uwzględnić swoje dane logowania.

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

Utwórz instancję GoogleAdsClient, przekazując ścieżkę do miejsca, w którym przechowujesz ten plik.

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

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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

Biblioteka jest dystrybuowana w ramach CPAN. Zacznij od sklonowania repozytorium google-ads-perl w wybranym katalogu.

git clone https://github.com/googleads/google-ads-perl.git

Przejdź do katalogu google-ads-perl i uruchom w wierszu poleceń to polecenie, aby zainstalować wszystkie zależności potrzebne do korzystania z biblioteki.

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

Utwórz kopię pliku googleads.properties z repozytorium GitHub i zmodyfikuj go, aby uwzględnić swoje dane logowania.

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Utwórz instancję Client, przekazując ścieżkę do miejsca przechowywania tego pliku.

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

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

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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

Zacznij od ustawienia konta usługi jako aktywnych danych logowania w interfejsie wiersza poleceń gcloud.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

Następnie pobierz token dostępu OAuth 2.0 dla interfejsu Google Ads API.

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

Następnie uruchom raport kampanii, korzystając z metody GoogleAdsService.SearchStream, aby pobrać kampanie na koncie. Ten przewodnik nie zawiera szczegółowych informacji o raportowaniu.

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"

Zawartość pliku query.json jest następująca:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Wstecz
Wprowadzenie
Dalej
Typowe błędy