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

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

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

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

Предварительные требования

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

Настройте свой проект в Google API Console для доступа к Google Ads API.

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

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

Включить API Google Ads

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

После заполнения заявки Google автоматически рассмотрит её и в большинстве случаев предоставит доступ к Explorer Access. Если вам не предоставили доступ к Explorer Access, не волнуйтесь; это руководство содержит необходимые инструкции по настройке вашей учетной записи 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 вашего проекта Google Cloud. Проверьте страницу обзора API Google Ads, чтобы узнать свой уровень доступа к API.

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

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

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

Ваш проект Google Cloud нельзя использовать для выполнения 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>46.0.0</version>
</dependency>

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

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

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

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
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 26.1.0

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    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.V25.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:33.6.0

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

[GOOGLE_ADS]
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==31.2.0

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

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', '~> 43.0.0'

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

bundle install

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

Google::Ads::GoogleAds::Config.new do |c|
  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
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::V25::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/v25/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» для получения рекомендаций по устранению неполадок.

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