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

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

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

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

    Новая пара ключей будет создана и скачана на ваш компьютер в виде нового файла. Сохраните скачанный 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 Рекламы, созданные в тестовом управляющем аккаунте, автоматически становятся тестовыми.
  3. При желании создайте несколько кампаний в тестовом клиентском аккаунте Google Рекламы на странице Google Рекламы.

Чтобы выполнить вызов 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.

Чтобы управлять версиями зависимостей и предотвращать конфликты, ознакомьтесь с руководством по спецификации 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.

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