Transmite informes con GoogleAdsService

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

• GoogleAdsService.SearchStream
• GoogleAdsService.Search

Estas son las distinciones generales de los dos métodos:

	GoogleAdsService.SearchStream	GoogleAdsService.Search
Adecuado para código de producción	Sí	Sí
Servicio	GoogleAdsService	GoogleAdsService
Situación	Recuperación de objetos y de informes	Recuperación de objetos y de informes
Respuesta	Transmisión de objetos GoogleAdsRow	Páginas de GoogleAdsRow objetos
Campos de respuesta	Solo los especificados en la consulta	Solo los especificados en la consulta
Límites diarios	Límites diarios basados en niveles de acceso	Límites diarios basados en 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 SearchGoogleAdsStreamResponse objetos. 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 ida y vuelta de la red necesario para solicitar cada página individual de una respuesta Search, SearchStream ofrece un mejor rendimiento que la paginación, en especial para 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 la solicitud y la respuesta de los dos métodos:

	SearchStream	Search
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

Para 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: Por lo general, SearchStream es 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 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 llegan en lugar de almacenarlas en búfer en la memoria a la vez para evitar errores de memoria insuficiente (OOM).
• Resistencia de la conexión: Debido a que SearchStream se basa en una conexión persistente, las transmisiones de larga duración pueden interrumpirse por caídas de la red o tiempos de espera de fecha límite. Configura los tiempos de espera de RPC adecuados y, luego, implementa la lógica de reintento para los errores de transmisión transitorios.

Límites de frecuencia

Los límites de operación diarios para ambos métodos cumplen con los límites estándar y los niveles de acceso de tu proyecto de Google Cloud. Una sola consulta de informe lógico se cuenta como una operación para tu cuota de operaciones diarias independientemente de si el resultado se transmite con SearchStream o se recupera en varias páginas almacenadas en caché con Search con un page_token. Sin embargo, cada solicitud Search paginada aún se cuenta como una llamada RPC individual en comparació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.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;
    }
}
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::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;
}
get_campaigns.pl
      

curl

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

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

Recursos clave:

• Uso de REST
• Estructura de la interfaz REST
• Asignaciones de campos JSON
• Consulta la referencia de la API de REST para obtener información sobre el servicio y el método específicos.