Transmisión de informes

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:

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.

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

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());
      }
    }
  }
}
GetKeywordStats.java
      

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;
    }
}
GetKeywordStats.cs
      

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

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."
            )
get_keyword_stats.py
      

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

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;
}
get_keyword_stats.pl