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

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

Ключевые понятия

  • Токен разработчика : Токен разработчика — это буквенно-цифровая строка длиной в 22 символа, которая идентифицирует ваше приложение для серверов Google Ads API. Он необходим для выполнения вызовов 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. Если вы скопировали этот идентификатор из пользовательского интерфейса 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 Manager.

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

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

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

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

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

Настройте свой проект в 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 Ads

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

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

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

    Перейдите в раздел «Учетные записи служб».

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Используйте HTTP-клиент (REST).

локон

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

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

Следуйте инструкциям по установке 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 . Добавьте клиентскую библиотеку в качестве зависимости в свой проект следующим образом:

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

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

Зависимость Gradle следующая:

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

Мы также рекомендуем использовать спецификацию компонентов (BOM) Google Ads API для управления версиями зависимостей. Инструкции см. в руководстве по использованию спецификации компонентов .

Создайте файл ~/ads.properties со следующим содержимым:

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

C#

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

dotnet add package Google.Ads.GoogleAds --version 25.0.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.V23.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 . Перейдите в корневой каталог вашего проекта и выполните следующую команду, чтобы установить библиотеку и все её зависимости в каталог vendor/ корневого каталога вашего проекта.

composer require googleads/google-ads-php:32.1.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
        );
    }
}

Python

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

python -m pip install google-ads==29.0.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.'
            )

Руби

Ruby-гемы для клиентской библиотеки публикуются на сайте хостинга гемов Rubygems . Рекомендуемый способ установки — использование bundler. Добавьте строку в ваш Gemfile:

gem 'google-ads-googleads', '~> 37.0.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

Perl

Библиотека распространяется через 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::V23::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;
}

локон

Для начала установите учетную запись службы в качестве активных учетных данных в интерфейсе командной строки 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/v23/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"
}

Если при первом вызове возникнут ошибки, см. раздел «Обработка ошибок API» для получения рекомендаций по устранению неполадок.