Наши клиентские библиотеки предоставляют высокоуровневые представления и базовые строительные блоки функциональности API Google Рекламы, что упрощает быструю разработку приложений. Мы рекомендуем начать с одного, если вы новичок в API.
Поддерживаемые версии API
В таблице показано, какие клиентские библиотеки с какими версиями API работают.
Джава
API Google Рекламы | Клиентская библиотека для Java |
v14 | Min: 26.0.0Max: - |
v13 | Min: 23.0.0Max: - |
С#
API Google Рекламы | Клиентская библиотека для .NET |
v14 | Min: 16.1.0Max: - |
v13 | Min: 15.0.0Max: - |
PHP
API Google Рекламы | Клиентская библиотека для PHP |
v14 | Min: 19.2.0Max: - |
v13 | Min: 18.0.0Max: - |
Питон
API Google Рекламы | Клиентская библиотека для Python |
v14 | Min: 21.2.0Max: - |
v13 | Min: 20.0.0Max: - |
Рубин
API Google Рекламы | Клиентская библиотека для Ruby |
v14 | Min: 23.0.0Max: - |
v13 | Min: 21.0.0Max: - |
Перл
API Google Рекламы | Клиентская библиотека для Perl |
v14 | Min: 17.0.0Max: - |
v13 | Min: 15.0.0Max: - |
Конфигурация
Каждая клиентская библиотека Ads API предоставляет различные параметры конфигурации и методы загрузки, которые вы можете использовать для настройки ее поведения.
Ниже приведены переменные среды, которые являются общими для всех клиентских библиотек и которые можно загрузить для установки параметров конфигурации:
- Клиентская библиотека
-
GOOGLE_ADS_CONFIGURATION_FILE_PATH: путь к файлу конфигурации.
-
- ОАут2
- Режим приложения
-
GOOGLE_ADS_CLIENT_ID: установите для этого значения идентификатор клиента OAuth2. -
GOOGLE_ADS_CLIENT_SECRET: установите это значение для секрета вашего клиента OAuth2. -
GOOGLE_ADS_REFRESH_TOKEN: задайте для этого значения предварительно созданный токен обновления OAuth2, если вы хотите повторно использовать токены OAuth2. Этот параметр является необязательным.
-
- Режим учетной записи службы
-
GOOGLE_ADS_JSON_KEY_FILE_PATH: задайте для этого значения путь к файлу конфигурации JSON OAuth2. -
GOOGLE_ADS_IMPERSONATED_EMAIL: установите в этом значении адрес электронной почты учетной записи, которую вы выдаете за себя.
-
- Режим приложения
- API Google Рекламы
-
GOOGLE_ADS_DEVELOPER_TOKEN: укажите свой токен разработчика. -
GOOGLE_ADS_LOGIN_CUSTOMER_ID: это идентификатор авторизованного клиента, который будет использоваться в запросе, без дефисов (-). -
GOOGLE_ADS_LINKED_CUSTOMER_ID: этот заголовок необходим только для методов, которые обновляют ресурсы объекта при наличии разрешения через связанные аккаунты в пользовательском интерфейсе Google Рекламы (ресурсAccountLinkв API Google Рекламы). Задайте для этого значения идентификатор клиента поставщика данных, который обновляет ресурсы с указанным идентификатором клиента. Его следует указывать без дефисов (-). Чтобы узнать больше о связанных аккаунтах, посетите Справочный центр .
-
Переменные среды обычно определяются в файле конфигурации bash, например файле .bashrc или .bash_profile расположенном в каталоге $HOME . Их также можно определить с помощью командной строки.
Вот несколько основных шагов по определению переменной среды с помощью файла .bashrc с помощью терминала:
# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
src ~/.bashrc
Переменные среды также можно установить в экземпляре вашего терминала непосредственно из командной строки:
export GOOGLE_ADS_CLIENT_ID=1234567890
Другой альтернативой является установка переменных среды при вызове команды, которая их использует:
GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php
Нумерация страниц поиска
GoogleAdsService.Search обычно используется в интерактивных приложениях, отображающих страницы результатов.
Наша клиентская библиотека автоматически реализует разбиение по страницам при повторении результатов, чтобы вы могли последовательно загружать и обрабатывать их все одновременно, например:
Джава
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());
}
}
}
}
С#
public void Run(GoogleAdsClient client, long customerId)
{
// Get the GoogleAdsService.
GoogleAdsServiceClient googleAdsService = client.GetService(
Services.V14.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
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
);
}
}
Питон
def main(client, customer_id):
ga_service = client.get_service("GoogleAdsService")
query = """
SELECT
campaign.id,
campaign.name
FROM campaign
ORDER BY campaign.id"""
# Issues a search request using streaming.
stream = ga_service.search_stream(customer_id=customer_id, query=query)
for batch in stream:
for row in batch.results:
print(
f"Campaign with ID {row.campaign.id} and name "
f'"{row.campaign.name}" was found.'
)
Рубин
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
Перл
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::V14::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;
}
В зависимости от варианта использования вам может потребоваться:
- Оптимизируйте количество загружаемых страниц.
- Оптимизируйте объем одновременного хранения результатов.
- Загружайте и обрабатывайте страницы результатов в определенном порядке.
Это можно сделать, сохраняя токены страниц вместо результатов, что усложняет ваш код.
Джава
/**
* Fetches and prints the results of a page of a search using a cache of page tokens.
*
* @param googleAdsClient the Google Ads API client.
* @param customerId the client customer ID.
* @param query the search query.
* @param pageNumber the number of the page to fetch and print results for.
* @param pageTokens the cache of page tokens to use and update.
*/
private static void fetchAndPrintPageResults(
GoogleAdsClient googleAdsClient,
long customerId,
String query,
int pageNumber,
SortedMap<Integer, String> pageTokens) {
int currentPageNumber;
// There is no need to fetch the pages we already know the page tokens for.
if (pageTokens.containsKey(pageNumber)) {
System.out.println(
"The token of the requested page was cached, we will use it to get the results.");
currentPageNumber = pageNumber;
} else {
System.out.printf(
"The token of the requested page was never cached, we will use the closest page we know"
+ " the token for (page %d) and sequentially get pages from there.%n",
pageTokens.size());
currentPageNumber = pageTokens.lastKey();
}
// Fetches next pages in sequence and caches their tokens until the requested page results
// are returned.
while (currentPageNumber <= pageNumber) {
// Fetches the next page.
System.out.printf("Fetching page %d...%n", currentPageNumber);
SearchGoogleAdsRequest request =
SearchGoogleAdsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setPageSize(PAGE_SIZE)
.setQuery(query)
.setReturnTotalResultsCount(true)
// Uses the page token cached for the current page number.
.setPageToken(pageTokens.get(currentPageNumber))
.build();
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
SearchPagedResponse response = googleAdsServiceClient.search(request);
cacheNextPageToken(pageTokens, response.getPage(), currentPageNumber + 1);
// Prints only the results for the requested page.
if (currentPageNumber == pageNumber) {
// Prints the results of the requested page.
System.out.printf("Printing results found for page %d:%n", pageNumber);
for (GoogleAdsRow googleAdsRow : response.getPage().getResponse().getResultsList()) {
System.out.printf(
"- Campaign with ID %d and name '%s'.%n",
googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
}
}
currentPageNumber++;
}
}
}
С#
/// <summary>
/// Fetches and prints the results of a page of a search using a cache of page tokens.
/// </summary>
/// <param name="googleAdsService">The Google Ads API Service client.</param>
/// <param name="request">The request.</param>
/// <param name="pageNumber">The number of the page to fetch and print results for.</param>
/// <param name="pageTokens">The cache of page tokens to use and update.</param>
/// <returns></returns>
private static void FetchAndPrintPageResults(GoogleAdsServiceClient googleAdsService,
SearchGoogleAdsRequest request, int pageNumber, Dictionary<int, string> pageTokens)
{
int currentPageNumber = pageNumber;
// There is no need to fetch the pages we already know the page tokens for.
if (pageTokens.ContainsKey(pageNumber - 1))
{
Console.WriteLine("The token of the requested page was cached, we will use it " +
"to get the results.");
currentPageNumber = pageNumber;
}
else
{
Console.WriteLine("The token of the requested page was never cached, we will " +
$"use the closest page we know the token for (page #{pageNumber}) and " +
$"sequentially get pages from there.");
currentPageNumber = pageNumber;
while (!pageTokens.ContainsKey(currentPageNumber))
{
currentPageNumber--;
}
}
SearchGoogleAdsResponse response = null;
// Fetches next pages in sequence and caches their tokens until the requested page
// results are returned.
while (currentPageNumber <= pageNumber)
{
// Fetches the next page.
Console.WriteLine($"Fetching page #{currentPageNumber}...");
request.PageToken = pageTokens[currentPageNumber - 1];
response = googleAdsService.Search(request)
.AsRawResponses().First();
CacheNextPageToken(pageTokens, response, currentPageNumber);
currentPageNumber++;
}
// Prints the results of the requested page.
Console.WriteLine($"Printing results found for the page #{pageNumber}");
foreach (GoogleAdsRow row in response.Results)
{
Campaign c = row.Campaign;
Console.WriteLine($" - Campaign with ID {c.Id} and name '{c.Name}'");
}
}
PHP
/**
* Fetches and prints the results of a page of a search using a cache of page tokens.
*
* @param GoogleAdsServiceClient $googleAdsServiceClient the Google Ads API Service client
* @param int $customerId the customer ID
* @param string $searchQuery the search query
* @param array $searchOptions the search options
* @param int $pageNumber the number of the page to fetch and print results for
* @param array &$pageTokens the cache of page tokens to use and update
*/
private static function fetchAndPrintPageResults(
GoogleAdsServiceClient $googleAdsServiceClient,
int $customerId,
string $searchQuery,
array $searchOptions,
int $pageNumber,
array &$pageTokens
) {
// There is no need to fetch the pages we already know the page tokens for.
if (isset($pageTokens[$pageNumber])) {
printf(
'The token of the requested page was cached, we will use it to get the results.%s',
PHP_EOL
);
$currentPageNumber = $pageNumber;
} else {
printf(
'The token of the requested page was never cached, we will use the closest page ' .
'we know the token for (page #%d) and sequentially get pages from there.%s',
count($pageTokens),
PHP_EOL
);
$currentPageNumber = count($pageTokens);
}
// Fetches next pages in sequence and caches their tokens until the requested page results
// are returned.
while ($currentPageNumber <= $pageNumber) {
// Fetches the next page.
printf('Fetching page #%d...%s', $currentPageNumber, PHP_EOL);
$response = $googleAdsServiceClient->search(
(new SearchGoogleAdsRequest(
$searchOptions + [
// Uses the page token cached for the current page number.
'page_token' => $pageTokens[$currentPageNumber]
]
))->setCustomerId($customerId)->setQuery($searchQuery)
);
self::cacheNextPageToken($pageTokens, $response->getPage(), $currentPageNumber);
$currentPageNumber++;
}
// Prints the results of the requested page.
printf('Printing results found for the page #%d:%s', $pageNumber, PHP_EOL);
foreach ($response->getPage()->getIterator() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
printf(
" - Campaign with ID %d and name '%s'.%s",
$googleAdsRow->getCampaign()->getId(),
$googleAdsRow->getCampaign()->getName(),
PHP_EOL
);
}
}
Питон
def fetch_and_print_results(
client, customer_id, query, page_number, page_tokens
):
"""Fetches and prints the results of a page using a cache of page tokens.
Args:
client: an initialized GoogleAdsClient instance.
customer_id: a client customer ID.
query: the search query.
page_number: the number of the page to fetch and print results for.
page_tokens: the cache of page tokens to use and update.
"""
current_page_number = None
# There is no need to fetch the pages we already know the page tokens for.
if page_tokens.get(page_number, None):
print(
"The token of the request page was cached, we will use it to get "
"the results."
)
current_page_number = page_number
else:
count = len(page_tokens.keys())
print(
"The token of the requested page was never cached, we will use "
f"the closest page we know the token for (page {count}) and "
"sequentially get pages from there."
)
current_page_number = count
googleads_service = client.get_service("GoogleAdsService")
# Fetches next pages in sequence and caches their tokens until the requested
# page results are returned.
while current_page_number <= page_number:
# Fetches the next page.
print(f"Fetching page {current_page_number}...")
request = client.get_type("SearchGoogleAdsRequest")
request.customer_id = customer_id
request.query = query
request.page_size = _PAGE_SIZE
request.return_total_results_count = True
# Uses the page token cached for the current page number.
request.page_token = page_tokens[current_page_number]
response = googleads_service.search(request=request)
cache_next_page_token(page_tokens, response, current_page_number)
current_page_number += 1
# Prints the results of the requested page.
print(f"Printing results found for the page {page_number}.")
for row in response.results:
print(
f" - Campaign with ID {row.campaign.id} and name "
f"{row.campaign.name}."
)
Рубин
def fetch_and_print_page_results(client, customer_id, query, page_size,
return_total_results_count, page_number, page_tokens)
if page_tokens.has_key?(page_number)
puts 'The page token for the request page was cached. Reusing it.'
current_page = page_number
else
puts "The token for the requested page has not been cached yet. We will start " \
"at page #{page_tokens.size} and request and cache pages until we find it."
current_page = page_tokens.size
end
while current_page <= page_number
puts page_tokens
response = client.service.google_ads.search(
customer_id: customer_id,
query: query,
page_size: page_size,
return_total_results_count: return_total_results_count,
page_token: page_tokens[current_page],
)
cache_next_page_token(page_tokens, response.page, current_page + 1)
current_page += 1
end
puts "Printing results found for page #{page_number}."
response.page.response.results.each do |result|
puts "- Campaign with ID #{result.campaign.id} and name #{result.campaign.name}."
end
end
Перл
# Fetches and prints the results of a page of a search using a cache of page tokens.
sub fetch_and_print_page_results {
my (
$api_client, $customer_id, $query,
$search_options, $page_number, $page_tokens
) = @_;
my $current_page_number = undef;
# There is no need to fetch the pages we already know the page tokens for.
if (exists $page_tokens->{$page_number}) {
print "The token of the requested page was cached, " .
"we will use it to get the results.\n";
$current_page_number = $page_number;
} else {
printf "The token of the requested page was never cached, " .
"we will use the closest page we know the token for (page #%d) " .
"and sequentially get pages from there.\n", scalar keys %$page_tokens;
$current_page_number = scalar keys %$page_tokens;
}
# Fetch next pages in sequence and cache their tokens until the requested page
# results are returned.
my $response = undef;
while ($current_page_number <= $page_number) {
# Fetch the next page.
printf "Fetching page #%d...\n", $current_page_number;
$response = $api_client->GoogleAdsService()->search({
customerId => $customer_id,
query => $query,
%$search_options,
# Use the page token cached for the current page number.
pageToken => $page_tokens->{$current_page_number}});
cache_next_page_token($page_tokens, $response, $current_page_number);
$current_page_number++;
}
# Print the results of the requested page.
printf "Printing results found for the page #%d:\n", $page_number;
foreach my $google_ads_row (@{$response->{results}}) {
printf
" - Campaign with ID %d and name '%s'.\n",
$google_ads_row->{campaign}{id},
$google_ads_row->{campaign}{name};
}
}
Примеры кода
Ознакомьтесь с примерами кода некоторых распространенных функций Google Ads API.