Existen tres métodos para recuperar entidades e informar datos con la API de Google Ads.
GoogleAdsService.SearchStream
GoogleAdsService.Search
- Solicitudes GET
Esta guía se centra principalmente en los datos de transmisión de GoogleAdsService
. A continuación, se detallan las distinciones de alto nivel de los tres métodos de recuperación de datos:
Servicio de Google Ads.SearchStream | Servicio de Google Ads | Solicitudes GET | |
---|---|---|---|
Apto para código de producción | Sí | Sí | No (solo para depuración) |
Service | GoogleAdsService |
GoogleAdsService |
Servicios específicos de recursos (por ejemplo, CampaignService ) |
Situación | Recupera informes y objetos | Recupera informes y objetos | Recupera objetos |
Respuesta | Flujo de objetos GoogleAdsRow |
Páginas de los objetos GoogleAdsRow |
Un objeto (por ejemplo, Campaign ) |
Campos de la respuesta | Solo los especificados en la consulta | Solo los especificados en la consulta | Todos los campos propagados |
Límites diarios | Límites diarios según los niveles de acceso | Límites diarios según los niveles de acceso | 1,000 solicitudes por día |
SearchStream frente a Search
Si bien Search
puede enviar varias solicitudes paginadas para descargar el informe completo, SearchStream
envía una sola solicitud e inicia una conexión persistente con la API de Google Ads, sin importar el tamaño del informe.
Para SearchStream
, los paquetes de datos comienzan a descargarse de inmediato con el resultado completo almacenado en caché en un búfer de datos. Tu código puede comenzar a leer los datos almacenados en búfer sin tener que esperar a que finalice toda la transmisión.
Al quitar el tiempo de red de ida y vuelta necesario para solicitar cada página individual de una respuesta Search
, según tu app, SearchStream
puede ofrecer un mejor rendimiento en la paginación, en especial para informes más grandes.
Ejemplo
Tomemos como ejemplo un informe que contenga 100,000
filas. En la siguiente tabla, se desglosan las diferencias contables entre los dos métodos.
Flujo de búsqueda | Buscar | |
---|---|---|
Tamaño de la página | No aplicable | 10,000 filas por página |
Cantidad de solicitudes a la API | 1 solicitud | 10 solicitudes |
Cantidad de respuestas de API | 1 transmisión continua | 10 respuestas |
Factores de rendimiento
En general, recomendamos SearchStream
en lugar de Search
por las siguientes razones.
Para los informes de una sola página (menos de 10,000 filas): no hay diferencias de rendimiento significativas entre los dos métodos.
En los informes de varias páginas,
SearchStream
suele ser más rápido, ya que se evitan varias idas y vueltas, y la lectura y escritura desde la caché de disco es menos un factor.
Límites de frecuencia
Los límites diarios de ambos métodos se adhieren a los límites estándar y los niveles de acceso del token del desarrollador. Una consulta o un informe individual se cuentan como una operación, sin importar el resultado que se pagina o se transmite.
Ejemplos de código
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { try (GoogleAdsServiceClient googleAdsServiceClient = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { String searchQuery = "SELECT campaign.id, " + "campaign.name, " + "ad_group.id, " + "ad_group.name, " + "ad_group_criterion.criterion_id, " + "ad_group_criterion.keyword.text, " + "ad_group_criterion.keyword.match_type, " + "metrics.impressions, " + "metrics.clicks, " + "metrics.cost_micros " + "FROM keyword_view " + "WHERE segments.date DURING LAST_7_DAYS " + "AND campaign.advertising_channel_type = 'SEARCH' " + "AND ad_group.status = 'ENABLED' " + "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') " // Limits to the 50 keywords with the most impressions in the date range. + "ORDER BY metrics.impressions DESC " + "LIMIT 50"; // Constructs the SearchGoogleAdsStreamRequest. SearchGoogleAdsStreamRequest request = SearchGoogleAdsStreamRequest.newBuilder() .setCustomerId(Long.toString(customerId)) .setQuery(searchQuery) .build(); // Creates and issues a search Google Ads stream request that will retrieve all of the // requested field values for the keyword. ServerStream<SearchGoogleAdsStreamResponse> stream = googleAdsServiceClient.searchStreamCallable().call(request); // Iterates through the results in the stream response and prints all of the requested // field values for the keyword in each row. for (SearchGoogleAdsStreamResponse response : stream) { for (GoogleAdsRow googleAdsRow : response.getResultsList()) { Campaign campaign = googleAdsRow.getCampaign(); AdGroup adGroup = googleAdsRow.getAdGroup(); AdGroupCriterion adGroupCriterion = googleAdsRow.getAdGroupCriterion(); Metrics metrics = googleAdsRow.getMetrics(); System.out.printf( "Keyword text '%s' with " + "match type '%s' " + "and ID %d " + "in ad group '%s' " + "with ID %d " + "in campaign '%s' " + "with ID %d " + "had %d impression(s), " + "%d click(s), " + "and %d cost (in micros) " + "during the last 7 days.%n", adGroupCriterion.getKeyword().getText(), adGroupCriterion.getKeyword().getMatchType(), adGroupCriterion.getCriterionId(), adGroup.getName(), adGroup.getId(), campaign.getName(), campaign.getId(), metrics.getImpressions(), metrics.getClicks(), metrics.getCostMicros()); } } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V12.GoogleAdsService); // Create the query. string query = @"SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.impressions, metrics.clicks, metrics.cost_micros FROM keyword_view WHERE segments.date DURING LAST_7_DAYS AND campaign.advertising_channel_type = 'SEARCH' AND ad_group.status = 'ENABLED' AND ad_group_criterion.status IN ('ENABLED','PAUSED') ORDER BY metrics.impressions DESC LIMIT 50"; try { // Issue a search request. googleAdsService.SearchStream(customerId.ToString(), query, delegate (SearchGoogleAdsStreamResponse resp) { // Display the results. foreach (GoogleAdsRow criterionRow in resp.Results) { Console.WriteLine( "Keyword with text " + $"'{criterionRow.AdGroupCriterion.Keyword.Text}', match type " + $"'{criterionRow.AdGroupCriterion.Keyword.MatchType}' and ID " + $"{criterionRow.AdGroupCriterion.CriterionId} in ad group " + $"'{criterionRow.AdGroup.Name}' with ID " + $"{criterionRow.AdGroup.Id} in campaign " + $"'{criterionRow.Campaign.Name}' with ID " + $"{criterionRow.Campaign.Id} had " + $"{criterionRow.Metrics.Impressions.ToString()} impressions, " + $"{criterionRow.Metrics.Clicks} clicks, and " + $"{criterionRow.Metrics.CostMicros} cost (in micros) during the " + "last 7 days."); } } ); } 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 keyword statistics. $query = "SELECT campaign.id, " . "campaign.name, " . "ad_group.id, " . "ad_group.name, " . "ad_group_criterion.criterion_id, " . "ad_group_criterion.keyword.text, " . "ad_group_criterion.keyword.match_type, " . "metrics.impressions, " . "metrics.clicks, " . "metrics.cost_micros " . "FROM keyword_view " . "WHERE segments.date DURING LAST_7_DAYS " . "AND campaign.advertising_channel_type = 'SEARCH' " . "AND ad_group.status = 'ENABLED' " . "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') " // Limits to the 50 keywords with the most impressions in the date range. . "ORDER BY metrics.impressions DESC " . "LIMIT 50"; // Issues a search stream request. /** @var GoogleAdsServerStreamDecorator $stream */ $stream = $googleAdsServiceClient->searchStream($customerId, $query); // Iterates over all rows in all messages and prints the requested field values for // the keyword in each row. foreach ($stream->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ $campaign = $googleAdsRow->getCampaign(); $adGroup = $googleAdsRow->getAdGroup(); $adGroupCriterion = $googleAdsRow->getAdGroupCriterion(); $metrics = $googleAdsRow->getMetrics(); printf( "Keyword text '%s' with " . "match type %s " . "and ID %d " . "in ad group '%s' " . "with ID %d " . "in campaign '%s' " . "with ID %d " . "had %d impression(s), " . "%d click(s), " . "and %d cost (in micros) " . "during the last 7 days.%s", $adGroupCriterion->getKeyword()->getText(), KeywordMatchType::name($adGroupCriterion->getKeyword()->getMatchType()), $adGroupCriterion->getCriterionId(), $adGroup->getName(), $adGroup->getId(), $campaign->getName(), $campaign->getId(), $metrics->getImpressions(), $metrics->getClicks(), $metrics->getCostMicros(), PHP_EOL ); } }
Python
def main(client, customer_id): ga_service = client.get_service("GoogleAdsService") query = """ SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.impressions, metrics.clicks, metrics.cost_micros FROM keyword_view WHERE segments.date DURING LAST_7_DAYS AND campaign.advertising_channel_type = 'SEARCH' AND ad_group.status = 'ENABLED' AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') ORDER BY metrics.impressions DESC LIMIT 50""" # Issues a search request using streaming. search_request = client.get_type("SearchGoogleAdsStreamRequest") search_request.customer_id = customer_id search_request.query = query stream = ga_service.search_stream(search_request) for batch in stream: for row in batch.results: campaign = row.campaign ad_group = row.ad_group criterion = row.ad_group_criterion metrics = row.metrics print( f'Keyword text "{criterion.keyword.text}" with ' f'match type "{criterion.keyword.match_type.name}" ' f"and ID {criterion.criterion_id} in " f'ad group "{ad_group.name}" ' f'with ID "{ad_group.id}" ' f'in campaign "{campaign.name}" ' f"with ID {campaign.id} " f"had {metrics.impressions} impression(s), " f"{metrics.clicks} click(s), and " f"{metrics.cost_micros} cost (in micros) during " "the last 7 days." )
Ruby
def get_keyword_stats(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 ga_service = client.service.google_ads # Limits to the 50 keywords with the most impressions in the date range. # If you wish to exclude entries with zero impressions, include a # predicate in the WHERE statement like 'metrics.impressions > 0' query = <<~QUERY SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, metrics.impressions, metrics.clicks, metrics.cost_micros FROM keyword_view WHERE segments.date DURING LAST_7_DAYS AND campaign.advertising_channel_type = 'SEARCH' AND ad_group.status = 'ENABLED' AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') ORDER BY metrics.impressions DESC LIMIT 50 QUERY responses = ga_service.search_stream(customer_id: customer_id, query: query) responses.each do |response| response.results.each do |row| campaign = row.campaign ad_group = row.ad_group criterion = row.ad_group_criterion metrics = row.metrics puts "Keyword text '#{criterion.keyword.text}' with match type "\ "'#{criterion.keyword.match_type}' and ID #{criterion.criterion_id} in "\ "ad group '#{ad_group.name}' with ID #{ad_group.id} in campaign "\ "'#{campaign.name}' with ID #{campaign.id} had #{metrics.impressions} "\ "impression(s), #{metrics.clicks} click(s), and #{metrics.cost_micros} "\ "cost (in micros) during the last 7 days." end end end
Perl
sub get_keyword_stats { my ($api_client, $customer_id) = @_; # Limit to the 50 keywords with the most impressions in the date range. # If you wish to exclude entries with zero impressions, include a # predicate in the WHERE statement like 'metrics.impressions > 0'. my $search_query = "SELECT campaign.id, campaign.name, ad_group.id, ad_group.name, " . "ad_group_criterion.criterion_id, ad_group_criterion.keyword.text, " . "ad_group_criterion.keyword.match_type, " . "metrics.impressions, metrics.clicks, metrics.cost_micros " . "FROM keyword_view WHERE segments.date DURING LAST_7_DAYS " . "AND campaign.advertising_channel_type = 'SEARCH' " . "AND ad_group.status = 'ENABLED' " . "AND ad_group_criterion.status IN ('ENABLED', 'PAUSED') " . "ORDER BY metrics.impressions DESC LIMIT 50"; # Create a search Google Ads stream request that will retrieve all keyword # statistics. my $search_stream_request = Google::Ads::GoogleAds::V12::Services::GoogleAdsService::SearchGoogleAdsStreamRequest ->new({ customerId => $customer_id, query => $search_query, }); # 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 keyword in each row. $search_stream_handler->process_contents( sub { my $google_ads_row = shift; my $campaign = $google_ads_row->{campaign}; my $ad_group = $google_ads_row->{adGroup}; my $ad_group_criterion = $google_ads_row->{adGroupCriterion}; my $metrics = $google_ads_row->{metrics}; printf "Keyword text '%s' with match type '%s' and ID %d in ad group" . " '%s' with ID %d in campaign '%s' with ID %d had %d impression(s), " . "%d click(s), and %d cost (in micros) during the last 7 days.\n", $ad_group_criterion->{keyword}{text}, $ad_group_criterion->{keyword}{matchType}, $ad_group_criterion->{criterionId}, $ad_group->{name}, $ad_group->{id}, $campaign->{name}, $campaign->{id}, $metrics->{impressions}, $metrics->{clicks}, $metrics->{costMicros}; }); return 1; }