Para recuperar entidades de la API de Google Ads y datos de informes, usa uno de los siguientes métodos:
Estas son las distinciones generales de los dos métodos:
| GoogleAdsService.SearchStream | GoogleAdsService.Search | |
|---|---|---|
| Adecuado para el código de producción | Sí | Sí |
| Servicio | GoogleAdsService |
GoogleAdsService |
| Situación | Recuperación de objetos e informes | Recuperación de objetos e informes |
| Respuesta | Transmisión de objetos GoogleAdsRow |
Páginas de objetos GoogleAdsRow |
| Campos de la respuesta | Solo los especificados en la búsqueda | Solo los especificados en la búsqueda |
| Límites diarios | Límites diarios basados en los niveles de acceso | Límites diarios según los niveles de acceso |
SearchStream en comparación con Search
Mientras que Search envía varias solicitudes paginadas para descargar un informe completo, SearchStream envía una sola solicitud y, luego, inicia una conexión gRPC persistente con la API de Google Ads, independientemente del tamaño del informe.
En el caso de SearchStream, los paquetes de datos comienzan a descargarse de inmediato en lotes de objetos SearchGoogleAdsStreamResponse. Tu código puede iterar sobre los lotes entrantes a medida que llegan sin esperar a que finalice toda la transmisión.
Al eliminar el tiempo de red de ida y vuelta necesario para solicitar cada página individual de una respuesta Search, SearchStream ofrece un mejor rendimiento que la paginación, en especial para los informes grandes.
Ejemplo
En este ejemplo, se analiza un informe que consta de 100,000 filas. En la siguiente tabla, se desglosan las diferencias entre las solicitudes y las respuestas de los dos métodos:
| SearchStream | 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 la API | 1 transmisión continua | 10 respuestas |
Factores de rendimiento
En la mayoría de los casos de uso, recomendamos SearchStream en lugar de Search por los siguientes motivos:
- Informes de una sola página (menos de 10,000 filas): No hay diferencias significativas en el rendimiento entre los dos métodos.
- Informes de varias páginas:
SearchStreamsuele ser más rápido porque se evitan varios viajes de ida y vuelta de la red, y la lectura o escritura desde la memoria caché del disco es un factor menor. - Eficiencia de la memoria: Cuando se procesan informes grandes con
SearchStream, se itera a través de fragmentos de transmisión y se procesan las filas a medida que llegan, en lugar de almacenar en búfer todas las filas en la memoria a la vez para evitar errores de memoria insuficiente (OOM). - Resistencia de la conexión: Debido a que
SearchStreamdepende de una conexión persistente, los flujos de larga duración pueden interrumpirse por cortes de red o tiempos de espera de plazos. Configura los tiempos de espera de RPC adecuados y, luego, implementa la lógica de reintentos para los errores de transmisión transitorios.
Límites de frecuencia
Los límites de operación diarios para ambos métodos se ajustan a los límites estándar y a los niveles de acceso de tu proyecto de Google Cloud. Una sola consulta lógica de informes se cuenta como una operación para tu cuota diaria de operaciones, independientemente de si el resultado se transmite con SearchStream o se recupera en varias páginas almacenadas en caché con Search y un page_token. Sin embargo, cada solicitud Search paginada sigue contando como una llamada a RPC individual en relación con los límites de frecuencia a corto plazo.
Ejemplo de código
En el siguiente ejemplo de código, se muestra cómo ejecutar una consulta de informes de transmisión con las bibliotecas cliente:
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.V25.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: GoogleAdsClient, customer_id: str) -> None: ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService") query: str = """ SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id""" # Issues a search request using streaming. stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream( customer_id=customer_id, query=query ) for batch in stream: rows: List[GoogleAdsRow] = batch.results for row in rows: 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::V25::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; }