Это краткое руководство поможет вам выполнить первый вызов 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 необходимо выполнить следующие шаги.
Настройте свой облачный проект для доступа к API Google Ads.
Проект Google Cloud используется для управления API Google и учетными данными API OAuth 2.0. Вы можете найти свои существующие проекты Google Cloud или создать новый, посетив консоль Google Cloud .
Для начала включите API Google Ads в своем проекте:
Далее перейдите на страницу обзора API Google Ads . На странице отображается ваш текущий уровень доступа к API. Если ваш текущий уровень доступа к API — «Тест» , разверните раздел « Повысить уровень доступа» . Следуйте инструкциям, чтобы применить уровень доступа «Explorer» .
После завершения подачи заявки Google автоматически проверит её и в большинстве случаев обновит до версии для Explorer. Если вам не предоставили доступ к Explorer, не волнуйтесь; это руководство содержит необходимые инструкции по настройке вашей учетной записи Google Ads .
Создайте учетную запись службы
Для выполнения вызовов API вам потребуется учетная запись службы и ключ учетной записи службы. Если вы уже используете другой API Google и создали учетную запись службы и ключ OAuth 2.0, вы можете пропустить этот шаг и повторно использовать существующие учетные данные.
Как создать учетную запись службы и ключ.
- В консоли Google Cloud перейдите в > IAM и администрирование > Учетные записи служб .
- Выберите свой сервисный аккаунт.
- Нажмите «Клавиши» > «Добавить клавишу» > «Создать новую клавишу» .
- Выберите JSON , затем нажмите «Создать» .
Ваша новая пара открытого/закрытого ключей будет сгенерирована и загружена на ваш компьютер в виде нового файла. Сохраните загруженный JSON-файл как
credentials.jsonв вашей рабочей директории. Этот файл является единственной копией данного ключа. Не добавляйтеcredentials.jsonв систему контроля версий (например, не добавляйте его в файл.gitignore). - Нажмите «Закрыть» .
Настройте свой клиентский аккаунт Google Ads.
Для начала определите аккаунт 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, созданный под ним.
Нажмите синюю кнопку, чтобы создать тестовый аккаунт Google Ads. Если потребуется, войдите в систему с помощью аккаунта Google, не связанного с вашим рабочим аккаунтом Google Ads. Если у вас его нет, используйте кнопку «Создать аккаунт» на этой странице, чтобы создать новый аккаунт Google.
- Находясь в своем аккаунте Google Ads Test Manager, создайте тестовый аккаунт Google Ads: нажмите «Аккаунты» > > «Создать новый аккаунт» и заполните форму. Все аккаунты Google Ads, созданные вами из аккаунта Google Ads Test Manager, автоматически становятся тестовыми аккаунтами Google Ads.
- При желании, на странице Google Ads можно создать несколько кампаний в тестовом аккаунте клиента.
Для выполнения API-запроса к клиенту Google Ads необходимо предоставить доступ и соответствующие разрешения учетной записи клиента Google Ads в рамках вашей сервисной учетной записи. Для этого требуется административный доступ к учетной записи клиента.
Как предоставить сервисному аккаунту доступ к вашему аккаунту Google Ads
- Для начала войдите в свой аккаунт Google Ads в качестве администратора.
- Перейдите в раздел Администрирование > Доступ и безопасность .
- Нажмите кнопку на вкладке "Пользователи" .

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

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

- [Необязательно] При первоначальной настройке вы не можете предоставить администраторский доступ к учетной записи службы. Если для ваших вызовов API требуется административный доступ, вы можете повысить уровень доступа следующим образом.
- В столбце «Уровень доступа» щелкните стрелку раскрывающегося списка рядом с уровнем доступа учетной записи службы.
- Выберите «Администратор» из выпадающего списка.
Загрузите инструменты и клиентские библиотеки.
В зависимости от того, как вы предпочитаете выполнять вызовы API, вы можете либо загрузить клиентскую библиотеку, либо HTTP-клиент.
Используйте клиентскую библиотеку
Загрузите и установите клиентскую библиотеку по вашему выбору.
Используйте HTTP-клиент (REST).
локон
Загрузите и установите 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>46.1.0</version>
</dependency>
Gradle : Добавьте следующую зависимость в файл build.gradle :
implementation 'com.google.api-ads:google-ads:46.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.4.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.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 . Убедитесь, что у вас установлена совместимая версия PHP и Composer, затем перейдите в корневой каталог вашего проекта и выполните следующую команду, чтобы установить библиотеку и её зависимости в каталог vendor/ вашего проекта:
composer require googleads/google-ads-php:35.1.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\V25\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==33.0.0Для аутентификации вызовов API настройте файл google-ads.yaml :
- Загрузите копию примера файла
google-ads.yamlиз репозитория GitHub. - Сохраните файл в своей домашней директории (
~/google-ads.yaml) или по указанному вами пути. Откройте
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")
Если вы опустите аргумент пути, 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-гемы для клиентской библиотеки опубликованы на RubyGems . Убедитесь, что у вас установлена поддерживаемая версия Ruby, и используйте Bundler для установки библиотеки:
Добавьте гем в
Gemfileвашего приложения:gem 'google-ads-googleads', '~> 45.1.0'Установите гем, выполнив команду:
bundle install
Чтобы настроить учетные данные:
- Скопируйте пример файла
google_ads_config.rbиз репозитория GitHub. - Сохраните файл в корневом каталоге вашего проекта или в вашем домашнем каталоге (
~). Откройте файл
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 .
Клонируйте репозиторий
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 perl Build perl Build install
Чтобы настроить учетные данные:
Скопируйте пример конфигурационного файла
googleads.propertiesиз репозитория GitHub в свою домашнюю директорию (~/googleads.properties):cp googleads.properties ~/googleads.propertiesОтредактируйте
~/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::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=JSON_KEY_FILE_PATHДалее получите токен доступа OAuth 2.0 для API Google Ads.
gcloud auth \
print-access-token \
--scopes='https://www.googleapis.com/auth/adwords'Создайте файл с именем query.json , содержащий ваш запрос на языке запросов Google Ads (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/v25/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» для получения рекомендаций по устранению неполадок.