Быстрое начало

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

Основные понятия

  • Проект Google Cloud. Проект Google Cloud – это основа для создания, включения и использования всех сервисов Google, включая управление API и учетными данными OAuth 2.0 API. Его можно создать в консоли Google Cloud.
  • Уровень доступа к API. Уровень доступа к API в вашем облачном проекте Google Cloud определяет, сколько вызовов API вы можете делать в день и в каких средах. Уровень доступа к API указан на обзорной странице Google Ads API.
  • Управляющий аккаунт Google Рекламы используется для управления другими аккаунтами Google Рекламы, которые могут быть набором клиентских аккаунтов Google Рекламы или другими управляющими аккаунтами Google Рекламы.
  • Клиентский аккаунт Google Рекламы. Аккаунт Google Рекламы, используемый для показа объявлений, на которые вы хотите настроить таргетинг с помощью вызовов API.
  • Идентификатор клиента. Десятизначный номер, который идентифицирует клиентский аккаунт Google Рекламы. Если вы скопировали этот идентификатор из интерфейса Google Рекламы, удалите дефисы.
  • OAuth 2.0. OAuth 2.0 – это стандартный отраслевой протокол авторизации, который используется всеми API Google. Чтобы генерировать учетные данные OAuth 2.0 для вызовов API, вам потребуется сервисный аккаунт и ключ.
  • Сервисный аккаунт. Особый тип аккаунта Google, который принадлежит приложению, а не отдельному пользователю. Он используется для аутентификации вашего приложения в Google Ads API. Чтобы получить сервисный аккаунт, вам понадобится проект Google Cloud.
  • Ключ сервисного аккаунта. JSON-файл учетных данных приложения, содержащий закрытый ключ сервисного аккаунта. Он используется для создания учетных данных OAuth 2.0, необходимых для аутентификации сервисного аккаунта при вызове Google Ads API. Чтобы получить ключ сервисного аккаунта, вам нужен сервисный аккаунт.

Требования

Чтобы выполнить вызов Google Ads API, выполните следующие действия.

Как настроить облачный проект для доступа к Google Ads API

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

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

Как включить Google Ads API

Затем перейдите на обзорную страницу Google Ads API. На этой странице указан ваш текущий уровень доступа к API. Если у вас тестовый уровень доступа, разверните раздел Повысить уровень доступа. Следуйте инструкциям, чтобы подать заявку на уровень доступа Исследователь.

После того как вы заполните заявку, Google автоматически проверит ее и в большинстве случаев повысит ваш уровень до исследователя. Если у вас нет доступа к Explorer, не волнуйтесь. В этом руководстве есть инструкции по настройке клиентского аккаунта Google Рекламы.

Как создать сервисный аккаунт

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

Как создать сервисный аккаунт и ключ

  1. В консоли Google Cloud нажмите на значок меню > IAM & Admin (IAM и администрирование) > Service Accounts (Сервисные аккаунты).

    Перейти к сервисным аккаунтам

  2. Выберите сервисный аккаунт.
  3. Нажмите Keys (Ключи) > Add key (Добавить ключ) > Create new key (Создать ключ).
  4. Выберите JSON и нажмите Create (Создать).

    Новая пара ключей будет создана и скачана на ваш компьютер в виде нового файла. Сохраните скачанный JSON-файл под названием credentials.json в рабочем каталоге. Этот файл – единственная копия ключа. Не добавляйте файл credentials.json в систему управления версиями (например, добавьте его в файл .gitignore).

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

Сначала определите, к какому аккаунту Google Рекламы вы выполняете вызовы API. Тип аккаунта, к которому можно выполнять вызовы API, зависит от уровня доступа к API вашего облачного проекта Google Cloud. Узнать свой уровень доступа к API можно на обзорной странице Google Ads API.

Уровни доступа Explorer, Basic и Standard

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

Проверьте доступ

Проект Google Cloud нельзя использовать для вызовов API в рабочем аккаунте Google Рекламы. Вызовы API можно выполнять только в тестовых аккаунтах Google Рекламы.

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

Ниже описано, как создать тестовый управляющий аккаунт Google Рекламы и тестовый клиентский аккаунт Google Рекламы в нем.

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

    Создайте тестовый управляющий аккаунт

  2. На странице выбора аккаунта нажмите Новый аккаунт Google Рекламы (или Создать аккаунт, если появится диалоговое окно Завершить настройку аккаунта?). На странице выбора аккаунта не будет указано, что он тестовый, но если вы перешли на нее по ссылке Создать тестовый управляющий аккаунт, то будет создан именно такой аккаунт.

  3. На странице Подтвердите информацию о компании укажите отображаемое название аккаунта, выберите основную цель использования аккаунта, страну, часовой пояс и валюту. Убедитесь, что в правом верхнем углу есть красный ярлык Тестовый аккаунт, нажмите Отправить, а затем – Посмотреть аккаунт, чтобы открыть панель управления тестового управляющего аккаунта.

  4. В тестовом управляющем аккаунте Google Рекламы создайте тестовый клиентский аккаунт Google Рекламы. Для этого нажмите Аккаунты > > Создать аккаунт. Укажите название аккаунта, выберите страну, часовой пояс и валюту, а затем сохраните аккаунт. Все клиентские аккаунты, созданные в тестовом управляющем аккаунте, автоматически становятся тестовыми. Инструкции по проверке приведены в разделе Просмотр тестовых аккаунтов.

  5. Необязательно. Создайте хотя бы одну тестовую кампанию в тестовом клиентском аккаунте на странице Google Рекламы. Если вы пропустите этот шаг, то ваш первый вызов API в разделе Вызов API будет успешным, но вернет пустой ответ (ноль кампаний).

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

Как предоставить сервисному аккаунту доступ к аккаунту Google Рекламы

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

Скачивание инструментов и клиентских библиотек

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

Использование клиентской библиотеки

Скачайте и установите клиентскую библиотеку.

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

curl

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

Интерфейс командной строки Google Cloud

Установите gcloud CLI, следуя руководству по установке Google Cloud 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:

Java

Артефакты клиентской библиотеки публикуются в репозитории Maven Central.

Чтобы управлять версиями зависимостей и предотвращать конфликты, ознакомьтесь с руководством по ведомости материалов (BOM) Google Ads API.

Если вы не используете BOM, добавьте клиентскую библиотеку непосредственно в проект с помощью одного из следующих инструментов сборки:

Maven. Добавьте в файл pom.xml следующую зависимость:

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

Gradle Добавьте в файл build.gradle следующую зависимость:

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

Создайте файл ads.properties в домашнем каталоге (~/ads.properties в Linux и macOS или %USERPROFILE%\ads.properties в Windows) со следующим содержимым:

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

Прежде чем отправлять запросы к API, создайте экземпляр GoogleAdsClient. По умолчанию fromPropertiesFile() загружает учетные данные из файла ads.properties, расположенного в домашнем каталоге:

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

Затем создайте отчет о кампаниях с помощью 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());
      }
    }
  }
}

C#

Пакеты клиентских библиотек публикуются в репозитории NuGet.org. Сначала добавьте ссылку на пакет NuGet в пакет Google.Ads.GoogleAds:

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

Чтобы выполнять вызовы API, создайте объект GoogleAdsConfig на основе настроек конфигурации (например, appsettings.json, переменных среды или пользовательских настроек) и передайте его для инициализации экземпляра 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);

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

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

PHP

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

composer require googleads/google-ads-php:35.3.0

Скопируйте файл google_ads_php.ini из хранилища GitHub, сохраните его в домашнем или корневом каталоге проекта и добавьте в него свои учетные данные:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

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

Создайте экземпляр GoogleAdsClient, используя файл конфигурации 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();

Затем создайте отчет о кампаниях с помощью метода 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
        );
    }
}

Python

Клиентская библиотека Google Ads API для Python распространяется через PyPI. Убедитесь, что у вас установлена поддерживаемая версия Python, а затем установите библиотеку с помощью pip:

python -m pip install google-ads==35.0.0

Чтобы выполнять аутентификацию вызовов API, настройте файл google-ads.yaml:

  1. Скачайте копию файла google-ads.yaml из хранилища GitHub.
  2. Сохраните файл в домашнем каталоге (~/google-ads.yaml) или по собственному пути.

  3. Откройте файл google-ads.yaml и добавьте в него свои учетные данные:

    login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH

    Настройте ведение журнала до инициализации клиента, чтобы библиотека регистрировала все предупреждения об инициализации или конфигурации. В примере ниже регистратор библиотеки настроен на вывод журналов INFO в стандартный вывод (stdout):

import logging
import sys

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

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

Если вы не укажете аргумент path, load_from_storage() будет искать файл конфигурации в домашнем каталоге (~/google-ads.yaml).

Затем создайте отчет о кампаниях с помощью метода 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.'
            )

Ruby

Гемы Ruby для клиентской библиотеки публикуются на сайте RubyGems. Убедитесь, что у вас установлена поддерживаемая версия Ruby, и используйте Bundler для установки библиотеки:

  1. Добавьте gem в файл Gemfile приложения:

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

  2. Установите гем, выполнив следующую команду:

    bundle install

Чтобы настроить учетные данные, выполните следующие действия:

  1. Скопируйте пример файла google_ads_config.rb из репозитория GitHub.
  2. Сохраните файл в корневом каталоге проекта или в домашнем каталоге (~).

  3. Откройте файл google_ads_config.rb и замените значения-плейсхолдеры своими учетными данными Google Ads API:

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

    Создайте экземпляр GoogleAdsClient, передав путь к файлу конфигурации (google_ads_config.rb):

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

Perl

Клиентская библиотека Perl распространяется через CPAN. Для ее работы требуется Perl 5.28 или более поздней версии и менеджер пакетов cpan или cpanm.

  1. Клонируйте хранилище google-ads-perl в нужный каталог:

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

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

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

Чтобы настроить учетные данные, выполните следующие действия:

  1. Скопируйте пример файла конфигурации googleads.properties из репозитория GitHub в домашний каталог (~/googleads.properties):

    cp googleads.properties ~/googleads.properties

  2. Добавьте в файл ~/googleads.properties свои учетные данные:

    jsonKeyFilePath=JSON_KEY_FILE_PATH
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

    Создайте экземпляр Client, передав путь к настроенному файлу googleads.properties (например, ~/googleads.properties):

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

Затем создайте отчет о кампаниях с помощью метода 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::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;
}

При выполнении скрипт передает соответствующие строки и выводит идентификатор и название каждой кампании в вашем аккаунте.

curl

Сначала задайте сервисный аккаунт в качестве активных учетных данных в gcloud CLI.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

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

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

Создайте файл с именем query.json, содержащий запрос на языке запросов Google Рекламы (GAQL):

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

Чтобы получить список кампаний в аккаунте, создайте отчет о кампаниях с помощью метода GoogleAdsService.SearchStream.

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"

Если при первом вызове возникнут ошибки, ознакомьтесь с разделом Обработка ошибок API.

Назад
Введение
Далее
Обработка ошибок