Downloads a new instance of an existing report definition. If the path
parameter is specified it will be downloaded to the file at that path,
otherwise it will be downloaded to memory and be returned as a string.
| public DownloadReport ( mixed $reportDefinition, string $path = null, AdWordsUser $user, array $options = null ) : mixed | ||
| $reportDefinition | mixed | the ReportDefinition to download or the id of a stored report definition |
| $path | string | an optional path of the file to download the report to |
| $user | AdWordsUser | the user that created the ReportDefinition |
| $options | array | the option to use when downloading the report: {boolean} skipReportHeader: if report responses should skip the header row containing the report name and date range {boolean} skipColumnHeader: if report responses should skip the header row containing column names {boolean} skipReportSummary: if report responses should skip the summary row containing totals {boolean} includeZeroImpressions: if report responses should include zero impression rows {boolean} useRawEnumValues: if report responses should return enum values instead of enum display values {string} server: the server to make the request to. If null, then the default server will be used {string} version: the version to make the request against. If null, then the default version will be used |
| return | mixed | if path isn't specified the contents of the report, otherwise the size in bytes of the downloaded report |
/**
* Runs the example.
* @param AdWordsUser $user the user to run the example with
* @param string $filePath the path of the file to download the report to
*/
function DownloadCriteriaReportExample(AdWordsUser $user, $filePath)
{
// Load the service, so that the required classes are available.
$user->LoadService('ReportDefinitionService', ADWORDS_VERSION);
// Create selector.
$selector = new Selector();
$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'Impressions', 'Clicks', 'Cost');
// Optional: use predicate to filter out paused criteria.
$selector->predicates[] = new Predicate('Status', 'NOT_IN', array('PAUSED'));
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->selector = $selector;
$reportDefinition->reportName = 'Criteria performance report #' . uniqid();
$reportDefinition->dateRangeType = 'LAST_7_DAYS';
$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
$reportDefinition->downloadFormat = 'CSV';
// Exclude criteria that haven't recieved any impressions over the date range.
$reportDefinition->includeZeroImpressions = false;
// Set additional options.
$options = array('version' => ADWORDS_VERSION);
// Optional: Set skipReportHeader, skipColumnHeader, skipReportSummary to
// suppress headers or summary rows.
// $options['skipReportHeader'] = true;
// $options['skipColumnHeader'] = true;
// $options['skipReportSummary'] = true;
// Optional: Set includeZeroImpressions to include zero impression rows in
// the report output.
// $options['includeZeroImpressions'] = true;
// Download report.
ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
printf("Report with name '%s' was downloaded to '%s'.\n", $reportDefinition->reportName, $filePath);
}
/**
* @param [Array] $definition
* $definition['reportType']
* $definition['periode']
* $definition['fields']
* $definition['predicates']
*/
public function createReport(array $definition)
{
$filePath = dirname(__FILE__) . $this->tempDirPath . uniqid() . 'report.csv';
$this->AdWordsUser->LoadService('ReportDefinitionService', ADWORDS_VERSION);
// Create selector.
$selector = new \Selector();
$selector->fields = $definition['fields'];
$selector->dateRange = new \DateRange((new \DateTime($definition['periode']['start']))->format('Ymd'), (new \DateTime($definition['periode']['end']))->format('Ymd'));
// predicates
if (isset($definition['predicates']) && count($definition['predicates']) > 0) {
foreach ($definition['predicates'] as $predicate) {
$selector->predicates[] = new \Predicate($predicate['field'], $predicate['condition'], $predicate['value']);
}
}
// Create report definition.
$reportDefinition = new \ReportDefinition();
$reportDefinition->selector = $selector;
$reportDefinition->reportName = 'Custom Report';
$reportDefinition->dateRangeType = 'CUSTOM_DATE';
$reportDefinition->reportType = $definition['reportType'];
$reportDefinition->downloadFormat = 'CSV';
$options = array('version' => ADWORDS_VERSION, 'includeZeroImpressions' => false);
// Download report.
try {
$reportUtils = new \ReportUtils();
$report = $reportUtils->DownloadReport($reportDefinition, $filePath, $this->AdWordsUser, $options);
$this->result = $this->parseAccountReport($filePath);
$this->result = $this->convertMicroMoney($definition['fields'], $this->result);
} catch (\Exception $e) {
printf("An error has occurred: %s\n", $e->getMessage());
}
unlink($filePath);
}
/**
* Runs the example.
* @param AdWordsUser $user the user to run the example with
* @param string $reportDefinitionId the ID of the report definition to download
* @param string $filePath the path of the file to download the report to
*/
function DownloadDefinedReportExample(AdWordsUser $user, $reportDefinitionId, $filePath)
{
// Set options.
$options = array('version' => 'v201109', 'returnMoneyInMicros' => TRUE);
// Download report.
ReportUtils::DownloadReport($reportDefinitionId, $filePath, $user, $options);
printf("Report with definition id '%s' was downloaded to '%s'.\n", $reportDefinitionId, $filePath);
}
/**
* Runs the example.
* @param AdWordsUser $user the user to run the example with
* @param string $filePath the path of the file to download the report to
*/
function DownloadCriteriaReportExample(AdWordsUser $user, $filePath)
{
// Load the service, so that the required classes are available.
$user->LoadService('ReportDefinitionService', ADWORDS_VERSION);
// Optional: Set clientCustomerId to get reports of your child accounts
// $user->SetClientCustomerId('INSERT_CLIENT_CUSTOMER_ID_HERE');
// Create selector.
$selector = new Selector();
$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'Impressions', 'Clicks', 'Cost');
// Optional: use predicate to filter out paused criteria.
$selector->predicates[] = new Predicate('Status', 'NOT_IN', array('PAUSED'));
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->selector = $selector;
$reportDefinition->reportName = 'Criteria performance report #' . uniqid();
$reportDefinition->dateRangeType = 'LAST_7_DAYS';
$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
$reportDefinition->downloadFormat = 'CSV';
// Set additional options.
$options = array('version' => ADWORDS_VERSION);
// Optional: Set skipReportHeader, skipColumnHeader, skipReportSummary to
// suppress headers or summary rows.
// $options['skipReportHeader'] = true;
// $options['skipColumnHeader'] = true;
// $options['skipReportSummary'] = true;
//
// Optional: Set useRawEnumValues to return enum values instead of enum
// display values.
// $options['useRawEnumValues'] = true;
//
// Optional: Set includeZeroImpressions to include zero impression rows in
// the report output.
// $options['includeZeroImpressions'] = true;
// Download report.
$reportUtils = new ReportUtils();
$reportUtils->DownloadReport($reportDefinition, $filePath, $user, $options);
printf("Report with name '%s' was downloaded to '%s'.\n", $reportDefinition->reportName, $filePath);
}
/**
* @param $clientId
* @param \ReportDefinition $reportDefinition
* @param $path
* @param array $options
* @return null|string|void
*/
public function downloadReport($clientId, \ReportDefinition $reportDefinition, $format, $path = null, array $options = null)
{
$allowformats = array("CSV", "XML", "TSV", "GZIPPED_CSV", "GZIPPED_XML");
if (!in_array($format, $allowformats)) {
return;
}
if (!$this->validateUser()) {
return;
}
$this->setAdwordsId($clientId);
$reportDefinition->downloadFormat = $format;
$report = null;
try {
$report = \ReportUtils::DownloadReport($reportDefinition, $path, $this->adwordsuser, $options);
if ("GZIPPED_CSV" == $format || "GZIPPED_XML" == $format) {
$report = gzdecode($report);
}
} catch (\Exception $e) {
$this->lastexception = $e;
return;
}
return $report;
}
/**
* Runs the example.
* @param AdWordsUser $user the user to run the example with
* @param string $filePath the path of the file to download the report to
*/
function DownloadCriteriaReportExample(AdWordsUser $user, $filePath)
{
// Load the service, so that the required classes are available.
$user->LoadService('ReportDefinitionService', ADWORDS_VERSION);
// Create selector.
$selector = new Selector();
$selector->fields = array('CampaignId', 'AdGroupId', 'Id', 'Criteria', 'CriteriaType', 'Impressions', 'Clicks', 'Cost');
// Filter out deleted criteria.
$selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DELETED'));
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->selector = $selector;
$reportDefinition->reportName = 'Criteria performance report #' . uniqid();
$reportDefinition->dateRangeType = 'LAST_7_DAYS';
$reportDefinition->reportType = 'CRITERIA_PERFORMANCE_REPORT';
$reportDefinition->downloadFormat = 'CSV';
// Exclude criteria that haven't recieved any impressions over the date range.
$reportDefinition->includeZeroImpressions = FALSE;
// Set additional options.
$options = array('version' => ADWORDS_VERSION, 'returnMoneyInMicros' => TRUE);
// Download report.
ReportUtils::DownloadReport($reportDefinition, $filePath, $user, $options);
printf("Report with name '%s' was downloaded to '%s'.\n", $reportDefinition->reportName, $filePath);
}
$path = dirname(__FILE__) . '/../../../../src';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
require_once 'Google/Api/Ads/Dfp/Lib/DfpUser.php';
require_once dirname(__FILE__) . '/../../../Common/ExampleUtils.php';
require_once 'Google/Api/Ads/Dfp/Util/ReportUtils.php';
try {
// Get DfpUser from credentials in "../auth.ini"
// relative to the DfpUser.php file's directory.
$user = new DfpUser();
// Log SOAP XML request and response.
$user->LogDefaults();
// Get the ReportService.
$reportService = $user->GetService('ReportService', 'v201208');
// Set the ID of the completed report.
$reportJobId = 'INSERT_REPORT_JOB_ID_HERE';
// Set the format of the report. Ex: CSV_DUMP
$exportFormat = 'INSERT_EXPORT_FORMAT_HERE';
// Set the file name to download the gzipped report to. Ex: report.csv.gz.
$fileName = 'INSERT_FILE_NAME_HERE' . '.gz';
$filePath = dirname(__FILE__) . '/' . $fileName;
$downloadUrl = $reportService->getReportDownloadURL($reportJobId, $exportFormat);
printf("Downloading report from URL '%s'.\n", $downloadUrl);
ReportUtils::DownloadReport($downloadUrl, $filePath);
printf("Report downloaded to file '%s'.\n", $filePath);
} catch (OAuth2Exception $e) {
ExampleUtils::CheckForOAuth2Errors($e);
} catch (ValidationException $e) {
ExampleUtils::CheckForOAuth2Errors($e);
} catch (Exception $e) {
print $e->getMessage() . "\n";
}
/**
* Test downloading a report to a string. A dummy URL is used in place of a
* report URL.
* @covers ReportUtils::DownloadReport
*/
public function testDownloadReportToString()
{
$result = ReportUtils::DownloadReport(ReportUtilsTest::DUMMY_REPORT_URL);
$this->assertTrue(isset($result));
}
$path = dirname(__FILE__) . '/../../../../src';
set_include_path(get_include_path() . PATH_SEPARATOR . $path);
require_once 'Google/Api/Ads/Dfp/Lib/DfpUser.php';
require_once dirname(__FILE__) . '/../../../Common/ExampleUtils.php';
require_once 'Google/Api/Ads/Dfp/Util/ReportUtils.php';
try {
// Get DfpUser from credentials in "../auth.ini"
// relative to the DfpUser.php file's directory.
$user = new DfpUser();
// Log SOAP XML request and response.
$user->LogDefaults();
// Get the ReportService.
$reportService = $user->GetService('ReportService', 'v201311');
// Set the ID of the completed report.
$reportJobId = 'INSERT_REPORT_JOB_ID_HERE';
// Set the format of the report (e.g., CSV_DUMP) and download without
// compression so we can print it.
$reportDownloadOptions = new ReportDownloadOptions();
$reportDownloadOptions->exportFormat = 'INSERT_EXPORT_FORMAT_HERE';
$reportDownloadOptions->useGzipCompression = false;
$downloadUrl = $reportService->getReportDownloadUrlWithOptions($reportJobId, $reportDownloadOptions);
printf("Downloading report from URL '%s'.\n", $downloadUrl);
$report = ReportUtils::DownloadReport($downloadUrl);
printf("\n%s\n", $report);
} catch (OAuth2Exception $e) {
ExampleUtils::CheckForOAuth2Errors($e);
} catch (ValidationException $e) {
ExampleUtils::CheckForOAuth2Errors($e);
} catch (Exception $e) {
printf("%s\n", $e->getMessage());
}
/**
* Runs the example.
* @param AdWordsUser $user the user to run the example with
*/
function ParallelReportDownloadExample(AdWordsUser $user)
{
// Load the service, so that the required classes are available.
$user->LoadService('ReportDefinitionService', ADWORDS_VERSION);
// Create selector.
$selector = new Selector();
$selector->fields = array('CampaignId', 'AdGroupId', 'Impressions', 'Clicks', 'Cost');
// Create report definition.
$reportDefinition = new ReportDefinition();
$reportDefinition->selector = $selector;
$reportDefinition->reportName = 'Custom ADGROUP_PERFORMANCE_REPORT';
$reportDefinition->dateRangeType = 'LAST_7_DAYS';
$reportDefinition->reportType = 'ADGROUP_PERFORMANCE_REPORT';
$reportDefinition->downloadFormat = 'CSV';
// Set additional options.
$options = array('version' => ADWORDS_VERSION);
// Optional: Set skipReportHeader, skipColumnHeader, skipReportSummary to
// suppress headers or summary rows.
// $options['skipReportHeader'] = true;
// $options['skipColumnHeader'] = true;
// $options['skipReportSummary'] = true;
//
// Optional: Set useRawEnumValues to return enum values instead of enum
// display values.
// $options['useRawEnumValues'] = true;
//
// Optional: Set includeZeroImpressions to include zero impression rows in
// the report output.
// $options['includeZeroImpressions'] = true;
$customerIds = getAllManagedCustomerIds($user);
printf("Downloading reports for %d managed customers.\n", count($customerIds));
$successfulReports = array();
$failedReports = array();
$reportDir = sys_get_temp_dir();
$reportUtils = new ReportUtils();
foreach ($customerIds as $customerId) {
$filePath = sprintf('%s.csv', tempnam($reportDir, 'adgroup_'));
$user->SetClientCustomerId($customerId);
$retryCount = 0;
$doContinue = true;
do {
$retryCount++;
try {
$reportUtils->DownloadReport($reportDefinition, $filePath, $user, $options);
printf("Report for client customer ID %d successfully downloaded to: %s\n", $customerId, $filePath);
$successfulReports[$customerId] = $filePath;
$doContinue = false;
} catch (ReportDownloadException $e) {
printf("Report attempt #%d for client customer ID %d was not downloaded" . " due to: %s\n", $retryCount, $customerId, $e->getMessage());
if ($e->GetHttpCode() >= 500 && $retryCount < MAX_RETRIES) {
$sleepTime = $retryCount * BACKOFF_FACTOR;
printf("Sleeping %d seconds before retrying report for client customer " . "ID %d.\n", $sleepTime, $customerId);
sleep($sleepTime);
} else {
printf("Report request failed for client customer ID %d.\n", $customerId);
$failedReports[$customerId] = $filePath;
$doContinue = false;
}
}
} while ($doContinue === true);
}
print "All downloads completed. Results:\n";
print "Successful reports:\n";
foreach ($successfulReports as $customerId => $filePath) {
printf("\tClient ID %d => '%s'\n", $customerId, $filePath);
}
print "Failed reports:\n";
foreach ($failedReports as $customerId => $filePath) {
printf("\tClient ID %d => '%s'\n", $customerId, $filePath);
}
print "End of results.\n";
}
