Это краткое руководство поможет вам выполнить первый вызов 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. На странице будет показан ваш текущий уровень доступа к API. Если у вас тестовый уровень доступа к API, разверните раздел Повысить уровень доступа. Следуйте инструкциям, чтобы подать заявку на уровень доступа Исследователь.
После того как вы заполните заявку, Google автоматически рассмотрит ее и в большинстве случаев повысит уровень до "Исследователь". Если у вас нет доступа к Explorer, не волнуйтесь. В этом руководстве вы найдете инструкции по настройке клиентского аккаунта Google Рекламы.
Как создать сервисный аккаунт
Для вызова API вам понадобится сервисный аккаунт и его ключ. Если вы уже используете другой API Google и создали сервисный аккаунт и ключ OAuth 2.0, можете пропустить этот шаг и использовать существующие учетные данные.
Как создать сервисный аккаунт и ключ
- В консоли Google Cloud нажмите на значок меню > IAM & Admin (IAM и администрирование) > Service Accounts (Сервисные аккаунты).
- Выберите сервисный аккаунт.
- Нажмите Keys (Ключи) > Add key (Добавить ключ) > Create new key (Создать ключ).
- Выберите JSON и нажмите Создать.
Новая пара ключей будет создана и скачана на ваш компьютер в виде нового файла. Сохраните скачанный JSON-файл под названием
credentials.jsonв рабочем каталоге. Этот файл – единственная копия ключа. Не добавляйте файлcredentials.jsonв систему управления версиями (например, добавьте его в файл.gitignore). - Нажмите Закрыть.
Как настроить клиентский аккаунт Google Рекламы
Сначала определите аккаунт Google Рекламы, к которому вы обращаетесь с помощью вызовов API. Тип аккаунта, к которому можно обращаться с помощью вызовов API, зависит от уровня доступа API вашего облачного проекта Google Cloud. Узнать уровень доступа к API можно на обзорной странице Google Ads API.
Уровни доступа "Исследователь", "Базовый" и "Стандартный"
Вы можете отправлять вызовы в рабочий аккаунт Google Рекламы. Однако при необходимости вы можете создать тестовый аккаунт Google Рекламы, следуя инструкциям на вкладке Тестовый доступ.
Проверьте доступ
Ваш проект Google Cloud нельзя использовать для вызовов API в рабочем аккаунте Google Рекламы. Вызовы API можно выполнять только в тестовых аккаунтах Google Рекламы.
Как создать тестовый аккаунт Google Рекламы
Ниже описано, как создать тестовый управляющий аккаунт Google Рекламы и тестовый аккаунт рекламодателя Google Рекламы в нем.
Нажмите синюю кнопку, чтобы создать тестовый управляющий аккаунт Google Рекламы. Если потребуется, войдите в аккаунт Google, который не связан с вашим рабочим управляющим аккаунтом Google Рекламы. Если у вас нет аккаунта, нажмите кнопку Создать аккаунт на этой странице.
- Войдите в тестовый управляющий аккаунт Google Рекламы и создайте тестовый клиентский аккаунт Google Рекламы. Для этого нажмите Аккаунты > > Создать аккаунт и заполните форму. Все аккаунты Google Рекламы, созданные в тестовом управляющем аккаунте Google Рекламы, автоматически становятся тестовыми.
- При необходимости создайте несколько кампаний в тестовом клиентском аккаунте Google Рекламы на странице Google Рекламы.
Чтобы выполнить вызов API для клиентского аккаунта Google Рекламы, необходимо предоставить сервисному аккаунту доступ к этому аккаунту и нужные разрешения. Для этого вам потребуется доступ с правами администратора к аккаунту клиента.
Как предоставить сервисному аккаунту доступ к аккаунту Google Рекламы
- Войдите в аккаунт Google Рекламы как администратор.
- Перейдите в раздел Администратор > Доступ и безопасность.
- Нажмите кнопку на вкладке Пользователи.
- Введите адрес электронной почты сервисного аккаунта в поле Email (Электронная почта).
Выберите нужный уровень доступа и нажмите кнопку Добавить аккаунт. Обратите внимание, что для сервисных аккаунтов не поддерживается уровень доступа "Только оповещения по электронной почте".
- Сервисному аккаунту предоставляется доступ.
- [Необязательно] При первоначальной настройке вы не можете предоставить сервисному аккаунту доступ с правами администратора. Если для вызовов API требуются права администратора, вы можете повысить уровень доступа, как описано ниже.
- В столбце Уровень доступа нажмите на значок раскрывающегося списка рядом с уровнем доступа сервисного аккаунта.
- В раскрывающемся списке выберите Администратор.
Как скачать инструменты и клиентские библиотеки
Вы можете скачать клиентскую библиотеку или 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:
- Скачайте копию файла
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")
Если вы не укажете аргумент 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 для установки библиотеки:
Добавьте gem в файл
Gemfileвашего приложения:gem 'google-ads-googleads', '~> 46.0.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::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.