ReportDownloader Utilities

Overview

The client library includes ReportDownloader utilities for AdWords API and Ad Manager API. This page describes the options each utility offers for processing report results.

For examples of how to construct and issue report requests, see the following folders:

• AdWords API: examples/AdWords/v201809/Reporting
• Ad Manager API: examples/AdManager/v201905/ReportService

Key objects

ReportDownloader

• Provides methods for downloading reports in a given format. For AdWords API, you can use either AWQL (downloadReportWithAwql) or selector (downloadReport).
• Results are instances of ReportDownloadResult for AdWords API and StreamInterface for Ad Manager API.
• An implementation exists for each API version: Google\AdsApi\AdWords\Reporting\API_VERSION\ReportDownloader and Google\AdsApi\AdManager\Util\API_VERSION\ReportDownloader.

ReportDownloadResult (AdWords API only)

• Stores the downloaded result for a given report definition.

Download report contents as a string

Use the approach below to download the full report contents as a string. You will hold the entire contents of the report in memory, so this is not the best option for large reports. Instead, consider downloading to a file or processing the report contents as a stream.

AdWords API

$reportDownloadResult = $reportDownloader->downloadReportWithAwql(
    $reportQuery,
    $reportFormat,
    $reportSettingsOverride
);
$reportContents = $reportDownloadResult->getAsString();

Ad Manager API

$reportDownloader = new ReportDownloader($reportService, $reportJobId);
if ($reportDownloader->waitForReportToFinish()) {
    $stream = $reportDownloader->downloadReport(ExportFormat::CSV_DUMP, null);
}
$reportContents = $stream->getContents();

Process the report contents as a stream

Use the approach below to process report contents as a Guzzle stream. This is useful if the report output is extremely large (based on your computer's memory and development environment) and you do not want to hold the entire contents in memory.

The examples show how to convert the report output into a guzzle stream.

AdWords API

$reportDownloadResult = $reportDownloader->downloadReportWithAwql(
    $reportQuery,
    $reportFormat,
    $reportSettingsOverride
);
$stream = $reportDownloadResult->getStream();

Ad Manager API

$reportDownloader = new ReportDownloader($reportService, $reportJobId);
if ($reportDownloader->waitForReportToFinish()) {
    $stream = $reportDownloader->downloadReport(ExportFormat::CSV_DUMP, null);
}

Download report contents to a file

Use the approach below to download report contents to a file.

AdWords API

$reportDownloadResult = $reportDownloader->downloadReportWithAwql(
    $reportQuery,
    $reportFormat,
    $reportSettingsOverride
);
$filePath = sprintf(
    '%s.csv',
    tempnam(sys_get_temp_dir(), 'criteria-report-')
);
$reportDownloadResult->saveToFile($filePath);

Ad Manager API

$reportDownloader = new ReportDownloader($reportService, $reportJobId);
if ($reportDownloader->waitForReportToFinish()) {
    $filePath = sprintf(
        '%s.csv.gz',
        tempnam(sys_get_temp_dir(), 'inventory-report-')
    );
    $reportDownloader->downloadReport(ExportFormat::CSV_DUMP, $filePath);
}