Transmite informes con GoogleAdsService

Para recuperar entidades y datos de informes de la API de Google Ads, usa uno de estos métodos:

• GoogleAdsService.SearchStream
• GoogleAdsService.Search

Estas son las diferencias generales entre los dos métodos:

	GoogleAdsService.SearchStream	GoogleAdsService.Search
Adecuado para el código de producción	Sí	Sí
Servicio	GoogleAdsService	GoogleAdsService
Situación	Recuperando objetos e informes	Recuperando objetos e informes
Respuesta	Stream de objetos GoogleAdsRow	Páginas de objetos GoogleAdsRow
Campos de la respuesta	Solo los especificados en la consulta	Solo los especificados en la consulta
Límites diarios	Límites diarios basados en los niveles de acceso	Límites diarios basados en los niveles de acceso

SearchStream contra 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 de gRPC persistente con la API de Google Ads, independientemente del tamaño del informe.

Para 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 termine todo el flujo.

Como se elimina el tiempo de ida y vuelta de la red que se requiere para solicitar cada página individual de una respuesta de 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 de solicitud y respuesta entre 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 de 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 menos importante.
• Eficiencia de la memoria: Cuando proceses informes grandes con SearchStream, itera a través de fragmentos de transmisión y procesa las filas a medida que lleguen, en lugar de almacenar en búfer todas las filas en la memoria a la vez para evitar errores de memoria insuficiente (OOM).
• Resiliencia de la conexión: Debido a que SearchStream se basa en una conexión persistente, las transmisiones de larga duración se pueden interrumpir por caídas de la red o tiempos de espera de fecha límite. Configura tiempos de espera de RPC adecuados y, además, implementa una lógica de reintentos para los errores de transmisión transitorios.

Límites de frecuencia

Los límites de operaciones diarias para ambos métodos se adhieren a los límites estándar y a los niveles de acceso de tu proyecto de Google Cloud. Una sola consulta de informe lógica se cuenta como una operación para tu cuota de operaciones diaria, 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 se sigue contando como una llamada 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 informe 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());
      }
    }
  }
}
GetCampaigns.java
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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;
    }
}
GetCampaigns.cs
      

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
        );
    }
}
GetCampaigns.php
      

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.'
            )
get_campaigns.py
      

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
get_campaigns.rb
      

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::V26::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;
}
get_campaigns.pl
      

curl

Nota: Aunque aquí no se proporciona una muestra de código de REST directa para este paso, puedes lograrlo con una solicitud de REST manual.

Consulta la documentación de la interfaz de REST de la API de Google Ads y las páginas de referencia específicas de cada método. Deberás construir la carga útil de JSON según las definiciones de proto.

Recursos clave:

• Usa REST
• Estructura de la interfaz de REST
• Asignaciones de campos JSON
• Consulta la referencia de la API de REST para conocer el servicio y el método específicos.