Principes de base sur la création de rapports

Introduction

Ce guide vous explique comment générer et télécharger un rapport à l'aide de l'API. Il aborde à la fois à l'aide d'une requête de rapport enregistré existante, puis en créant une requête de rapport ad hoc.

Remarque :Pour en savoir plus sur la collecte des données de rapport Ad Manager, consultez Comptabilisation des impressions et des clics et le respect des règles de l'IAB.

Prérequis

• Accès à un réseau de production Google Ad Manager
• d'une bibliothèque cliente Ad Manager.

Primer

Si vous ne savez pas comment créer des rapports dans Ad Manager, consultez Créez un rapport pour une sur l'exécution d'un rapport dans l'interface utilisateur d'Ad Manager. L'interface utilisateur propose un aperçu et des info-bulles indiquant les combinaisons de colonnes et de dimensions sont pris en charge. Lorsque vous créez une requête de rapport complexe, il peut être plus simple dans l'interface utilisateur, avant de récupérer la requête avec l'API.

Récupérer une ReportQuery enregistrée

La classe ReportQuery contient tous les détails du rapport. Vous pouvez créer des requêtes de rapport dans dans l'interface utilisateur d'Ad Manager, puis récupérez-les à l'aide de la ReportService.getSavedQueriesByStatement . L'ID de requête enregistré est inclus dans l'URL lors de l'affichage d'une requête dans la UI. Par exemple, dans l'URL https://www.google.com/admanager/1234#reports/report/detail/report_id=456789, l'ID de requête est 456789.

Si une requête n'est pas compatible avec la version de votre API, SavedQuery.reportQuery sera null et SavedQuery.isCompatibleWithApiVersion sera false.

Les requêtes enregistrées compatibles peuvent être exécutées avec ou sans modification.

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

Afficher sur GitHub

Python

  statement = (ad_manager.StatementBuilder(version='v202408')
               .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']
    

Afficher sur GitHub

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

Afficher sur GitHub

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;
    

Afficher sur GitHub

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
    

Afficher sur GitHub

Pour exécuter la requête, voir Création du ReportJob.

Créer une ReportQuery

En plus d'utiliser des requêtes enregistrées, vous pouvez également créer un objet ReportQuery ad hoc. Pour ce faire, vous devez définir dimensions dimension Attributs, colonnes, filtrer et la plage de dates. Cet exemple concerne un rapport de diffusion de base sur une seule commande.

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='v202408')
               .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()
  }
    

Créer le ReportJob

Une fois que vous avez une ReportQuery, vous pouvez exécuter le rapport. L'objet ReportJob contient l'état d'un rapport et vous indique quand il est prêt à être téléchargé. À commencez à générer votre rapport, utilisez la 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='v202408')

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

Télécharger le rapport

Une fois la tâche de création de rapports démarrée, un ID est défini par le serveur. Utiliser ceci associé au ReportService.getReportJobStatus pour vérifier l'état de votre signalement. Une fois que l'état est ReportJobStatus.COMPLETED le rapport est prêt à être téléchargé.

Certaines de nos bibliothèques clientes ont des utilitaires d'aide qui interrogent l'API et attendez la fin du rapport. Une fois le rapport terminé, vous pouvez obtenir l'URL de téléchargement avec le ReportService.getReportDownloadURL . Un rapport peut être téléchargé dans différents formats. Si vous souhaitez un traitement plus poussé, vous devez utiliser CSV_DUMP .

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 << open(download_url).read()
  end
    

Lecture des données du rapport

Bon nombre de nos bibliothèques clientes incluent des utilitaires permettant de lire les données des rapports. C'est utiles pour effectuer un traitement supplémentaire sur les données des rapports ou pour combiner des rapports ; provenant de différentes plages de dates. Notez que l'exemple de code suppose que le fichier n'est pas compressée.

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
    

Pour d'autres exemples de rapports, consultez notre Centre d'aide bibliothèques sur GitHub.

Questions fréquentes

Pourquoi tous les résultats du rapport sur mon réseau de test sont-ils vides ?

Les réseaux de test ne diffusent pas d'annonces. Les rapports sur la diffusion ne contiennent donc aucune donnée.

Pourquoi tous les résultats de rapport sur mon réseau de production sont-ils vides ?

L'utilisateur dont vous vous authentifiez n'a peut-être pas accès aux données sur lesquelles vous essayez de créer un rapport. Vérifiez que leurs autorisations de rôle équipes sont correctement configurées.

Pourquoi l'erreur ReportError.COLUMNS_NOT_SUPPORTED_FOR_REQUESTED_DIMENSIONS s'affiche-t-elle pour mon rapport ?

Toutes les combinaisons de colonnes et de dimensions ne sont pas compatibles avec Ad Manager. Pour les rapports complexes, il peut être plus simple de créer un rapport valide dans l'interface utilisateur, à l'aide de la commande ReportService.getSavedQueriesByStatement .

Pourquoi mon rapport enregistré n'est-il pas renvoyé dans l'API ?

Assurez-vous que le propriétaire du rapport l'a partagé avec l'utilisateur que vous s'authentifier en tant que.

Pourquoi mon rapport enregistré n'est-il pas compatible avec l'API ?

Certaines fonctionnalités de reporting ne sont pas disponibles dans l'API. Cela inclut les colonnes, les attributs de dimension, les dimensions et les types de plages de dates. Pour types de plages de dates incompatibles, vous pouvez enregistrer le rapport en choisissant un type compatible rendez-le récupérable, puis modifiez ReportQuery pour respecter la plage de dates fixe souhaitée.

Pourquoi le nombre total de clics/impressions ne correspond-il pas à celui indiqué dans le rapport de l'interface utilisateur ?

Les impressions permanentes s'appliquent à toute la durée de vie de l'élément de campagne, quelle que soit la plage de dates du rapport. Si un élément de campagne est toujours diffusé, la valeur changera probablement entre deux rapports.

Mes rapports prennent trop de temps et arrivent parfois à expiration. Que puis-je faire ?

Diminuez la plage de dates ou le nombre de dimensions pour améliorer des performances. Essayez plutôt de générer plusieurs rapports sur des périodes plus courtes. Vous pouvez ensuite fusionner les données du rapport pour couvrir la période souhaitée.

Quelle est la différence entre les colonnes INVENTORY_LEVEL et LINE_ITEM_LEVEL ? Que dois-je utiliser ?

Les colonnes avec LINE_ITEM_LEVEL ne peuvent être utilisées que si vous avez défini un élément de campagne au niveau de l'élément de campagne. l'allocation dynamique doit être activée sur votre réseau. Ces colonnes incluent les données l'allocation dynamique au niveau de l'élément de campagne vers AdSense ou Ad Exchange. De même, Les colonnes INVENTORY_LEVEL incluent les données de l'allocation dynamique au niveau de l'inventaire. Pour en savoir plus sur l'allocation dynamique, consultez Éléments de campagne Ad Exchange.

Si vous ne savez toujours pas quelles colonnes d'API utiliser, créez une requête enregistrée dans le dans l'interface utilisateur d'Ad Manager, puis récupérez-la à l'aide de ReportService.getSavedQueriesByStatement .