我们的客户端库提供了 Google Ads API 功能的总体视图和基本构件,可让您更轻松地快速开发应用。如果您刚开始使用该 API,我们建议您先从 API 开始。
支持的 API 版本
下表列出了支持每个可用 API 版本的具体库版本。
Java
API 和支持的最低/最高 Java 版本 | |
---|---|
12 版 | Min: 22.0.0 Max: - |
v11 | Min: 19.0.0 Max: - |
10 版 | Min:17.0.0 Max: - |
C#
API 和受支持的最低/最高 .NET 版本 | |
---|---|
12 版 | Min: 14.2.0 Max: - |
v11 | Min: 12.1.0 Max: - |
10 版 | Min: 11.0.0 Max: - |
PHP
API 和支持的最低/最高 PHP 版本 | |
---|---|
12 版 | Min: 17.1.0 Max: - |
v11 | Min: 15.1.0 Max: - |
10 版 | Min: 14.0.0 Max: - |
Python
API 和受支持的最低/最高 Python 版本 | |
---|---|
12 版 | Min: 19.0.0 Max: - |
v11 | Min:17.0.0 Max: - |
10 版 | Min: 15.0.0 Max: - |
Ruby
API 和受支持的最低/最高 Ruby 版本 | |
---|---|
12 版 | Min: 20.0.0 Max: - |
v11 | Min: 18.0.0 Max: - |
10 版 | Min: 16.0.0 Max: - |
Perl
API 和支持的最低/最高 Perl 版本 | |
---|---|
12 版 | Min: 14.0.0 Max: - |
v11 | Min: 12.0.0 Max: - |
10 版 | Min: 10.0.0 Max: - |
配置
每个 Ads API 客户端库都提供不同的配置设置和加载方法,可供您自定义其行为。
以下是所有客户端库通用的环境变量,可通过加载它们来设置配置设置:
- 客户端库
GOOGLE_ADS_CONFIGURATION_FILE_PATH
:配置文件的路径。
- OAuth2
- 应用模式
GOOGLE_ADS_CLIENT_ID
:将此值设为您的 OAuth2 客户端 ID。GOOGLE_ADS_CLIENT_SECRET
:将此值设为您的 OAuth2 客户端密钥。GOOGLE_ADS_REFRESH_TOKEN
:如果您想重复使用 OAuth2 令牌,请将此值设置为预先生成的 OAuth2 刷新令牌。此设置是可选的。
- 服务帐号模式
GOOGLE_ADS_JSON_KEY_FILE_PATH
:将此值设为 OAuth2 JSON 配置文件路径。GOOGLE_ADS_IMPERSONATED_EMAIL
:将此值设为您要模拟的帐号的电子邮件地址。
- 应用模式
- Google Ads API
GOOGLE_ADS_DEVELOPER_TOKEN
:将此列设置为您的开发者令牌。GOOGLE_ADS_LOGIN_CUSTOMER_ID
:这是请求中要使用的授权客户的客户 ID,它不带连字符 (-
)。GOOGLE_ADS_LINKED_CUSTOMER_ID
:只有在通过 Google Ads 界面中的“已关联的帐号”(Google Ads API 中的AccountLink
资源)获得权限时,更新实体资源的相应方法才需要此标头。请将此值设置为数据提供程序的客户 ID,该 ID 可更新指定客户 ID 的资源。不应设置连字符 (-
)。如需详细了解关联的帐号,请访问帮助中心。
环境变量通常在 bash 配置文件中定义,例如位于 $HOME
目录中的 .bashrc
或 .bash_profile
文件。您也可以使用命令行对其进行定义。
以下是使用终端通过 .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
通常用在显示搜索结果页面的交互式应用中。
当您迭代结果时,我们的客户端库会自动实现分页,以便您一次性依序下载和处理所有这些结果,例如:
Java
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."); } } }
C#
public void Run(GoogleAdsClient client, long customerId, long labelId) { // Get the GoogleAdsServiceClient. GoogleAdsServiceClient googleAdsService = client.GetService(Services.V12.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 ); } }
Python
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="v12") 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)
Ruby
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
Perl
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::V12::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; }
根据用例,您可能需要执行以下操作:
- 优化抓取的网页数量。
- 优化一次存储的结果数量。
- 以特定顺序下载和处理结果页。
这可以通过存储页面令牌(而非结果)来实现,这会增加代码的复杂性。
Java
/** * 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++; } } }
C#
/// <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 ); } }
Python
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}." )
Ruby
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
Perl
# 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}; } }