REST API를 찾고 계신가요? 이제 Ad Manager API (베타)를 사용할 수 있습니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

보고서 기본사항

소개

이 가이드에서는 API를 사용하여 보고서를 실행하고 다운로드하는 방법을 설명합니다. 여기에는 저장된 보고서 쿼리를 사용하여 임시 보고서 검색어를 만들 수 있습니다.

기본 요건

프로덕션 Google Ad Manager 네트워크에 액세스
Ad Manager 클라이언트 라이브러리

Primer

Ad Manager의 보고에 익숙하지 않은 경우 다음에 대한 새 보고서를 작성합니다. Ad Manager UI에서 보고서를 실행하는 방법에 대한 개요를 살펴봅니다 UI에는 열 및 측정기준 조합을 설명하는 도움말과 함께 는 지원됩니다. 복잡한 보고서 검색어를 만들 때는 먼저 UI에서 가져온 다음 API로 쿼리를 검색할 수 있습니다.

저장된 ReportQuery 검색

ReportQuery 객체에는 보고서의 모든 세부정보가 포함됩니다. 다음에서 보고서 검색어를 만들 수 있습니다. 새 Ad Manager UI를 사용하여 ReportService.getSavedQueriesByStatement 메서드를 사용하여 축소하도록 요청합니다. 저장된 쿼리 ID는 있습니다. 예를 들어 URL https://www.google.com/admanager/1234#reports/report/detail/report_id=456789 쿼리 ID는 456789입니다.

쿼리가 API 버전과 호환되지 않는 경우 SavedQuery.reportQuery null 및 SavedQuery.isCompatibleWithApiVersion false입니다.

호환되는 저장된 쿼리는 수정 여부와 관계없이 실행할 수 있습니다.

자바

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

GitHub에서 보기

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']

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

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;

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

GitHub에서 보기

쿼리를 실행하려면 ReportJob 만들기를 참조하세요.

ReportQuery 만들기

저장된 쿼리를 사용하는 것 외에 임시 ReportQuery를 만들 수도 있습니다. 이렇게 하려면 보고서의 측정기준 측정기준 속성, 열, 필터, 기간을 설정할 수 있습니다. 이 예는 단일 주문에 대한 기본 게재 보고서입니다.

자바

    // 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 만들기

ReportQuery가 있으면 보고서를 실행할 차례입니다. 이 ReportJob 객체 보고서의 상태를 유지하며, 보고서가 다운로드 준비가 되면 이를 알려줍니다. 받는사람 보고서를 실행하려면 ReportService.runReportJob 메서드를 사용하여 축소하도록 요청합니다.

자바

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

보고서 다운로드

보고서 작업을 시작하면 서버에서 설정한 ID가 생성됩니다. 사용 ID가 ReportService.getReportJobStatus 방법을 사용하여 보고서 상태를 확인하세요. 상태가 ReportJobStatus.COMPLETED 보고서를 다운로드할 준비가 되었습니다.

일부 클라이언트 라이브러리에는 API와 보고서가 완료될 때까지 기다립니다 보고서가 완료되면 다운로드 URL을 ReportService.getReportDownloadURL 메서드를 사용하여 축소하도록 요청합니다. 보고서는 다양한 형식으로 다운로드할 수 있습니다. 원하는 작업 추가 머신이 아닌 보고서에 추가할 수 있는 경우 CSV_DUMP 형식으로 입력합니다.

자바

    // 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

보고서 데이터 읽기

대부분의 클라이언트 라이브러리에는 보고서 데이터를 읽기 위한 유틸리티가 포함되어 있습니다. 이것은 보고서 데이터에 대한 추가 처리를 수행하거나 여러 보고서를 결합하는 데 유용합니다. 확인할 수 있습니다 예시 코드에서는 파일이 압축됩니다.

자바

  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

더 많은 보고서 예는 클라이언트 라이브러리를 참조하세요.

FAQ

테스트 네트워크의 보고서 결과가 모두 비어 있는 이유는 무엇인가요?

테스트 네트워크에서는 광고를 게재하지 않으므로 게재 보고서에 데이터가 없습니다.

프로덕션 네트워크의 모든 보고서 결과가 비어 있는 이유는 무엇인가요?

내가 인증하는 사용자는 내 데이터에 대한 액세스 권한이 없을 수 있습니다. 있습니다. 사이트의 역할 권한 및 팀이 올바르게 설정되었는지 확인하세요.

보고서에 ReportError.COLUMNS_NOT_SUPPORTED_FOR_REQUESTED_DIMENSIONS 오류가 표시되는 이유는 무엇인가요?

Ad Manager에서는 일부 열 및 측정기준 조합이 지원되지 않습니다. 복잡한 보고서의 경우 UI에서 유효한 보고서를 만든 다음 다음 명령어로 ReportService.getSavedQueriesByStatement 메서드를 사용하세요.

저장된 보고서가 API에서 반환되지 않는 이유는 무엇인가요?

보고서 소유자가 보고서를 현재 사용자와 공유했는지 확인합니다. 있습니다

저장된 보고서가 API와 호환되지 않는 이유는 무엇인가요?

특정 보고 기능은 API에서 사용할 수 없습니다. 여기에는 열, 측정기준 속성, 측정기준, 기간 유형이 포함됩니다. 호환되지 않는 기간 유형의 경우 지원되는 유형으로 보고서를 저장하여 검색할 수 있도록 한 다음 원하는 고정 기간에 맞게 ReportQuery를 변경할 수 있습니다.

전체 기간 클릭수/노출수가 UI의 보고서와 일치하지 않는 이유는 무엇인가요?

전체 기간 노출수는 확인할 수 있습니다. 광고 항목이 아직 게재 중인 경우 값은 변경할 수 있습니다

보고서가 너무 오래 걸리고 때때로 타임아웃됩니다. 어떻게 해야 하나요?

기간이나 측정기준의 수를 줄이면 실적 개선에 도움이 됩니다. 확인할 수 있습니다 대신 더 짧은 기간에 대해 여러 보고서를 실행해 보세요. 나 원하는 기간을 포함하도록 보고서 데이터를 병합할 수 있습니다.

INVENTORY_LEVEL 열과 LINE_ITEM_LEVEL 열의 차이점은 무엇인가요? 어떤 옵션을 사용해야 하나요?

LINE_ITEM_LEVEL 열이 있는 열은 광고 항목 수준이 있는 경우에만 사용할 수 있습니다. 동적 할당이 사용 설정되어 있어야 합니다. 이 열에는 광고 항목 수준 동적 할당을 애드센스 또는 Ad Exchange에 할당할 수 있습니다. 마찬가지로 INVENTORY_LEVEL개 열에 인벤토리 수준 동적 할당의 데이터가 포함됩니다. 동적 할당에 대해 자세히 알아보려면 다음을 참조하세요. Ad Exchange 광고 항목

어떤 API 열을 사용해야 할지 잘 모르겠다면 Ad Manager UI를 사용하여 ReportService.getSavedQueriesByStatement 메서드를 사용하여 축소하도록 요청합니다.

보고서 기본사항 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

소개

기본 요건

Primer

저장된 ReportQuery 검색

자바

Python

PHP

C#

Ruby

ReportQuery 만들기

자바

Python

PHP

C#

Ruby

ReportJob 만들기

자바

Python

PHP

C#

Ruby

보고서 다운로드

자바

Python

PHP

C#

Ruby

보고서 데이터 읽기

자바

Python

PHP

C#

Ruby

FAQ

보고서 기본사항