The code samples below provide examples of common reporting functions using the AdWords API. Client Library.
Download a criteria performance report with AWQL
#!/usr/bin/perl -w
#
# 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.
#
# This code example gets and downloads a criteria report using an AWQL query.
# Currently, there is only production support for reports download.
use strict;
use lib "../../../lib";
use utf8;
use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::Utilities::ReportQueryBuilder;
use Google::Ads::Common::ReportUtils;
use Cwd qw(abs_path);
use File::HomeDir;
use File::Spec;
# Example main subroutine.
sub download_criteria_report_with_awql {
my $client = shift;
my $output_file = shift;
# Create report query.
my (undef, undef, undef, $mday, $mon, $year) = localtime(time - 60 * 60 * 24);
my $yesterday = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
(undef, undef, undef, $mday, $mon, $year) =
localtime(time - 60 * 60 * 24 * 4);
my $four_days_ago = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
my $report_query =
Google::Ads::AdWords::Utilities::ReportQueryBuilder->new(
{client => $client})
->select([
"CampaignId", "AdGroupId", "Id", "Criteria",
"CriteriaType", "Impressions", "Clicks", "Cost"
]
)->from("CRITERIA_PERFORMANCE_REPORT")
->where("Status")
->in(["ENABLED", "PAUSED"])
->during($four_days_ago, $yesterday)
->build();
# Optional: Modify the reporting configuration of the client to suppress
# header, column, or summary rows in the report output and include data with
# zero impressions. You can choose to return enum field values as enum
# values instead of display values.
# You can also configure this via your adwords.properties configuration file.
$client->get_reporting_config()->set_skip_header(0);
$client->get_reporting_config()->set_skip_column_header(0);
$client->get_reporting_config()->set_skip_summary(0);
$client->get_reporting_config()->set_include_zero_impressions(1);
$client->get_reporting_config()->set_use_raw_enum_values(0);
# Get the report handler.
my $report_handler = Google::Ads::Common::ReportUtils::get_report_handler({
query => $report_query,
format => "CSV"
},
$client
);
# Download the report using the appropriate method on ReportDownloadHandler.
my $result;
if ($output_file) {
$result = $report_handler->save($output_file);
} else {
$result = $report_handler->get_as_string();
}
if (!$result) {
printf("An error has occurred of type '%s', triggered by '%s'.\n",
$result->get_type(), $result->get_trigger());
} elsif ($output_file) {
printf("Report was downloaded to \"%s\".\n", $output_file);
} else {
printf("%s\n", $result);
}
return 1;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();
# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);
my $output_file =
File::Spec->catfile(File::HomeDir->my_home, "criteria_report.csv");
# Call the example
download_criteria_report_with_awql($client, $output_file);
Download a criteria performance report using selectors
#!/usr/bin/perl -w
#
# 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.
#
# This code example gets and downloads a criteria report from an XML
# report definition.
# Currently, there is only production support for reports download.
use strict;
use lib "../../../lib";
use utf8;
use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::Reports::Predicate;
use Google::Ads::AdWords::Reports::ReportDefinition;
use Google::Ads::AdWords::Reports::Selector;
use Google::Ads::Common::ReportUtils;
use Cwd qw(abs_path);
use File::HomeDir;
use File::Spec;
# Example main subroutine.
sub download_criteria_report_with_selector {
my $client = shift;
my $output_file = shift;
# Create criteria status predicate.
my $predicate = Google::Ads::AdWords::Reports::Predicate->new({
field => "Status",
operator => "IN",
values => ["ENABLED", "PAUSED"]});
# Create selector.
my $selector = Google::Ads::AdWords::Reports::Selector->new({
fields => [
"CampaignId", "AdGroupId", "Id", "CriteriaType",
"Criteria", "FinalUrls", "Impressions", "Clicks",
"Cost"
],
predicates => [$predicate]});
# Create report definition.
my (undef, undef, undef, $mday, $mon, $year) = localtime(time);
my $today = sprintf("%d%02d%02d", ($year + 1900), ($mon + 1), $mday);
my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
reportName => "Last 7 days CRITERIA_PERFORMANCE_REPORT #" . $today,
dateRangeType => "LAST_7_DAYS",
reportType => "CRITERIA_PERFORMANCE_REPORT",
downloadFormat => "CSV",
selector => $selector
});
# Optional: Modify the reporting configuration of the client to suppress
# header, column, or summary rows in the report output and include data with
# zero impressions. You can choose to return enum field values as enum
# values instead of display values.
# You can also configure this via your adwords.properties configuration file.
$client->get_reporting_config()->set_skip_header(0);
$client->get_reporting_config()->set_skip_column_header(0);
$client->get_reporting_config()->set_skip_summary(0);
$client->get_reporting_config()->set_include_zero_impressions(0);
$client->get_reporting_config()->set_use_raw_enum_values(0);
# Get the report handler.
my $report_handler =
Google::Ads::Common::ReportUtils::get_report_handler($report_definition,
$client);
# Download the report using the appropriate method on ReportDownloadHandler.
my $result;
if ($output_file) {
$result = $report_handler->save($output_file);
} else {
$result = $report_handler->get_as_string();
}
if (!$result) {
printf("An error has occurred of type '%s', triggered by '%s'.\n",
$result->get_type(), $result->get_trigger());
} elsif ($output_file) {
printf("Report was downloaded to \"%s\".\n", $output_file);
} else {
printf("%s\n", $result);
}
return 1;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();
# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);
my $output_file =
File::Spec->catfile(File::HomeDir->my_home, "criteria_report.csv");
# Call the example
download_criteria_report_with_selector($client, $output_file);
Get the report fields from a report
#!/usr/bin/perl -w
#
# 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.
#
# This example gets report fields of a CRITERIA_PERFORMANCE_REPORT.
use strict;
use lib "../../../lib";
use utf8;
use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Cwd qw(abs_path);
# Example main subroutine.
sub get_report_fields {
my $client = shift;
# The type of the report to get fields for.
my $report_type = "CRITERIA_PERFORMANCE_REPORT";
# Get report fields.
my $report_definition_fields =
$client->ReportDefinitionService()
->getReportFields({reportType => $report_type});
# Display report fields.
printf "The report type \"%s\" contains the following fields:\n",
$report_type;
foreach my $report_definition_field (@{$report_definition_fields}) {
printf("- %s (%s)",
$report_definition_field->get_fieldName(),
$report_definition_field->get_fieldType());
if ($report_definition_field->get_enumValues()) {
printf " := [%s]",
join(", ", @{$report_definition_field->get_enumValues()});
}
print "\n";
}
return 1;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();
# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);
# Call the example
get_report_fields($client);
Download a report for multiple accounts
#!/usr/bin/perl -w
#
# 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.
#
# 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.
# NOTE: Even though this example is called parallel_report_download, this shows
# how to download the reports serially.
use strict;
use warnings;
use lib "../../../lib";
use utf8;
use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::Reports::ReportDefinition;
use Google::Ads::AdWords::Reports::Selector;
use Google::Ads::Common::ReportUtils;
use Google::Ads::AdWords::v201809::Paging;
use Google::Ads::AdWords::v201809::Selector;
use Cwd qw(abs_path);
use File::Spec;
use File::Temp qw/ tempdir /;
use constant PAGE_SIZE => 500;
# Set a timeout to fail if the report is not downloaded in a specified amount
# of time.
use constant JOB_TIMEOUT_IN_MILLISECONDS => 180000;
# The time to sleep in between retries will start at this time. Then an
# exponential back-off will be instituted.
use constant JOB_BASE_WAITTIME_IN_MILLISECONDS => 10000;
# Example main subroutine.
sub parallel_report_download {
my $client = shift;
my $report_directory = tempdir();
# Retrieve all accounts under the manager account.
my @customers = __get_all_managed_customers($client);
# Create selector.
my $selector = Google::Ads::AdWords::Reports::Selector->new(
{fields => ["CampaignId", "AdGroupId", "Impressions", "Clicks", "Cost"]});
# Create report definition.
my $report_definition = Google::Ads::AdWords::Reports::ReportDefinition->new({
reportName => "Custom ADGROUP_PERFORMANCE_REPORT",
dateRangeType => "LAST_7_DAYS",
reportType => "ADGROUP_PERFORMANCE_REPORT",
downloadFormat => "CSV",
selector => $selector
});
# Optional: Modify the reporting configuration of the client to suppress
# header, column, or summary rows in the report output and include data with
# zero impressions. You can choose to return enum field values as enum
# values instead of display values.
# You can also configure this via your adwords.properties configuration file.
$client->get_reporting_config()->set_skip_header(0);
$client->get_reporting_config()->set_skip_column_header(0);
$client->get_reporting_config()->set_skip_summary(0);
$client->get_reporting_config()->set_include_zero_impressions(0);
$client->get_reporting_config()->set_use_raw_enum_values(0);
printf("Downloading report for %d managed customers.\n", scalar @customers);
my $successful_reports = {};
my $failed_reports = {};
foreach my $customer_id (@customers) {
my $output_file =
File::Spec->catfile($report_directory,
sprintf("adgroup_%010d.csv", $customer_id));
$client->set_client_id($customer_id);
# Get the report handler.
my $report_handler =
Google::Ads::Common::ReportUtils::get_report_handler($report_definition,
$client);
# If there is a failure, then retry the request.
my $result;
my $retries = 0;
my $end_time = time + JOB_TIMEOUT_IN_MILLISECONDS;
do {
# Download the report.
$result = $report_handler->save($output_file);
my $waittime_in_milliseconds =
JOB_BASE_WAITTIME_IN_MILLISECONDS * (2**$retries);
if ( ((time + $waittime_in_milliseconds) < $end_time)
and !$result
and $result->get_response_code() >= 500)
{
printf("Report for client customer ID %s was not downloaded" .
" due to: %s - %s\n",
$customer_id, $result->get_type(), $result->get_trigger());
printf("Sleeping %d milliseconds before retrying...\n",
$waittime_in_milliseconds);
sleep($waittime_in_milliseconds / 1000); # Convert to seconds.
$retries++;
}
} while (time < $end_time
and !$result
and $result->get_response_code() >= 500);
if (!$result) {
printf("Report for client customer ID %s was not downloaded" .
" due to: %s - %s\n",
$customer_id, $result->get_type(), $result->get_trigger());
$failed_reports->{$customer_id} = sprintf("%s: %s - %s",
$output_file, $result->get_type(), $result->get_trigger());
} else {
printf(
"Report for client customer ID %s successfully downloaded to: %s\n",
$customer_id, $output_file);
$successful_reports->{$customer_id} = $output_file;
}
}
printf("All downloads completed. Results:\n");
printf("Successful reports:\n");
foreach my $client_customer_id (keys $successful_reports) {
printf("\tClient ID %s => '%s'\n",
$client_customer_id, $successful_reports->{$client_customer_id});
}
printf("Failed reports:\n");
foreach my $client_customer_id (keys $failed_reports) {
printf("\tClient ID %s => '%s'\n",
$client_customer_id, $failed_reports->{$client_customer_id});
}
printf("End of results.");
return 1;
}
# Retrieve all the customers under a manager account.
sub __get_all_managed_customers {
my ($client) = @_;
# Create selector.
my $paging = Google::Ads::AdWords::v201809::Paging->new({
startIndex => 0,
numberResults => PAGE_SIZE
});
my $predicate = Google::Ads::AdWords::v201809::Predicate->new({
field => "CanManageClients",
operator => "EQUALS",
values => "false"
});
my $selector = Google::Ads::AdWords::v201809::Selector->new({
fields => ["CustomerId"],
paging => $paging,
predicates => [$predicate]});
my $page;
my @customers = ();
do {
$page =
$client->ManagedCustomerService()->get({serviceSelector => $selector});
if ($page->get_entries()) {
foreach my $customer (@{$page->get_entries()}) {
push @customers, $customer->get_customerId();
}
}
$paging->set_startIndex($paging->get_startIndex() + PAGE_SIZE);
} while ($paging->get_startIndex() < $page->get_totalNumEntries());
return @customers;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();
# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);
# Call the example
parallel_report_download($client);
Stream results from a report
#!/usr/bin/perl -w
#
# 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.
#
# This example streams the result of an ad hoc report, collecting total
# impressions by campaign for each line. This demonstrates how you can extract
# data from a large report without holding the entire result set in memory
# or using files.
use strict;
use lib "../../../lib";
use utf8;
use Google::Ads::AdWords::Client;
use Google::Ads::AdWords::Logging;
use Google::Ads::AdWords::Utilities::ReportQueryBuilder;
use Google::Ads::Common::ReportUtils;
use Cwd qw(abs_path);
# Example main subroutine.
sub stream_criteria_report_results {
my $client = shift;
my $report_query =
Google::Ads::AdWords::Utilities::ReportQueryBuilder->new(
{client => $client})
->select([
"Id", "AdNetworkType1", "Impressions",
])->from("CRITERIA_PERFORMANCE_REPORT")
->where("Status")
->in(["ENABLED", "PAUSED"])
->during("LAST_7_DAYS")
->build();
# Optional: Set the reporting configuration of the session to suppress
# header, column name, or summary rows in the report output. You can also
# configure this via your adwords.properties configuration file.
# In addition, you can set whether you want to explicitly include or
# exclude zero impression rows and you can set whether to return enum values
# or display values for enum fields.
$client->get_reporting_config()->set_skip_header(1);
$client->get_reporting_config()->set_skip_column_header(1);
$client->get_reporting_config()->set_skip_summary(1);
$client->get_reporting_config()->set_include_zero_impressions(0);
$client->get_reporting_config()->set_use_raw_enum_values(0);
# Get the report handler.
my $report_handler = Google::Ads::Common::ReportUtils::get_report_handler({
query => $report_query,
format => "CSV"
},
$client
);
# Pass in the anonymous subroutine that will be called as data is available
# for processing.
my %impressions_by_ad_network_type1 = ();
my $incomplete_line = '';
my $result = $report_handler->process_contents(
sub {
my ($data, $response) = @_;
# If the line is starting in the middle, then prepend the incomplete line
# from last time.
$data = $incomplete_line . $data;
$incomplete_line = '';
# Match the line that is ID,AdNetworkType1,Impressions
# Example: 123456,Search Network,5
while ($data =~ /(\d+),([^,]+),(\d+)\n/g) {
my ($ad_network_type1, $impressions) = ($2, $3);
my $impressions_total =
$impressions_by_ad_network_type1{$ad_network_type1};
$impressions_total =
(defined($impressions_total)) ? $impressions_total : 0;
$impressions_by_ad_network_type1{$ad_network_type1} =
$impressions_total + $impressions;
}
# If everything wasn't processed, then save off the incomplete line to
# be prepended the next time this subroutine is called.
if ($data =~ /\n(.*)$/) {
$incomplete_line = $1;
}
});
if (!$result) {
printf("An error has occurred of type '%s', triggered by '%s'.\n",
$result->get_type(), $result->get_trigger());
return 1;
}
# Print the impression totals by ad network type 1.
print("Total impressions by ad network type 1:\n");
while (my ($key, $val) = each %impressions_by_ad_network_type1) {
printf "$key\t$val\n";
}
return 1;
}
# Don't run the example if the file is being included.
if (abs_path($0) ne abs_path(__FILE__)) {
return 1;
}
# Log SOAP XML request, response and API errors.
Google::Ads::AdWords::Logging::enable_all_logging();
# Get AdWords Client, credentials will be read from ~/adwords.properties.
my $client = Google::Ads::AdWords::Client->new({version => "v201809"});
# By default examples are set to die on any server returned fault.
$client->set_die_on_faults(1);
# Call the example.
stream_criteria_report_results($client);
ご不明な点がありましたら、Google の