Наши клиентские библиотеки предоставляют представления высокого уровня и базовые строительные блоки функций Google Ads API, упрощая быструю разработку приложений. Мы рекомендуем начать с одного, если вы новичок в API.
Поддерживаемые версии API
В таблице ниже перечислены конкретные версии библиотек, которые поддерживают каждую доступную версию API.
Джава
| API и поддерживаемые минимальные/максимальные версии Java | |
|---|---|
| v13 | Min: 23.0.0 Max: - |
| v12 | Min: 22.0.0 Max: - |
| v11 | Min: 19.0.0 Max: - |
С#
| API и поддерживаемые версии Min/Max .NET | |
|---|---|
| v13 | Min: 15.0.0 Max: - |
| v12 | Min: 14.2.0 Max: - |
| v11 | Min: 12.1.0 Max: - |
PHP
| API и поддерживаемые минимальные/максимальные версии PHP | |
|---|---|
| v13 | Min: 18.0.0 Max: - |
| v12 | Min: 17.1.0 Max: - |
| v11 | Min: 15.1.0 Max: - |
Питон
| API и поддерживаемые минимальные/максимальные версии Python | |
|---|---|
| v13 | Min: 20.0.0 Max: - |
| v12 | Min: 19.0.0 Max: - |
| v11 | Min: 17.0.0 Max: - |
| v10 | Min: 15.0.0 Max: 19.0.0 |
Рубин
| API и поддерживаемые версии Min/Max Ruby | |
|---|---|
| v13 | Min: 21.0.0 Max: - |
| v12 | Min: 20.0.0 Max: - |
| v11 | Min: 18.0.0 Max: - |
Перл
| API и поддерживаемые версии Min/Max Perl | |
|---|---|
| v13 | Min: 15.0.0 Max: - |
| v12 | Min: 14.0.0 Max: - |
| v11 | Min: 12.0.0 Max: - |
Конфигурация
Каждая клиентская библиотека Ads API предоставляет различные параметры конфигурации и методы загрузки, которые можно использовать для настройки ее поведения.
Вот переменные среды, общие для всех клиентских библиотек, которые можно загрузить для установки параметров конфигурации:
- Клиентская библиотека
-
GOOGLE_ADS_CONFIGURATION_FILE_PATH: путь к файлу конфигурации.
-
- OAuth2
- Режим приложения
-
GOOGLE_ADS_CLIENT_ID: задайте для этого значения свой идентификатор клиента OAuth2. -
GOOGLE_ADS_CLIENT_SECRET: задайте для этого значения секрет вашего клиента OAuth2. -
GOOGLE_ADS_REFRESH_TOKEN: установите для этого значения предварительно сгенерированный токен обновления OAuth2, если вы хотите повторно использовать токены OAuth2. Этот параметр является необязательным.
-
- Режим сервисной учетной записи
-
GOOGLE_ADS_JSON_KEY_FILE_PATH: задайте для этого значения путь к файлу конфигурации OAuth2 JSON. -
GOOGLE_ADS_IMPERSONATED_EMAIL: установите это значение на адрес электронной почты учетной записи, которую вы выдаете за себя.
-
- Режим приложения
- API Google Рекламы
-
GOOGLE_ADS_DEVELOPER_TOKEN: установите для этого токена разработчика. -
GOOGLE_ADS_LOGIN_CUSTOMER_ID: это идентификатор авторизованного клиента для использования в запросе без дефисов (-). -
GOOGLE_ADS_LINKED_CUSTOMER_ID: этот заголовок требуется только для методов, которые обновляют ресурсы объекта при разрешении через связанные аккаунты в пользовательском интерфейсе Google Ads ( ресурсAccountLinkв Google Ads API). Задайте для этого значения идентификатор клиента поставщика данных, который обновляет ресурсы указанного идентификатора клиента. Он должен быть указан без дефисов (-). Чтобы узнать больше о связанных учетных записях, посетите Справочный центр .
-
Переменные среды обычно определяются в файле конфигурации 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, long labelId) {
try (GoogleAdsServiceClient googleAdsServiceClient =
googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
// Creates a request that will retrieve all campaign labels with the specified
// labelId using pages of the specified page size.
SearchGoogleAdsRequest request =
SearchGoogleAdsRequest.newBuilder()
.setCustomerId(Long.toString(customerId))
.setPageSize(PAGE_SIZE)
.setQuery(
"SELECT campaign.id, campaign.name, label.id, label.name "
+ "FROM campaign_label WHERE label.id = "
+ labelId
+ " ORDER BY campaign.id")
.build();
// Issues the search request.
SearchPagedResponse searchPagedResponse = googleAdsServiceClient.search(request);
// Checks if the total results count is greater than 0.
if (searchPagedResponse.getPage().getResponse().getTotalResultsCount() > 0) {
// Iterates over all rows in all pages and prints the requested field values for the
// campaigns and labels in each row. The results include the campaign and label
// objects because these were included in the search criteria.
for (GoogleAdsRow googleAdsRow : searchPagedResponse.iterateAll()) {
System.out.printf(
"Campaign found with name '%s', ID %d, and label: %s.%n",
googleAdsRow.getCampaign().getName(),
googleAdsRow.getCampaign().getId(),
googleAdsRow.getLabel().getName());
}
} else {
System.out.println("No campaigns were found.");
}
}
}
С#
public void Run(GoogleAdsClient client, long customerId, long labelId)
{
// Get the GoogleAdsServiceClient.
GoogleAdsServiceClient googleAdsService =
client.GetService(Services.V13.GoogleAdsService);
// Creates a request that will retrieve all campaign labels with the specified
// labelId using pages of the specified page size.
SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
{
CustomerId = customerId.ToString(),
Query = "SELECT campaign.id, campaign.name, label.id, label.name " +
$"FROM campaign_label WHERE label.id = {labelId} ORDER BY campaign.id",
};
try
{
int count = 0;
// Issues the search request and prints the result.
foreach (GoogleAdsRow googleAdsRow in googleAdsService.Search(request))
{
count++;
Console.WriteLine($"Campaign found with name '{googleAdsRow.Campaign.Name}'" +
$", ID {googleAdsRow.Campaign.Id}, and label: " +
$"'${googleAdsRow.Label.Name}'.");
}
if (count == 0)
{
Console.WriteLine("No campaigns were found.");
}
}
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,
int $labelId
) {
$googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
// Creates a query that will retrieve all campaign labels with the specified
// label ID.
$query = "SELECT campaign.id, campaign.name, label.id, label.name " .
"FROM campaign_label WHERE label.id = $labelId ORDER BY campaign.id";
// Issues a search request by specifying page size.
$response =
$googleAdsServiceClient->search($customerId, $query, ['pageSize' => self::PAGE_SIZE]);
// Iterates over all rows in all pages and prints the requested field values for the
// campaigns and labels in each row. The results include the campaign and label
// objects because these were included in the search criteria.
foreach ($response->iterateAllElements() as $googleAdsRow) {
/** @var GoogleAdsRow $googleAdsRow */
printf(
"Campaign found with name '%s', ID %d, and label: '%s'.%s",
$googleAdsRow->getCampaign()->getName(),
$googleAdsRow->getCampaign()->getId(),
$googleAdsRow->getLabel()->getName(),
PHP_EOL
);
}
}
питон
def main(client, customer_id, label_id, page_size):
"""Demonstrates how to retrieve all campaigns by a given label ID.
Args:
client: An initialized GoogleAdsClient instance.
customer_id: A client customer ID str.
label_id: A label ID to use when searching for campaigns.
page_size: An int of the number of results to include in each page of
results.
"""
ga_service = client.get_service("GoogleAdsService")
# Creates a query that will retrieve all campaign labels with the
# specified label ID.
query = f"""
SELECT
campaign.id,
campaign.name,
label.id,
label.name
FROM campaign_label
WHERE label.id = "{label_id}"
ORDER BY campaign.id"""
# Retrieves a google.api_core.page_iterator.GRPCIterator instance
# initialized with the specified request parameters.
request = client.get_type("SearchGoogleAdsRequest")
request.customer_id = customer_id
request.query = query
request.page_size = page_size
iterator = ga_service.search(request=request)
# Iterates over all rows in all pages and prints the requested field
# values for the campaigns and labels in each row. The results include
# the campaign and label objects because these were included in the
# search criteria.
for row in iterator:
print(
f'Campaign found with ID "{row.campaign.id}", name '
f'"{row.campaign.name}", and label "{row.label.name}".'
)
if __name__ == "__main__":
# GoogleAdsClient will read the google-ads.yaml configuration file in the
# home directory if none is specified.
googleads_client = GoogleAdsClient.load_from_storage(version="v13")
parser = argparse.ArgumentParser(
description="Lists all campaigns for specified customer."
)
# The following argument(s) should be provided to run the example.
parser.add_argument(
"-c",
"--customer_id",
type=str,
required=True,
help="The Google Ads customer ID.",
)
parser.add_argument(
"-l",
"--label_id",
type=str,
required=True,
help="A label ID associated with a campaign.",
)
args = parser.parse_args()
try:
main(
googleads_client,
args.customer_id,
args.label_id,
_DEFAULT_PAGE_SIZE,
)
except GoogleAdsException as ex:
print(
f'Request with ID "{ex.request_id}" failed with status '
f'"{ex.error.code().name}" and includes the following errors:'
)
for error in ex.failure.errors:
print(f'\tError with message "{error.message}".')
if error.location:
for field_path_element in error.location.field_path_elements:
print(f"\t\tOn field: {field_path_element.field_name}")
sys.exit(1)
Рубин
def get_campaigns_by_label(customer_id, label_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
query = <<~EOQUERY
SELECT campaign.id, campaign.name, label.id, label.name
FROM campaign_label WHERE label.id = '#{label_id}' ORDER BY campaign.id
EOQUERY
ga_service = client.service.google_ads
response = ga_service.search(
customer_id: customer_id,
query: query,
page_size: PAGE_SIZE,
)
response.each do |row|
puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
end
end
Перл
sub get_campaigns_by_label {
my ($api_client, $customer_id, $label_id) = @_;
# Create the search query.
my $search_query =
"SELECT campaign.id, campaign.name, label.id, label.name " .
"FROM campaign_label WHERE label.id = $label_id ORDER BY campaign.id";
# Create a search Google Ads request that will retrieve all campaign labels
# with the specified label Id using pages of the specified page size.
my $search_request =
Google::Ads::GoogleAds::V13::Services::GoogleAdsService::SearchGoogleAdsRequest
->new({
customerId => $customer_id,
query => $search_query,
pageSize => PAGE_SIZE
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
service => $google_ads_service,
request => $search_request
});
# Iterate over all rows in all pages and print the requested field values for the
# campaigns and labels in each row. The results include the campaign and label
# objects because these were included in the search criteria.
while ($iterator->has_next) {
my $google_ads_row = $iterator->next;
printf "Campaign found with name '%s', ID %d, and label: '%s'.\n",
$google_ads_row->{campaign}{name}, $google_ads_row->{campaign}{id},
$google_ads_row->{label}{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(
$customerId,
$searchQuery,
$searchOptions + [
// Uses the page token cached for the current page number.
'pageToken' => $pageTokens[$currentPageNumber]
]
);
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.