Наши клиентские библиотеки предоставляют представления высокого уровня и базовые строительные блоки функций Google Ads API, упрощая быструю разработку приложений. Мы рекомендуем начать с одного, если вы новичок в API.
Поддерживаемые версии API
В таблице показано, какие клиентские библиотеки работают с какими версиями API.
Джава
API Google Рекламы | Клиентская библиотека для Java |
v13 | Min: 23.0.0 Max: - |
v12 | Min: 22.0.0 Max: - |
С#
API Google Рекламы | Клиентская библиотека для .NET |
v13 | Min: 15.0.0 Max: - |
v12 | Min: 14.2.0 Max: - |
PHP
API Google Рекламы | Клиентская библиотека для PHP |
v13 | Min: 18.0.0 Max: - |
v12 | Min: 17.1.0 Max: - |
питон
API Google Рекламы | Клиентская библиотека для Python |
v13 | Min: 20.0.0 Max: - |
v12 | Min: 19.0.0 Max: - |
Рубин
API Google Рекламы | Клиентская библиотека для Ruby |
v13 | Min: 21.0.0 Max: - |
v12 | Min: 20.0.0 Max: - |
Перл
API Google Рекламы | Клиентская библиотека для Perl |
v13 | Min: 15.0.0 Max: - |
v12 | Min: 14.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::V14::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.