İstemci kitaplıklarımız, Google Ads API işlevi için üst düzey görünümler ve temel yapı taşları sağlayarak uygulamaların hızlı bir şekilde geliştirilmesini kolaylaştırır. API'yi kullanmaya yeni başlıyorsanız bir API ile başlamanızı öneririz.
Desteklenen API sürümleri
Tablo, hangi istemci kitaplıklarının hangi API sürümleriyle çalıştığını gösterir.
Java
Google Ads API |
Java için istemci kitaplığı |
v16 |
Min: 30.0.0 Max: - |
v15 |
Min: 28.0.0 Max: - |
v14 |
Min: 26.0.0 Max: - |
C#
Google Ads API |
.NET için istemci kitaplığı |
v16 |
Min: 18.1.0 Max: - |
v15 |
Min: 17.1.0 Max: - |
v14 |
Min: 16.1.0 Max: - |
PHP
Google Ads API |
PHP için istemci kitaplığı |
v16 |
Min: 22.1.0 Max: - |
v15 |
Min: 21.1.0 Max: - |
v14 |
Min: 19.2.0 Max: - |
Python
Google Ads API |
Python için istemci kitaplığı |
v15 |
Min: 22.1.0 Max: - |
v14 |
Min: 21.2.0 Max: - |
Ruby
Google Ads API |
Ruby için istemci kitaplığı |
v16 |
Min: 27.0.0 Max: - |
v15 |
Min: 25.0.0 Max: - |
v14 |
Min: 23.0.0 Max: - |
Perl
Google Ads API |
Perl için istemci kitaplığı |
v16 |
Min: 21.0.0 Max: - |
v15 |
Min: 19.0.0 Max: - |
v14 |
Min: 17.0.0 Max: - |
Yapılandırma
Her bir Ads API İstemci kitaplığı, davranışını özelleştirmek için kullanabileceğiniz farklı yapılandırma ayarları ve yükleme yöntemleri sunar.
Tüm istemci kitaplıklarında ortak olan ve yapılandırma ayarlarını yapmak için yüklenebilen ortam değişkenleri aşağıda verilmiştir:
- İstemci kitaplığı
GOOGLE_ADS_CONFIGURATION_FILE_PATH
: Yapılandırma dosyasının yolu.
- OAuth2
- Uygulama Modu
GOOGLE_ADS_CLIENT_ID
: Bu değeri OAuth2 istemci kimliğiniz olarak ayarlayın.GOOGLE_ADS_CLIENT_SECRET
: Bu değeri OAuth2 istemci gizli anahtarınız olarak ayarlayın.GOOGLE_ADS_REFRESH_TOKEN
: OAuth2 jetonlarını yeniden kullanmak istiyorsanız bu değeri önceden oluşturulmuş bir OAuth2 yenileme jetonu olarak ayarlayın. Bu ayar isteğe bağlıdır.
- Hizmet Hesabı Modu
GOOGLE_ADS_JSON_KEY_FILE_PATH
: Bu değeri OAuth2 JSON yapılandırma dosyası yoluna ayarlayın.GOOGLE_ADS_IMPERSONATED_EMAIL
: Bu değeri, kimliğine büründüğünüz hesabın e-posta adresine ayarlayın.
- Uygulama Modu
- Google Ads API
GOOGLE_ADS_DEVELOPER_TOKEN
: Bunu geliştirici jetonunuz olarak ayarlayın.GOOGLE_ADS_LOGIN_CUSTOMER_ID
: İstekte kullanılacak yetkili müşterinin müşteri kimliğidir, kısa çizgi (-
) içermez.GOOGLE_ADS_LINKED_CUSTOMER_ID
: Bu üst bilgi yalnızca Google Ads kullanıcı arayüzündeki Bağlı Hesaplar (Google Ads API'dekiAccountLink
kaynağı) üzerinden izin verildiğinde bir varlığın kaynaklarını güncelleyen yöntemler için gereklidir. Bu değeri, belirtilen müşteri kimliğinin kaynaklarını güncelleyen veri sağlayıcının müşteri kimliğine ayarlayın. Kısa çizgi (-
) olmadan ayarlanmalıdır. Bağlı Hesaplar hakkında daha fazla bilgi edinmek için Yardım Merkezi'ni ziyaret edin.
Ortam değişkenleri genellikle $HOME
dizininde bulunan .bashrc
veya .bash_profile
dosyası gibi bir bash yapılandırma dosyasında tanımlanır. Komut satırı kullanılarak da tanımlanabilirler.
Terminal kullanarak bir .bashrc
dosyası kullanarak ortam değişkeni tanımlamanın bazı temel adımları şunlardır:
# 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
Ortam değişkenleri, terminal örneğinizde doğrudan komut satırından da ayarlanabilir:
export GOOGLE_ADS_CLIENT_ID=1234567890
Diğer bir alternatif de ortam değişkenlerini kullanan komutu çağırırken bu değişkenleri ayarlamaktır:
GOOGLE_ADS_CLIENT_ID=1234567890 php /path/to/script/that/uses/envvar.php
Sayfalara ayırmada ara
GoogleAdsService.Search
genellikle sonuç sayfaları görüntüleyen etkileşimli uygulamalarda kullanılır.
İstemci kitaplığımız, sonuçları tekrarladığınızda otomatik olarak sayfalama işlemi uygular. Böylece, hepsini aynı anda indirip işleyebilirsiniz. Örneğin:
Java
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#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V16.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 ); } }
Python
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.' )
Ruby
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
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::V16::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; }
Kullanım alanına bağlı olarak aşağıdakileri yapmanız gerekebilir:
- Getirilen sayfa sayısını optimize edin.
- Bir seferde ne kadar sonucun depolanacağını optimize edin.
- Belirli bir sırayla sonuç sayfalarını indirin ve işleyin.
Bunun için sonuçlar yerine sayfa jetonlarını saklayabilirsiniz. Bu da kodunuzun karmaşıklığını artırır.
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( (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 ); } }
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}; } }
Kod örnekleri
Google Ads API'de yaygın olarak kullanılan bazı işlevlerle ilgili kod örneklerimize göz atın.