Transmite informes con GoogleAdsService

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

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: SearchStream suele 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 SearchStream depende 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;
}
      

curl