Grundlegendes zu Berichten

Einführung

In diesem Leitfaden erfahren Sie, wie Sie mit der API einen Bericht erstellen und herunterladen. Sie umfasst sowohl eine vorhandene gespeicherte Berichtsabfrage verwenden und eine Ad-hoc-Berichtsabfrage erstellen.

Hinweis :Weitere Informationen dazu, wie Ad Manager-Berichtsdaten erhoben werden, finden Sie unter Impressionen und Klicks zählen und IAB-Compliance.

Vorbereitung

• Zugriff auf ein Google Ad Manager-Produktionsnetzwerk
• Ad Manager-Clientbibliothek

Primer

Wenn Sie mit der Berichterstellung in Ad Manager nicht vertraut sind, finden Sie unter Neuen Bericht erstellen eine Übersicht dazu, wie Sie einen Bericht in der Ad Manager-Benutzeroberfläche ausführen. Die Benutzeroberfläche bietet eine Vorschau der Ausgabe sowie Kurzinfos, die erklären, welche Spalten- und Dimensionskombinationen unterstützt werden. Bei einer komplexen Berichtsabfrage ist es unter Umständen einfacher, und rufen Sie die Abfrage dann mit der API ab.

Abrufen einer gespeicherten ReportQuery

ReportQuery enthält alle Details des Berichts. Sie können Berichtsabfragen in auf der Ad Manager-Benutzeroberfläche und rufen sie mit der Funktion ReportService.getSavedQueriesByStatement . Die gespeicherte Abfrage-ID ist in der URL enthalten, wenn Sie eine Abfrage in der Benutzeroberfläche aufrufen. In der URL https://www.google.com/admanager/1234#reports/report/detail/report_id=456789 ist die Abfrage-ID 456789.

Wenn eine Abfrage nicht mit Ihrer API-Version kompatibel ist, SavedQuery.reportQuery wird null sein und SavedQuery.isCompatibleWithApiVersion wird false sein.

Kompatible gespeicherte Abfragen können mit oder ohne Änderungen ausgeführt werden.

Java

    StatementBuilder statementBuilder =
        new StatementBuilder()
            .where("id = :id")
            .orderBy("id ASC")
            .limit(1)
            .withBindVariableValue("id", savedQueryId);

    SavedQueryPage page = reportService.getSavedQueriesByStatement(statementBuilder.toStatement());
    SavedQuery savedQuery = Iterables.getOnlyElement(Arrays.asList(page.getResults()));

    if (!savedQuery.getIsCompatibleWithApiVersion()) {
      throw new IllegalStateException("The saved query is not compatible with this API version.");
    }

    ReportQuery reportQuery = savedQuery.getReportQuery();
    

Auf GitHub ansehen

Python

  statement = (ad_manager.StatementBuilder(version='v202508')
               .Where('id = :id')
               .WithBindVariable('id', int(saved_query_id))
               .Limit(1))

  response = report_service.getSavedQueriesByStatement(
      statement.ToStatement())

  if 'results' in response and len(response['results']):
    saved_query = response['results'][0]

    if saved_query['isCompatibleWithApiVersion']:
      report_job = {}

      # Set report query and optionally modify it.
      report_job['reportQuery'] = saved_query['reportQuery']
    

Auf GitHub ansehen

PHP

      $statementBuilder = (new StatementBuilder())->where('id = :id')
          ->orderBy('id ASC')
          ->limit(1)
          ->withBindVariableValue('id', $savedQueryId);

      $savedQueryPage = $reportService->getSavedQueriesByStatement(
          $statementBuilder->toStatement()
      );
      $savedQuery = $savedQueryPage->getResults()[0];

      if ($savedQuery->getIsCompatibleWithApiVersion() === false) {
          throw new UnexpectedValueException(
              'The saved query is not compatible with this API version.'
          );
      }

      $reportQuery = $savedQuery->getReportQuery();
    

Auf GitHub ansehen

C#

StatementBuilder statementBuilder = new StatementBuilder()
    .Where("id = :id")
    .OrderBy("id ASC")
    .Limit(1)
    .AddValue("id", savedQueryId);

SavedQueryPage page =
    reportService.getSavedQueriesByStatement(statementBuilder.ToStatement());
SavedQuery savedQuery = page.results[0];

if (!savedQuery.isCompatibleWithApiVersion)
{
    throw new InvalidOperationException("Saved query is not compatible with this " +
        "API version");
}

// Optionally modify the query.
ReportQuery reportQuery = savedQuery.reportQuery;
    

Auf GitHub ansehen

Ruby

  statement = ad_manager.new_statement_builder do |sb|
    sb.where = 'id = :saved_query_id'
    sb.with_bind_variable('saved_query_id', saved_query_id)
  end

  saved_query_page = report_service.get_saved_queries_by_statement(
      statement.to_statement()
  )

  unless saved_query_page[:results].nil?
    saved_query = saved_query_page[:results].first

    if saved_query[:is_compatible_with_api_version]
      # Create report job.
      report_job = {:report_query => saved_query[:report_query]}
    else
      raise StandardError, 'Report query is not compatible with the API'
    end
    

Auf GitHub ansehen

Informationen zum Ausführen der Abfrage finden Sie unter ReportJob erstellen.

ReportQuery erstellen

Neben gespeicherten Abfragen können Sie auch eine Ad-hoc-ReportQuery erstellen. Dazu müssen Sie die Methode Dimensionen Dimension Attribute Spalten, Filter und Zeitraum. Dieses Beispiel bezieht sich auf einen einfachen Auslieferungsbericht für einen einzelnen Auftrag.

Java

    // Create report query.
    ReportQuery reportQuery = new ReportQuery();
    reportQuery.setDimensions(new Dimension[] {Dimension.DATE, Dimension.ORDER_ID});
    reportQuery.setColumns(
        new Column[] {
          Column.AD_SERVER_IMPRESSIONS,
          Column.AD_SERVER_CLICKS,
          Column.AD_SERVER_CTR,
          Column.AD_SERVER_CPM_AND_CPC_REVENUE
        });
    reportQuery.setDimensionAttributes(
        new DimensionAttribute[] {
          DimensionAttribute.ORDER_TRAFFICKER,
          DimensionAttribute.ORDER_START_DATE_TIME,
          DimensionAttribute.ORDER_END_DATE_TIME
        });

    // Create statement to filter for an order.
    StatementBuilder statementBuilder =
        new StatementBuilder()
            .where("ORDER_ID = :orderId")
            .withBindVariableValue("orderId", orderId);

    // Set the filter statement.
    reportQuery.setStatement(statementBuilder.toStatement());

    // Set the start and end dates or choose a dynamic date range type.
    reportQuery.setDateRangeType(DateRangeType.CUSTOM_DATE);
    reportQuery.setStartDate(
        DateTimes.toDateTime("2013-05-01T00:00:00", "America/New_York").getDate());
    reportQuery.setEndDate(
        DateTimes.toDateTime("2013-05-31T00:00:00", "America/New_York").getDate());
    

Python

  # Create statement object to filter for an order.
  statement = (ad_manager.StatementBuilder(version='v202508')
               .Where('ORDER_ID = :id')
               .WithBindVariable('id', int(order_id))
               .Limit(None)  # No limit or offset for reports
               .Offset(None))

  # Set the start and end dates of the report to run (past 8 days).
  end_date = datetime.now().date()
  start_date = end_date - timedelta(days=8)

  # Create report job.
  report_job = {
      'reportQuery': {
          'dimensions': ['ORDER_ID', 'ORDER_NAME'],
          'dimensionAttributes': ['ORDER_TRAFFICKER', 'ORDER_START_DATE_TIME',
                                  'ORDER_END_DATE_TIME'],
          'statement': statement.ToStatement(),
          'columns': ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS',
                      'AD_SERVER_CTR', 'AD_SERVER_CPM_AND_CPC_REVENUE',
                      'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
          'dateRangeType': 'CUSTOM_DATE',
          'startDate': start_date,
          'endDate': end_date
      }
  }
    

PHP

      // Create report query.
      $reportQuery = new ReportQuery();
      $reportQuery->setDimensions(
          [
              Dimension::ORDER_ID,
              Dimension::ORDER_NAME
          ]
      );
      $reportQuery->setDimensionAttributes(
          [
              DimensionAttribute::ORDER_TRAFFICKER,
              DimensionAttribute::ORDER_START_DATE_TIME,
              DimensionAttribute::ORDER_END_DATE_TIME
          ]
      );
      $reportQuery->setColumns(
          [
              Column::AD_SERVER_IMPRESSIONS,
              Column::AD_SERVER_CLICKS,
              Column::AD_SERVER_CTR,
              Column::AD_SERVER_CPM_AND_CPC_REVENUE,
              Column::AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM
          ]
      );

      // Create statement to filter for an order.
      $statementBuilder = (new StatementBuilder())
          ->where('ORDER_ID = :orderId')
          ->withBindVariableValue(
              'orderId',
              $orderId
          );

      // Set the filter statement.
      $reportQuery->setStatement($statementBuilder->toStatement());

      // Set the start and end dates or choose a dynamic date range type.
      $reportQuery->setDateRangeType(DateRangeType::CUSTOM_DATE);
      $reportQuery->setStartDate(
          AdManagerDateTimes::fromDateTime(
              new DateTime(
                  '-10 days',
                  new DateTimeZone('America/New_York')
              )
          )
              ->getDate()
      );
      $reportQuery->setEndDate(
          AdManagerDateTimes::fromDateTime(
              new DateTime(
                  'now',
                  new DateTimeZone('America/New_York')
              )
          )
              ->getDate()
      );
    

C#

// Create report job.
ReportJob reportJob = new ReportJob();
reportJob.reportQuery = new ReportQuery();
reportJob.reportQuery.dimensions = new Dimension[]
{
    Dimension.ORDER_ID,
    Dimension.ORDER_NAME
};
reportJob.reportQuery.dimensionAttributes = new DimensionAttribute[]
{
    DimensionAttribute.ORDER_TRAFFICKER,
    DimensionAttribute.ORDER_START_DATE_TIME,
    DimensionAttribute.ORDER_END_DATE_TIME
};
reportJob.reportQuery.columns = new Column[]
{
    Column.AD_SERVER_IMPRESSIONS,
    Column.AD_SERVER_CLICKS,
    Column.AD_SERVER_CTR,
    Column.AD_SERVER_CPM_AND_CPC_REVENUE,
    Column.AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM
};

// Set a custom date range for the last 8 days
reportJob.reportQuery.dateRangeType = DateRangeType.CUSTOM_DATE;
System.DateTime endDateTime = System.DateTime.Now;
reportJob.reportQuery.startDate = DateTimeUtilities
    .FromDateTime(endDateTime.AddDays(-8), "America/New_York").date;
reportJob.reportQuery.endDate = DateTimeUtilities
    .FromDateTime(endDateTime, "America/New_York").date;

// Create statement object to filter for an order.
StatementBuilder statementBuilder = new StatementBuilder().Where("ORDER_ID = :id")
    .AddValue("id", orderId);
reportJob.reportQuery.statement = statementBuilder.ToStatement();
    

Ruby

  # Specify a report to run for the last 7 days.
  report_end_date = ad_manager.today()
  report_start_date = report_end_date - 7

  # Create statement object to filter for an order.
  statement = ad_manager.new_report_statement_builder do |sb|
    sb.where = 'ORDER_ID = :order_id'
    sb.with_bind_variable('order_id', order_id)
  end

  # Create report query.
  report_query = {
    :date_range_type => 'CUSTOM_DATE',
    :start_date => report_start_date.to_h,
    :end_date => report_end_date.to_h,
    :dimensions => ['ORDER_ID', 'ORDER_NAME'],
    :dimension_attributes => ['ORDER_TRAFFICKER', 'ORDER_START_DATE_TIME',
        'ORDER_END_DATE_TIME'],
    :columns => ['AD_SERVER_IMPRESSIONS', 'AD_SERVER_CLICKS', 'AD_SERVER_CTR',
        'AD_SERVER_CPM_AND_CPC_REVENUE', 'AD_SERVER_WITHOUT_CPD_AVERAGE_ECPM'],
    :statement => statement.to_statement()
  }
    

ReportJob erstellen

Sobald Sie über eine ReportQuery verfügen, ist es an der Zeit, den Bericht zu erstellen. Die ReportJob-Objekt enthält den Status eines Berichts und informiert Sie, wenn er heruntergeladen werden kann. Bis erstellen Sie den Bericht, verwenden Sie ReportService.runReportJob .

Java

    // Create report job.
    ReportJob reportJob = new ReportJob();
    reportJob.setReportQuery(reportQuery);

    // Run report job.
    reportJob = reportService.runReportJob(reportJob);
    

Python

  # Initialize a DataDownloader.
  report_downloader = client.GetDataDownloader(version='v202508')

  try:
    # Run the report and wait for it to finish.
    report_job_id = report_downloader.WaitForReport(report_job)
  except errors.AdManagerReportError as e:
    print('Failed to generate report. Error was: %s' % e)
    

PHP

      // Create report job and start it.
      $reportJob = new ReportJob();
      $reportJob->setReportQuery($reportQuery);
      $reportJob = $reportService->runReportJob($reportJob);
    

C#

// Run report job.
reportJob = reportService.runReportJob(reportJob);
    

Ruby

  # Create report job.
  report_job = {:report_query => report_query}

  # Run report job.
  report_job = report_service.run_report_job(report_job);
    

Bericht herunterladen

Nachdem Sie den Berichtauftrag gestartet haben, wird eine ID vom Server festgelegt. Verwenden ID mit dem ReportService.getReportJobStatus um den Status Ihres Berichts zu überprüfen. Sobald der Status ReportJobStatus.COMPLETED kann der Bericht heruntergeladen werden.

Einige unserer Clientbibliotheken verfügen über Hilfsdienstprogramme, die die API abfragen und bis der Bericht fertig ist. Wenn der Bericht fertig ist, können Sie Download-URL mit dem ReportService.getReportDownloadURL . Ein Bericht kann in verschiedenen Formaten heruntergeladen werden. Wenn Sie mit dem Bericht weiter verarbeiten kann, sollten Sie die Methode CSV_DUMP Format.

Java

    // Create report downloader.
    ReportDownloader reportDownloader = new ReportDownloader(reportService, reportJob.getId());

    // Wait for the report to be ready.
    if (reportDownloader.waitForReportReady()) {
      // Change to your file location.
      File file = File.createTempFile("delivery-report-", ".csv.gz");

      System.out.printf("Downloading report to %s ...", file.toString());

      // Download the report.
      ReportDownloadOptions options = new ReportDownloadOptions();
      options.setExportFormat(ExportFormat.CSV_DUMP);
      options.setUseGzipCompression(true);
      URL url = reportDownloader.getDownloadUrl(options);
      Resources.asByteSource(url).copyTo(Files.asByteSink(file));

      System.out.println("done.");
    } else {
      System.out.printf("Report job %d failed.%n", reportJob.getId());
    }
    

Python

  # Change to your preferred export format.
  export_format = 'CSV_DUMP'

  report_file = tempfile.NamedTemporaryFile(suffix='.csv.gz', delete=False)

  # Download report data.
  report_downloader.DownloadReportToFile(
      report_job_id, export_format, report_file)

  report_file.close()

  # Display results.
  print('Report job with id "%s" downloaded to:\n%s' % (
      report_job_id, report_file.name))
    

PHP

      // Create report downloader to poll report's status and download when
      // ready.
      $reportDownloader = new ReportDownloader(
          $reportService,
          $reportJob->getId()
      );
      if ($reportDownloader->waitForReportToFinish()) {
          // Write to system temp directory by default.
          $filePath = sprintf(
              '%s.csv.gz',
              tempnam(sys_get_temp_dir(), 'delivery-report-')
          );
          printf("Downloading report to %s ...%s", $filePath, PHP_EOL);
          // Download the report.
          $reportDownloader->downloadReport(
              ExportFormat::CSV_DUMP,
              $filePath
          );
          print "done.\n";
      } else {
          print "Report failed.\n";
      }
    

C#

ReportUtilities reportUtilities =
    new ReportUtilities(reportService, reportJob.id);

// Set download options.
ReportDownloadOptions options = new ReportDownloadOptions();
options.exportFormat = ExportFormat.CSV_DUMP;
options.useGzipCompression = true;
reportUtilities.reportDownloadOptions = options;

// Download the report.
using (ReportResponse reportResponse = reportUtilities.GetResponse())
{
    reportResponse.Save(filePath);
}

Console.WriteLine("Report saved to \"{0}\".", filePath);
    

Ruby

  MAX_RETRIES.times do |retry_count|
    # Get the report job status.
    report_job_status = report_service.get_report_job_status(report_job[:id])

    break unless report_job_status == 'IN_PROGRESS'
    puts 'Report with ID %d is still running.' % report_job[:id]
    sleep(RETRY_INTERVAL)
  end

  puts 'Report job with ID %d finished with status "%s".' % [report_job[:id],
      report_service.get_report_job_status(report_job[:id])]

  # Get the report URL.
  download_url = report_service.get_report_download_url(
      report_job_id, export_format
  )

  puts 'Downloading "%s" to "%s"...' % [download_url, file_name]
  open(file_name, 'wb') do |local_file|
    local_file << URI.open(download_url).read()
  end
    

Lesen der Berichtsdaten

Viele unserer Clientbibliotheken enthalten Dienstprogramme zum Lesen von Berichtsdaten. Dies ist sind nützlich, um die Berichtsdaten weiter zu verarbeiten oder Berichte zu kombinieren. aus verschiedenen Zeiträumen. Im Beispielcode wird davon ausgegangen, dass die Datei nicht komprimiert.

Java

  List<String[]> rows = CsvFiles.getCsvDataArray(filePath, true);
  for (String[] row : rows) {
    // Additional row processing
    processReportRow(row);
  }
    

Python

  with open(report_file.name, 'rb') as report:
    report_reader = csv.reader(report)
    for row in report_reader:
      # Additional row processing
      process_row(row)
    

PHP

  $report = fopen($filePath, 'r');
  while (!feof($report)) {
    // Additional row processing
    processRow(fgetcsv($report));
  }
  fclose($report);
    

C#

  CsvFile file = new CsvFile();
  file.Read(fileName, true);
  for (String[] row : file.Records) {
    // Additional row processing
    ProcessReportRow(row);
  }
    

Ruby

    CSV.foreach(file_name, converters: :numeric, headers: true) do |row|
      # Additional row processing
      process_row(row)
    end
    

Weitere Beispiele für die Berichterstellung finden Sie in unserem Kundenkonto Bibliotheken auf GitHub.

FAQ

Warum sind alle Berichtsergebnisse in meinem Testnetzwerk leer?

In Testnetzwerken werden keine Anzeigen ausgeliefert, daher enthalten Auslieferungsberichte keine Daten.

Warum sind alle Berichtsergebnisse in meinem Produktionsnetzwerk leer?

Der zu authentifizierende Nutzer hat möglicherweise keinen Zugriff auf Ihre Daten über die Sie einen Bericht erstellen möchten. Prüfen Sie, ob das Rollenberechtigungen und Teams richtig festgelegt sind.

Warum erhalte ich für meinen Bericht die Fehlermeldung ReportError.COLUMNS_NOT_SUPPORTED_FOR_REQUESTED_DIMENSIONS?

In Ad Manager werden nicht alle Kombinationen aus Spalten und Dimensionen unterstützt. Bei komplexen Berichten ist es unter Umständen einfacher, einen gültigen Bericht in der Benutzeroberfläche zu erstellen und dann mit der Funktion ReportService.getSavedQueriesByStatement

Warum wird mein gespeicherter Bericht in der API nicht zurückgegeben?

Vergewissern Sie sich, dass der Inhaber des Berichts den Bericht für den Nutzer freigegeben hat, den Sie sind Authentifizierung als

Warum ist mein gespeicherter Bericht nicht mit der API kompatibel?

Bestimmte Berichtsfunktionen sind in der API nicht verfügbar. Dazu gehören Spalten, Dimensionsattribute, Dimensionen und Zeitraumtypen. Für Zeitraumtypen nicht kompatibel sind, können Sie den Bericht mit einem unterstützten Typ speichern, machen sie abrufbar und dann „ReportQuery“ so, dass sie den gewünschten festen Zeitraum erfüllt.

Warum stimmen die Gesamtzahl der Klicks/Impressionen nicht mit meinem Bericht in der Benutzeroberfläche überein?

Lifetime-Impressionen gelten für die gesamte Laufzeit der Werbebuchung, Zeitraum des Berichts. Wird eine Werbebuchung noch ausgeliefert, zwischen der Erstellung zweier Berichte ändern.

Die Ausführung meiner Berichte dauert zu lange und es kommt gelegentlich zu einer Zeitüberschreitung. Was kann ich tun?

Wenn Sie den Zeitraum oder die Anzahl der Dimensionen verringern, können Sie die Leistung verbessern die Leistung. Erstellen Sie stattdessen mehrere Berichte für kürzere Zeiträume. Ich können die Berichtsdaten dann zusammengeführt werden, um den gewünschten Zeitraum abzudecken.

Was ist der Unterschied zwischen den Spalten „INVENTORY_LEVEL“ und „LINE_ITEM_LEVEL“? Was soll ich verwenden?

Spalten mit LINE_ITEM_LEVEL können nur auf Werbebuchungsebene verwendet werden in Ihrem Netzwerk aktiviert ist. Diese Spalten enthalten Daten aus den die dynamische Zuordnung auf Werbebuchungsebene zu AdSense oder Ad Exchange. Die Funktion Die Spalten „INVENTORY_LEVEL“ enthalten Daten aus der dynamischen Zuordnung auf Inventarebene. Weitere Informationen zur dynamischen Zuordnung finden Sie unter Ad Exchange-Werbebuchungen.

Wenn Sie immer noch unsicher sind, welche API-Spalten Sie verwenden sollen, erstellen Sie eine gespeicherte Abfrage im auf der Ad Manager-Benutzeroberfläche und rufen sie mit der Funktion ReportService.getSavedQueriesByStatement .