Berichts-Streaming

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Es gibt drei Methoden, Entitäten mit der Google Ads API abzurufen und Berichtsdaten abzurufen:

In diesem Leitfaden geht es hauptsächlich um das Streamen von Daten aus GoogleAdsService. Im Folgenden finden Sie eine Übersicht über die drei Methoden zum Datenabruf:

GoogleAdsService.Suchstream GoogleAdsService GET-Anfragen
Geeignet für Produktionscode Yes Yes Nein (nur für Debugging)
Dienst GoogleAdsService GoogleAdsService Ressourcenspezifische Dienste (z. B. CampaignService)
Szenario Objekte und Berichte abrufen Objekte und Berichte abrufen Objekte werden abgerufen
Antwort Stream von GoogleAdsRow-Objekten Seiten mit GoogleAdsRow-Objekten Ein Objekt, z. B. Campaign
Antwortfelder Nur in der Abfrage angegebene Werte Nur in der Abfrage angegebene Werte Alle Felder ausgefüllt
Tageslimits Tageslimits anhand von Zugriffsebenen Tageslimits anhand von Zugriffsebenen 1.000 Anfragen pro Tag

Während Search mehrere paginierte Anfragen zum Herunterladen des gesamten Berichts senden kann, sendet SearchStream eine einzelne Anfrage und initiiert eine dauerhafte Verbindung mit der Google Ads API, unabhängig von der Größe des Berichts.

Bei SearchStream werden Datenpakete sofort heruntergeladen, wobei das gesamte Ergebnis in einem Datenzwischenspeicher im Cache gespeichert wird. Ihr Code kann beginnen, die zwischengespeicherten Daten zu lesen, ohne auf den Abschluss des gesamten Streams warten zu müssen.

Da die Zeitspanne, die erforderlich ist, um jede einzelne Seite einer Search-Antwort anzufordern (je nach Anwendung), kann SearchStream eine bessere Leistung als Paging bieten, insbesondere bei größeren Berichten.

Beispiel

Angenommen, ein Bericht besteht aus 100,000 Zeilen. In der folgenden Tabelle sind die Abrechnungsunterschiede zwischen den beiden Methoden aufgeführt.

Suchstream Suchen
Seitengröße Nicht zutreffend 10.000 Zeilen pro Seite
Anzahl der API-Anfragen 1 Anfrage 10 Anfragen
Anzahl der API-Antworten 1 kontinuierlicher Stream 10 Antworten

Leistungsfaktoren

Im Allgemeinen empfehlen wir SearchStream über Search, und zwar aus den folgenden Gründen.

  • Berichte für einzelne Seiten (unter 10.000 Zeilen): Es gibt keine signifikanten Leistungsunterschiede zwischen den beiden Methoden.

  • Bei Berichten zu mehreren Seiten ist SearchStream in der Regel schneller, da mehrere Roundtrips vermieden werden müssen und das Lesen/Schreiben aus dem Festplatten-Cache weniger Faktor ist.

Ratenbegrenzungen

Die Tageslimits für beide Methoden entsprechen den Standardlimits und Zugriffsebenen Ihres Entwicklertokens. Eine einzelne Abfrage oder ein einzelner Bericht wird als ein Vorgang gezählt, unabhängig davon, ob das Ergebnis auf einer Seite angezeigt oder gestreamt wird.

Codebeispiele

Java

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

C#

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;
    }
}
      

PHP

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
        );
    }
}
      

Python

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

Ruby

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
      

Perl

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;
}