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

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

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

  • Проект Google Cloud. Проект Google Cloud – это основа для создания, включения и использования всех сервисов Google, в том числе для управления API и учетными данными API OAuth 2.0. Его можно создать в консоли Google Cloud.
  • Уровень доступа к API. Уровень доступа к API вашего облачного проекта Google Cloud определяет количество вызовов API, которые вы можете выполнять в день, и среды, в которых можно выполнять вызовы API. Уровень доступа к API проекта указан на обзорной странице Google Ads API.
  • Управляющий аккаунт 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. Если у вас тестовый уровень доступа к 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 и нажмите Создать.

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

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

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

Уровни доступа "Исследователь", "Базовый" и "Стандартный"

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

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

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

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

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

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

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

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

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

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

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

Как скачать инструменты и клиентские библиотеки

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

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

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

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

curl

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

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

Следуйте руководству по установке 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:

Java

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

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

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

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

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

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

implementation 'com.google.api-ads:google-ads:48.0.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.5.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.2.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==34.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.0.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.

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