Share your feedback about the AdWords API! Take our annual survey.

Reporting Samples

The code samples below provide examples of common reporting functions using the AdWords API. Client Library.

Download a criteria performance report with AWQL

<?php
/**
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\AdsApi\Examples\AdWords\v201809\Reporting;

require __DIR__ . '/../../../../vendor/autoload.php';

use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Query\v201809\ReportQueryBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\Common\OAuth2TokenBuilder;

/**
 * Downloads CRITERIA_PERFORMANCE_REPORT for the specified client customer ID.
 */
class DownloadCriteriaReportWithAwql
{

    public static function runExample(AdWordsSession $session, $reportFormat)
    {
        // Create report query to get the data for last 7 days.
        $query = (new ReportQueryBuilder())
            ->select([
                'CampaignId',
                'AdGroupId',
                'Id',
                'Criteria',
                'CriteriaType',
                'Impressions',
                'Clicks',
                'Cost'
            ])
            ->from(ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT)
            ->where('Status')->in(['ENABLED', 'PAUSED'])
            ->duringDateRange(ReportDefinitionDateRangeType::LAST_7_DAYS)
            ->build();

        // Download report as a string.
        $reportDownloader = new ReportDownloader($session);
        // Optional: If you need to adjust report settings just for this one
        // request, you can create and supply the settings override here.
        // Otherwise, default values from the configuration
        // file (adsapi_php.ini) are used.
        $reportSettingsOverride = (new ReportSettingsBuilder())
            ->includeZeroImpressions(false)
            ->build();
        $reportDownloadResult = $reportDownloader->downloadReportWithAwql(
            sprintf('%s', $query),
            $reportFormat,
            $reportSettingsOverride
        );
        print "Report was downloaded and printed below:\n";
        print $reportDownloadResult->getAsString();
    }

    public static function main()
    {
        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // See: AdWordsSessionBuilder for setting a client customer ID that is
        // different from that specified in your adsapi_php.ini file.
        // Construct an API session configured from a properties file and the
        // OAuth2 credentials above.
        $session = (new AdWordsSessionBuilder())
            ->fromFile()
            ->withOAuth2Credential($oAuth2Credential)
            ->build();

        self::runExample($session, DownloadFormat::CSV);
    }
}

DownloadCriteriaReportWithAwql::main();

Download a criteria performance report using selectors

<?php
/**
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\AdsApi\Examples\AdWords\v201809\Reporting;

require __DIR__ . '/../../../../vendor/autoload.php';

use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinition;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\Predicate;
use Google\AdsApi\AdWords\v201809\cm\PredicateOperator;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\Common\OAuth2TokenBuilder;

/**
 * Downloads CRITERIA_PERFORMANCE_REPORT for the specified client customer ID.
 */
class DownloadCriteriaReportWithSelector
{

    public static function runExample(AdWordsSession $session, $filePath)
    {
        // Create selector.
        $selector = new Selector();
        $selector->setFields(
            [
                'CampaignId',
                'AdGroupId',
                'Id',
                'Criteria',
                'CriteriaType',
                'Impressions',
                'Clicks',
                'Cost'
            ]
        );

        // Use a predicate to filter out paused criteria (this is optional).
        $selector->setPredicates(
            [
                new Predicate('Status', PredicateOperator::NOT_IN, ['PAUSED'])
            ]
        );

        // Create report definition.
        $reportDefinition = new ReportDefinition();
        $reportDefinition->setSelector($selector);
        $reportDefinition->setReportName(
            'Criteria performance report #' . uniqid()
        );
        $reportDefinition->setDateRangeType(
            ReportDefinitionDateRangeType::LAST_7_DAYS
        );
        $reportDefinition->setReportType(
            ReportDefinitionReportType::CRITERIA_PERFORMANCE_REPORT
        );
        $reportDefinition->setDownloadFormat(DownloadFormat::CSV);

        // Download report.
        $reportDownloader = new ReportDownloader($session);
        // Optional: If you need to adjust report settings just for this one
        // request, you can create and supply the settings override here. Otherwise,
        // default values from the configuration file (adsapi_php.ini) are used.
        $reportSettingsOverride = (new ReportSettingsBuilder())->includeZeroImpressions(false)->build();
        $reportDownloadResult = $reportDownloader->downloadReport(
            $reportDefinition,
            $reportSettingsOverride
        );
        $reportDownloadResult->saveToFile($filePath);
        printf(
            "Report with name '%s' was downloaded to '%s'.\n",
            $reportDefinition->getReportName(),
            $filePath
        );
    }

    public static function main()
    {
        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // See: AdWordsSessionBuilder for setting a client customer ID that is
        // different from that specified in your adsapi_php.ini file.
        // Construct an API session configured from a properties file and the
        // OAuth2 credentials above.
        $session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();

        $filePath = sprintf(
            '%s.csv',
            tempnam(sys_get_temp_dir(), 'criteria-report-')
        );
        self::runExample($session, $filePath);
    }
}

DownloadCriteriaReportWithSelector::main();

Get the report fields from a report

<?php
/**
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\AdsApi\Examples\AdWords\v201809\Reporting;

require __DIR__ . '/../../../../vendor/autoload.php';

use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionService;
use Google\AdsApi\Common\OAuth2TokenBuilder;

/**
 * This example gets the fields available in a campaign report.
 */
class GetReportFields
{

    const PAGE_LIMIT = 500;

    public static function runExample(
        AdWordsServices $adWordsServices,
        AdWordsSession $session
    ) {
        $reportDefinitionService = $adWordsServices->get($session, ReportDefinitionService::class);

        // The type of the report to get fields for.
        $reportType = ReportDefinitionReportType::CAMPAIGN_PERFORMANCE_REPORT;

        // Get report fields of the report type.
        $reportDefinitionFields = $reportDefinitionService->getReportFields($reportType);

        printf(
            "The report type '%s' contains the following fields:\n",
            $reportType
        );
        foreach ($reportDefinitionFields as $reportDefinitionField) {
            printf(
                '  %s (%s)',
                $reportDefinitionField->getFieldName(),
                $reportDefinitionField->getFieldType()
            );
            if ($reportDefinitionField->getEnumValues() !== null) {
                printf(
                    ' := [%s]',
                    implode(', ', $reportDefinitionField->getEnumValues())
                );
            }
            print "\n";
        }
    }

    public static function main()
    {
        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // Construct an API session configured from a properties file and the
        // OAuth2 credentials above.
        $session = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential)->build();
        self::runExample(new AdWordsServices(), $session);
    }
}

GetReportFields::main();

Download a report for multiple accounts

<?php
/**
 * Copyright 2017 Google Inc. All Rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

namespace Google\AdsApi\Examples\AdWords\v201809\Reporting;

require __DIR__ . '/../../../../vendor/autoload.php';

use Google\AdsApi\AdWords\AdWordsServices;
use Google\AdsApi\AdWords\AdWordsSession;
use Google\AdsApi\AdWords\AdWordsSessionBuilder;
use Google\AdsApi\AdWords\Reporting\v201809\DownloadFormat;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinition;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDefinitionDateRangeType;
use Google\AdsApi\AdWords\Reporting\v201809\ReportDownloader;
use Google\AdsApi\AdWords\ReportSettingsBuilder;
use Google\AdsApi\AdWords\v201809\cm\ApiException;
use Google\AdsApi\AdWords\v201809\cm\Paging;
use Google\AdsApi\AdWords\v201809\cm\Predicate;
use Google\AdsApi\AdWords\v201809\cm\PredicateOperator;
use Google\AdsApi\AdWords\v201809\cm\ReportDefinitionReportType;
use Google\AdsApi\AdWords\v201809\cm\Selector;
use Google\AdsApi\AdWords\v201809\mcm\ManagedCustomerService;
use Google\AdsApi\Common\OAuth2TokenBuilder;

/**
 * This example gets and downloads an Ad Hoc report from an XML report
 * definition for all accounts directly under a manager account.
 * This example should be run against an AdWords manager account.
 *
 * Although the example's name is `ParallelReportDownload`, it doesn't download
 * reports in parallel as this client library doesn't support multithreading.
 * It is named so to be consistent with other client libraries.
 */
class ParallelReportDownload
{

    // Timeout between retries in seconds.
    const BACKOFF_FACTOR = 5;

    // Maximum number of retries for 500 errors.
    const MAX_RETRIES = 5;

    // The number of entries per page of the results.
    const PAGE_LIMIT = 500;

    public static function runExample(
        AdWordsServices $adWordsServices,
        AdWordsSessionBuilder $sessionBuilder,
        $reportDir
    ) {
        // Construct an API session for the client customer ID specified in the
        // configuration file.
        $session = $sessionBuilder->build();

        // Create selector.
        $selector = new Selector();
        $selector->setFields(
            ['CampaignId', 'AdGroupId', 'Impressions', 'Clicks', 'Cost']
        );

        // Create report definition.
        $reportDefinition = new ReportDefinition();
        $reportDefinition->setSelector($selector);
        $reportDefinition->setReportName('Custom ADGROUP_PERFORMANCE_REPORT');
        $reportDefinition->setDateRangeType(
            ReportDefinitionDateRangeType::LAST_7_DAYS
        );
        $reportDefinition->setReportType(
            ReportDefinitionReportType::ADGROUP_PERFORMANCE_REPORT
        );
        $reportDefinition->setDownloadFormat(DownloadFormat::CSV);

        $customerIds = self::getAllManagedCustomerIds($adWordsServices, $session);
        printf(
            "Downloading reports for %d managed customers.\n",
            count($customerIds)
        );

        $successfulReports = [];
        $failedReports = [];

        foreach ($customerIds as $customerId) {
            $filePath = sprintf(
                '%s%sadgroup_%d.csv',
                $reportDir,
                DIRECTORY_SEPARATOR,
                $customerId
            );

            // Construct an API session for the specified client customer ID.
            $session = $sessionBuilder->withClientCustomerId($customerId)->build();
            $reportDownloader = new ReportDownloader($session);

            $retryCount = 0;
            $doContinue = true;
            do {
                $retryCount++;
                try {
                    // Optional: If you need to adjust report settings just for this one
                    // request, you can create and supply the settings override here.
                    // Otherwise, default values from the configuration file
                    // (adsapi_php.ini) are used.
                    $reportSettingsOverride = (new ReportSettingsBuilder())->includeZeroImpressions(false)->build();
                    $reportDownloadResult = $reportDownloader->downloadReport(
                        $reportDefinition,
                        $reportSettingsOverride
                    );
                    $reportDownloadResult->saveToFile($filePath);
                    printf(
                        "Report for client customer ID %d successfully downloaded to: %s\n",
                        $customerId,
                        $filePath
                    );
                    $successfulReports[$customerId] = $filePath;
                    $doContinue = false;
                } catch (ApiException $e) {
                    printf(
                        "Report attempt #%d for client customer ID %d was not downloaded due to: %s\n",
                        $retryCount,
                        $customerId,
                        $e->getMessage()
                    );

                    // If this is a server error, retry up to the defined maximum number
                    // of retries.
                    if ($e->getErrors() === null && $retryCount < self::MAX_RETRIES) {
                        $sleepTime = $retryCount * self::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";
    }

    /**
     * Retrieves all the customer IDs under a manager account.
     *
     * To set clientCustomerId to any manager account you want to get
     * reports for its client accounts, use `AdWordsSessionBuilder` to
     * create new session.
     */
    private static function getAllManagedCustomerIds(
        AdWordsServices $adWordsServices,
        AdWordsSession $session
    ) {
        $managedCustomerService = $adWordsServices->get($session, ManagedCustomerService::class);

        $selector = new Selector();
        $selector->setFields(['CustomerId']);
        $selector->setPaging(new Paging(0, self::PAGE_LIMIT));
        $selector->setPredicates(
            [
                new Predicate(
                    'CanManageClients',
                    PredicateOperator::EQUALS,
                    ['false']
                )
            ]
        );

        $customerIds = [];
        $totalNumEntries = 0;
        do {
            $page = $managedCustomerService->get($selector);
            if ($page->getEntries() !== null) {
                $totalNumEntries = $page->getTotalNumEntries();
                foreach ($page->getEntries() as $customer) {
                    $customerIds[] = $customer->getCustomerId();
                }
            }
            $selector->getPaging()->setStartIndex(
                $selector->getPaging()->getStartIndex() + self::PAGE_LIMIT
            );
        } while ($selector->getPaging()->getStartIndex() < $totalNumEntries);

        return $customerIds;
    }

    public static function main()
    {
        // Generate a refreshable OAuth2 credential for authentication.
        $oAuth2Credential = (new OAuth2TokenBuilder())->fromFile()->build();

        // See: AdWordsSessionBuilder for setting a client customer ID that is
        // different from that specified in your adsapi_php.ini file.
        $sessionBuilder = (new AdWordsSessionBuilder())->fromFile()->withOAuth2Credential($oAuth2Credential);

        self::runExample(
            new AdWordsServices(),
            $sessionBuilder,
            sys_get_temp_dir()
        );
    }
}

ParallelReportDownload::main();

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。