Быстрый старт

Это краткое руководство поможет вам совершить первый вызов API к API Google Ads.

Ключевые концепции

  • Токен разработчика : токен разработчика — это буквенно-цифровая строка длиной 22 символа, которая идентифицирует ваше приложение на серверах API Google Ads. Он необходим для выполнения вызовов API.
  • Уровень доступа к API: Уровень доступа к API вашего токена разработчика контролирует количество вызовов API, которые вы можете совершать в день, а также среды, к которым вы можете совершать вызовы API.
  • Управляющий аккаунт Google Ads: управляющий аккаунт Google Ads используется для управления другими аккаунтами Google Ads. Управляющий аккаунт Google Ads может использоваться для управления клиентскими аккаунтами Google Ads или другими управляющими аккаунтами Google Ads. Для получения токена разработчика вам потребуется управляющий аккаунт Google Ads.
  • Клиентский аккаунт Google Ads: аккаунт Google Ads, к которому вы совершаете вызовы API.
  • Идентификатор клиента: 10-значный номер, идентифицирующий клиентскую учетную запись Google Ads.
  • OAuth 2.0: OAuth 2.0 — это отраслевой стандартный протокол авторизации, используемый всеми API Google. Для генерации учётных данных OAuth 2.0 и выполнения вызовов API вам потребуется сервисная учётная запись и ключ.
  • Проект Google Cloud: проект Google Cloud служит основой для создания, включения и использования всех сервисов Google, включая управление API и учётные данные API OAuth 2.0. Вы можете создать проект в консоли Google Cloud .
  • Сервисный аккаунт: особый тип аккаунта Google, принадлежащий вашему приложению, а не отдельному пользователю. Он используется для аутентификации вашего приложения в API Google Ads. Для получения сервисного аккаунта вам потребуется проект Google Cloud.
  • Ключ учётной записи сервиса: JSON-файл учётных данных приложения, содержащий закрытый ключ вашей учётной записи сервиса. Он используется для генерации учётных данных OAuth 2.0 для аутентификации учётной записи сервиса при выполнении вызова API Google Ads. Для получения ключа учётной записи сервиса вам потребуется учётная запись сервиса.

Предпосылки

Чтобы сделать вызов API Google Ads, необходимо выполнить следующие шаги.

Получите свой токен разработчика

Если вы ранее регистрировались для получения токена разработчика, вы можете найти его, посетив API-центр , войдя в свою учетную запись менеджера Google Ads.

Центр API доступа

Если у вас нет токена разработчика, вы можете зарегистрироваться для его получения в API Center.

Как зарегистрироваться для получения токена разработчика

  1. Откройте API Center в веб-браузере. При необходимости войдите в свой управляющий аккаунт Google Ads. Если у вас его ещё нет , создайте управляющий аккаунт Google Ads .
  2. Заполните форму доступа к API и примите Условия использования .
    • Убедитесь, что ваша информация верна, а URL-адрес веб-сайта вашей компании работает. Если веб-сайт неактивен, Google может не обработать вашу заявку и отклонить её.
    • Убедитесь, что указанный вами контактный адрес электронной почты API ведет на регулярно просматриваемый почтовый ящик. Команда Google по обеспечению соответствия требованиям API может обратиться на этот адрес электронной почты в процессе рассмотрения заявки для получения разъяснений. Если с вами не получится связаться, Google может отказать в обработке вашей заявки.
    • Вы можете изменить свой контактный адрес электронной почты для API в Центре API . Поддерживайте эту информацию актуальной даже после подачи заявки, чтобы Google мог отправлять вам важные уведомления об услугах.

После завершения процесса подачи заявки токен разработчика появится в вашем API Center со статусом «Ожидает одобрения» . Теперь вашему токену разработчика присвоен уровень доступа «Тестовый аккаунт» .

Настройте свой проект Google API Console

Проект Google API Console используется для управления API Google и учётными данными API OAuth 2.0. Вы можете найти существующие проекты Google API Console или создать новый, посетив Google API Console .

Открыть консоль Google API

Начните с включения API Google Ads в вашем проекте:

Включить API Google Рекламы

Далее вам понадобятся учётная запись сервиса и ключ учётной записи сервиса для выполнения вызовов API. Если вы уже используете другой API Google и создали учётную запись сервиса OAuth 2.0 и ключ, вы можете пропустить этот шаг и использовать существующие учётные данные.

Как создать учетную запись службы и ключ

  1. В консоли Google Cloud перейдите в > IAM и администрирование > Учетные записи служб .

    Перейти к учетным записям служб

  2. Выберите свою учетную запись службы.
  3. Нажмите Ключи > Добавить ключ > Создать новый ключ .
  4. Выберите JSON , затем нажмите Создать .

    Ваша новая пара открытого и закрытого ключей будет сгенерирована и загружена на ваш компьютер в виде нового файла. Сохраните загруженный JSON-файл как credentials.json в вашем рабочем каталоге. Этот файл — единственная копия данного ключа.

  5. Нажмите «Закрыть» .

Для начала определите аккаунт Google Рекламы, к которому вы обращаетесь через API. Тип аккаунта, к которому вы можете обращаться через API, зависит от уровня доступа к API вашего токена разработчика. Проверьте свой уровень доступа к API в Центре API .

Базовый и стандартный доступ

Вы можете совершать звонки на свой рабочий аккаунт Google Ads. Однако при необходимости вы можете создать тестовый аккаунт Google Ads, следуя инструкциям на вкладке «Доступ к тестовому аккаунту» .

Доступ к тестовой учетной записи

Ваш токен разработчика нельзя использовать для выполнения API-вызовов к рабочему аккаунту Google Ads. Вы можете выполнять API-вызовы только к тестовым аккаунтам Google Ads.

Как создать тестовый аккаунт Google Ads

Следующие инструкции позволят создать тестовую учетную запись менеджера Google Ads и тестовую учетную запись рекламодателя Google Ads.

  1. Нажмите синюю кнопку, чтобы создать тестовый управляющий аккаунт Google Рекламы. При появлении запроса войдите в систему, используя аккаунт Google, не связанный с вашим управляющим аккаунтом Google Рекламы. Если у вас его нет, нажмите кнопку «Создать аккаунт» на этой странице, чтобы создать новый аккаунт Google.

    Создайте тестовый аккаунт менеджера Google Ads

  2. В тестовом аккаунте менеджера Google Ads создайте тестовый аккаунт клиента Google Ads: нажмите «Аккаунты» > > «Создать новый аккаунт» и заполните форму. Все аккаунты Google Ads, созданные из тестового аккаунта менеджера Google Ads, автоматически становятся тестовыми аккаунтами Google Ads.
  3. При желании создайте несколько кампаний в тестовом клиентском аккаунте Google Ads со страницы Google Ads.

Чтобы выполнить вызов API к клиенту Google Рекламы, необходимо предоставить доступ и соответствующие разрешения для вашего сервисного аккаунта клиенту Google Рекламы. Для этого вам потребуется доступ администратора к аккаунту клиента.

Как предоставить сервисному аккаунту доступ к вашему аккаунту Google Ads

  1. Начните с входа в свой аккаунт Google Ads как администратор.
  2. Перейдите в раздел Администрирование > Доступ и безопасность .
  3. Нажмите кнопку на вкладке Пользователи .
  4. Введите адрес электронной почты учётной записи службы в поле «Электронная почта» . Выберите соответствующий уровень доступа и нажмите кнопку «Добавить учётную запись» . Обратите внимание, что уровень доступа «Электронная почта» не поддерживается для учётных записей служб.
  5. Учетной записи сервиса предоставлен доступ.
  6. [Необязательно] По умолчанию вы не можете предоставить доступ администратора учётной записи службы. Если для ваших вызовов API требуется доступ администратора, вы можете расширить его следующим образом.
    1. Нажмите стрелку раскрывающегося списка рядом с уровнем доступа учетной записи службы в столбце Уровень доступа .
    2. В раскрывающемся списке выберите Администратор .

Загрузите инструменты и клиентские библиотеки

В зависимости от того, как вы предпочитаете совершать вызовы API, вы можете загрузить клиентскую библиотеку или HTTP-клиент.

Используйте клиентскую библиотеку

Загрузите и установите клиентскую библиотеку по вашему выбору.

Использовать HTTP-клиент (REST)

завиток

Загрузите и установите curl — инструмент командной строки для передачи данных через URL.

Google Cloud CLI

Следуйте инструкциям по установке gcloud CLI.

Инструкции для остальной части этого руководства были проверены на совместимость со следующей версией инструмента gcloud и могут не работать с предыдущими версиями из-за различий в поведении приложения или параметрах командной строки.

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

Сделать вызов API

Выберите предпочитаемый вами клиент для получения инструкций по выполнению вызова API:

Ява

Артефакты клиентской библиотеки публикуются в центральном репозитории Maven . Добавьте клиентскую библиотеку в качестве зависимости к вашему проекту следующим образом:

Зависимость Maven:

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

Зависимость 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

Создайте объект GoogleAdsClient следующим образом:

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов .

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

С#

Пакеты клиентской библиотеки опубликованы в репозитории Nuget.org . Начните с добавления ссылки NuGet на пакет Google.Ads.GoogleAds .

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

Создайте объект GoogleAdsConfig с соответствующими настройками и используйте его для создания объекта GoogleAdsClient .

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов .

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

Пакеты клиентской библиотеки опубликованы в репозитории Packagist . Перейдите в корневой каталог вашего проекта и выполните следующую команду, чтобы установить библиотеку и все её зависимости в каталог vendor/ корневого каталога вашего проекта. 

composer require googleads/google-ads-php:31.0.0

Сделайте копию файла google_ads_php.ini из репозитория GitHub и измените его, включив в него свои учетные данные. 

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

Создайте экземпляр объекта 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();

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов . 

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

Питон

Клиентская библиотека распространяется на PyPI и может быть установлена ​​с помощью команды pip следующим образом: 

python -m pip install google-ads==21.3.0

Сделайте копию файла google-ads.yaml из репозитория GitHub и измените его, включив в него свои учетные данные. 

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Создайте экземпляр GoogleAdsClient , вызвав метод GoogleAdsClient.load_from_storage . Передайте путь к файлу google-ads.yaml в виде строки при вызове метода: 

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

Добавьте обработчик к регистратору библиотеки, указывающий, куда выводить логи. Следующий код сообщит регистратору библиотеки выводить данные на консоль ( stdout ). 

import logging
import sys

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов . 

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 для клиентской библиотеки опубликованы на сайте Rubygems . Рекомендуется установить их с помощью bundler. Добавьте в Gemfile следующую строку: 

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

Затем выполните: 

bundle install

Сделайте копию файла google_ads_config.rb из репозитория GitHub и измените его, включив в него свои учетные данные. 

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

Создайте экземпляр GoogleAdsClient , указав путь к месту хранения этого файла. 

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов . 

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

Перл

Библиотека распространяется на CPAN . Начните с клонирования репозитория google-ads-perl в любую папку по вашему выбору. 

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

Перейдите в каталог google-ads-perl и выполните следующую команду в командной строке, чтобы установить все зависимости, необходимые для использования библиотеки. 

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

Сделайте копию файла googleads.properties из репозитория GitHub и измените его, включив в него свои учетные данные. 

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Создайте экземпляр Client , указав путь к месту хранения этого файла. 

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

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов . 

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

завиток

Начните с настройки учетной записи службы в качестве активных учетных данных в интерфейсе командной строки gcloud. 

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

Затем получите токен доступа OAuth 2.0 для API Google Ads. 

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

Затем создайте отчёт по кампании, используя метод GoogleAdsService.SearchStream , чтобы получить данные о кампаниях в вашем аккаунте. В этом руководстве не рассматриваются детали создания отчётов . 

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"

Содержимое query.json следующее: 

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
Назад
Введение
Далее
Распространенные ошибки