| 1 | # Copyright 2026, Google LLC | ||||||||||||||||||||||||||||
| 2 | # | ||||||||||||||||||||||||||||
| 3 | # Licensed under the Apache License, Version 2.0 (the "License"); | ||||||||||||||||||||||||||||
| 4 | # you may not use this file except in compliance with the License. | ||||||||||||||||||||||||||||
| 5 | # You may obtain a copy of the License at | ||||||||||||||||||||||||||||
| 6 | # | ||||||||||||||||||||||||||||
| 7 | # http://www.apache.org/licenses/LICENSE-2.0 | ||||||||||||||||||||||||||||
| 8 | # | ||||||||||||||||||||||||||||
| 9 | # Unless required by applicable law or agreed to in writing, software | ||||||||||||||||||||||||||||
| 10 | # distributed under the License is distributed on an "AS IS" BASIS, | ||||||||||||||||||||||||||||
| 11 | # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||||||||||||||||||||||||||||
| 12 | # See the License for the specific language governing permissions and | ||||||||||||||||||||||||||||
| 13 | # limitations under the License. | ||||||||||||||||||||||||||||
| 14 | # | ||||||||||||||||||||||||||||
| 15 | # The main interface to the Google Ads API. It takes care of handling your API | ||||||||||||||||||||||||||||
| 16 | # credentials, and exposes all of the underlying services that make up the | ||||||||||||||||||||||||||||
| 17 | # Google Ads API. | ||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | package Google::Ads::GoogleAds::Client; | ||||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||
| 21 | 11 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 22 | 11 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 23 | 11 | ▶ | use version; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 24 | 11 | our $VERSION = qv("36.2.0"); | |||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | 11 | ▶ | use Google::Ads::GoogleAds::OAuth2ApplicationsHandler; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 27 | 11 | ▶ | use Google::Ads::GoogleAds::OAuth2ServiceAccountsHandler; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 28 | 11 | ▶ | use Google::Ads::GoogleAds::Logging::GoogleAdsLogger; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | 11 | ▶ | use Class::Std::Fast; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 31 | |||||||||||||||||||||||||||||
| 32 | 11 | ▶ | use constant OAUTH2_APPLICATIONS_HANDLER => "OAUTH2_APPLICATIONS_HANDLER"; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 33 | 11 | ▶ | use constant OAUTH2_SERVICE_ACCOUNTS_HANDLER => | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 34 | 11 | "OAUTH2_SERVICE_ACCOUNTS_HANDLER"; | |||||||||||||||||||||||||||
| 35 | 11 | ▶ | use constant AUTH_HANDLERS_ORDER => | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 36 | 11 | (OAUTH2_APPLICATIONS_HANDLER, OAUTH2_SERVICE_ACCOUNTS_HANDLER); | |||||||||||||||||||||||||||
| 37 | |||||||||||||||||||||||||||||
| 38 | # Class::Std-style attributes. Most values are read from googleads.properties file. | ||||||||||||||||||||||||||||
| 39 | # These need to go in the same line for older Perl interpreters to understand. | ||||||||||||||||||||||||||||
| 40 | 11 | my %developer_token_of : ATTR(:name<developer_token> :default<>); | |||||||||||||||||||||||||||
| 41 | 11 | my %login_customer_id_of : ATTR(:name<login_customer_id> :default<>); | |||||||||||||||||||||||||||
| 42 | 11 | my %linked_customer_id_of : ATTR(:name<linked_customer_id> :default<>); | |||||||||||||||||||||||||||
| 43 | 11 | my %service_address_of : ATTR(:name<service_address> :default<>); | |||||||||||||||||||||||||||
| 44 | 11 | my %user_agent_of : ATTR(:name<user_agent> :default<>); | |||||||||||||||||||||||||||
| 45 | 11 | my %proxy_of : ATTR(:name<proxy> :default<>); | |||||||||||||||||||||||||||
| 46 | 11 | my %http_timeout_of : ATTR(:name<http_timeout> :default<>); | |||||||||||||||||||||||||||
| 47 | 11 | my %http_retry_timing_of : ATTR(:name<http_retry_timing> :default<>); | |||||||||||||||||||||||||||
| 48 | 11 | my %version_of : ATTR(:name<version> :default<>); | |||||||||||||||||||||||||||
| 49 | 11 | my %die_on_faults_of : ATTR(:name<die_on_faults> :default<0>); | |||||||||||||||||||||||||||
| 50 | |||||||||||||||||||||||||||||
| 51 | 11 | my %properties_file_of : ATTR(:init_arg<properties_file> :default<>); | |||||||||||||||||||||||||||
| 52 | 11 | my %services_of : ATTR(:name<services> :default<{}>); | |||||||||||||||||||||||||||
| 53 | 11 | my %auth_handlers_of : ATTR(:name<auth_handlers> :default<>); | |||||||||||||||||||||||||||
| 54 | 11 | my %__enabled_auth_handler_of : ATTR(:name<__enabled_auth_handler> :default<>); | |||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | # Runtime statistics. | ||||||||||||||||||||||||||||
| 57 | 11 | my %last_request_of : ATTR(:name<last_request> :default<>); | |||||||||||||||||||||||||||
| 58 | 11 | my %last_response_of : ATTR(:name<last_response> :default<>); | |||||||||||||||||||||||||||
| 59 | |||||||||||||||||||||||||||||
| 60 | # Automatically called by Class::Std after the values for all the attributes | ||||||||||||||||||||||||||||
| 61 | # have been populated but before the constructor returns the new object. | ||||||||||||||||||||||||||||
| 62 | 8 | ▶ | sub START { | ||||||||||||||||||||||||||
|
Subroutine
START: called CC=17 SCAR=30.3
Pod
undocumented
| |||||||||||||||||||||||||||||
| 63 | 8 | my ($self, $ident) = @_; | |||||||||||||||||||||||||||
| 64 | |||||||||||||||||||||||||||||
| 65 | # If the properties file path is not specified during instantiation, load it | ||||||||||||||||||||||||||||
| 66 | # from the environment variable or set it to the default value. | ||||||||||||||||||||||||||||
| 67 | $properties_file_of{$ident} ||= | ||||||||||||||||||||||||||||
| 68 | 8 | ▶ | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_CONFIGURATION_FILE_PATH}; | ||||||||||||||||||||||||||
|
Condition100%3/3
$properties_file_of{$ident} ||= $ENV{"GOOGLE_ADS_CONFIGURATION_FILE_PATH"}
MC/DC100%2/2
$properties_file_of{$ident} ||= $ENV{"GOOGLE_ADS_CONFIGURATION_FILE_PATH"}
$properties_file_of{$ident}
$ENV{"GOOGLE_ADS_CONFIGURATION_FILE_PATH"}
Truth table100%3/3
A ||= B
A= $properties_file_of{$ident}B= $ENV{"GOOGLE_ADS_CONFIGURATION_FILE_PATH"}
| |||||||||||||||||||||||||||||
| 69 | 8 | ▶ | $properties_file_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition100%2/2
$properties_file_of{$ident} ||= "/home/cpancover/googleads.properties"
MC/DC100%1/1
$properties_file_of{$ident} ||= "/home/cpancover/googleads.properties"
$properties_file_of{$ident}
Truth table100%2/2
A
A= $properties_file_of{$ident}
| |||||||||||||||||||||||||||||
| 70 | Google::Ads::GoogleAds::Constants::DEFAULT_PROPERTIES_FILE; | ||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||
| 72 | 8 | my %properties = (); | |||||||||||||||||||||||||||
| 73 | # If there's a valid properties file, parse it and read the config values. | ||||||||||||||||||||||||||||
| 74 | 8 | ▶ | if ($properties_file_of{$ident} && -e $properties_file_of{$ident}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$properties_file_of{$ident} and -e $properties_file_of{$ident}
MC/DC50%1/2
$properties_file_of{$ident} and -e $properties_file_of{$ident}
$properties_file_of{$ident}
-e $properties_file_of{$ident}
Truth table66%2/3
A and B
A= $properties_file_of{$ident}B= -e $properties_file_of{$ident}
| |||||||||||||||||||||||||||||
| 75 | 6 | %properties = __parse_properties_file($properties_file_of{$ident}); | |||||||||||||||||||||||||||
| 76 | 6 | ▶ | $developer_token_of{$ident} ||= $properties{developerToken}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$developer_token_of{$ident} ||= $properties{"developerToken"}
MC/DC0%0/2
$developer_token_of{$ident} ||= $properties{"developerToken"}
$developer_token_of{$ident}
$properties{"developerToken"}
Truth table33%1/3
A ||= B
A= $developer_token_of{$ident}B= $properties{"developerToken"}
| |||||||||||||||||||||||||||||
| 77 | 6 | ▶ | $login_customer_id_of{$ident} ||= $properties{loginCustomerId}; | ||||||||||||||||||||||||||
|
Condition66%2/3
$login_customer_id_of{$ident} ||= $properties{"loginCustomerId"}
MC/DC0%0/2
$login_customer_id_of{$ident} ||= $properties{"loginCustomerId"}
$login_customer_id_of{$ident}
$properties{"loginCustomerId"}
Truth table66%2/3
A ||= B
A= $login_customer_id_of{$ident}B= $properties{"loginCustomerId"}
| |||||||||||||||||||||||||||||
| 78 | 6 | ▶ | $linked_customer_id_of{$ident} ||= $properties{linkedCustomerId}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$linked_customer_id_of{$ident} ||= $properties{"linkedCustomerId"}
MC/DC0%0/2
$linked_customer_id_of{$ident} ||= $properties{"linkedCustomerId"}
$linked_customer_id_of{$ident}
$properties{"linkedCustomerId"}
Truth table33%1/3
A ||= B
A= $linked_customer_id_of{$ident}B= $properties{"linkedCustomerId"}
| |||||||||||||||||||||||||||||
| 79 | 6 | ▶ | $service_address_of{$ident} ||= $properties{serviceAddress}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$service_address_of{$ident} ||= $properties{"serviceAddress"}
MC/DC0%0/2
$service_address_of{$ident} ||= $properties{"serviceAddress"}
$service_address_of{$ident}
$properties{"serviceAddress"}
Truth table33%1/3
A ||= B
A= $service_address_of{$ident}B= $properties{"serviceAddress"}
| |||||||||||||||||||||||||||||
| 80 | 6 | ▶ | $user_agent_of{$ident} ||= $properties{userAgent}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$user_agent_of{$ident} ||= $properties{"userAgent"}
MC/DC0%0/2
$user_agent_of{$ident} ||= $properties{"userAgent"}
$user_agent_of{$ident}
$properties{"userAgent"}
Truth table33%1/3
A ||= B
A= $user_agent_of{$ident}B= $properties{"userAgent"}
| |||||||||||||||||||||||||||||
| 81 | 6 | ▶ | $proxy_of{$ident} ||= $properties{proxy}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$proxy_of{$ident} ||= $properties{"proxy"}
MC/DC0%0/2
$proxy_of{$ident} ||= $properties{"proxy"}
$proxy_of{$ident}
$properties{"proxy"}
Truth table33%1/3
A ||= B
A= $proxy_of{$ident}B= $properties{"proxy"}
| |||||||||||||||||||||||||||||
| 82 | } | ||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | # Provide default values for below attributes if they weren't set by | ||||||||||||||||||||||||||||
| 85 | # parameters to new() nor in the properties file. | ||||||||||||||||||||||||||||
| 86 | 8 | ▶ | $service_address_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition100%2/2
$service_address_of{$ident} ||= "https://googleads.googleapis.com"
MC/DC100%1/1
$service_address_of{$ident} ||= "https://googleads.googleapis.com"
$service_address_of{$ident}
Truth table100%2/2
A
A= $service_address_of{$ident}
| |||||||||||||||||||||||||||||
| 87 | Google::Ads::GoogleAds::Constants::DEFAULT_SERVICE_ADDRESS; | ||||||||||||||||||||||||||||
| 88 | $service_address_of{$ident} .= "/" | ||||||||||||||||||||||||||||
| 89 | 8 | ▶ | if substr($service_address_of{$ident}, -1) ne "/"; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||
| 91 | 8 | ▶ | $user_agent_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition50%1/2
$user_agent_of{$ident} ||= "gl-perl/5.44.0"
MC/DC0%0/1
$user_agent_of{$ident} ||= "gl-perl/5.44.0"
$user_agent_of{$ident}
Truth table50%1/2
A
A= $user_agent_of{$ident}
| |||||||||||||||||||||||||||||
| 92 | Google::Ads::GoogleAds::Constants::DEFAULT_USER_AGENT; | ||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||
| 94 | 8 | ▶ | $http_timeout_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition50%1/2
$http_timeout_of{$ident} ||= 3600
MC/DC0%0/1
$http_timeout_of{$ident} ||= 3600
$http_timeout_of{$ident}
Truth table50%1/2
A
A= $http_timeout_of{$ident}
| |||||||||||||||||||||||||||||
| 95 | Google::Ads::GoogleAds::Constants::DEFAULT_HTTP_TIMEOUT; | ||||||||||||||||||||||||||||
| 96 | 8 | ▶ | $http_retry_timing_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition50%1/2
$http_retry_timing_of{$ident} ||= "5,10,15"
MC/DC0%0/1
$http_retry_timing_of{$ident} ||= "5,10,15"
$http_retry_timing_of{$ident}
Truth table50%1/2
A
A= $http_retry_timing_of{$ident}
| |||||||||||||||||||||||||||||
| 97 | Google::Ads::GoogleAds::Constants::DEFAULT_HTTP_RETRY_TIMING; | ||||||||||||||||||||||||||||
| 98 | 8 | ▶ | $version_of{$ident} ||= | ||||||||||||||||||||||||||
|
Condition50%1/2
$version_of{$ident} ||= "V26"
MC/DC0%0/1
$version_of{$ident} ||= "V26"
$version_of{$ident}
Truth table50%1/2
A
A= $version_of{$ident}
| |||||||||||||||||||||||||||||
| 99 | Google::Ads::GoogleAds::Constants::DEFAULT_API_VERSION; | ||||||||||||||||||||||||||||
| 100 | |||||||||||||||||||||||||||||
| 101 | # Setup of auth handlers. | ||||||||||||||||||||||||||||
| 102 | 8 | my %auth_handlers = (); | |||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||
| 104 | 8 | my $auth_handler = Google::Ads::GoogleAds::OAuth2ApplicationsHandler->new(); | |||||||||||||||||||||||||||
| 105 | 8 | $auth_handler->initialize($self, \%properties); | |||||||||||||||||||||||||||
| 106 | 8 | $auth_handlers{OAUTH2_APPLICATIONS_HANDLER} = $auth_handler; | |||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||
| 108 | 8 | $auth_handler = Google::Ads::GoogleAds::OAuth2ServiceAccountsHandler->new(); | |||||||||||||||||||||||||||
| 109 | 8 | $auth_handler->initialize($self, \%properties); | |||||||||||||||||||||||||||
| 110 | 8 | $auth_handlers{OAUTH2_SERVICE_ACCOUNTS_HANDLER} = $auth_handler; | |||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||
| 112 | 8 | $auth_handlers_of{$ident} = \%auth_handlers; | |||||||||||||||||||||||||||
| 113 | |||||||||||||||||||||||||||||
| 114 | # Initialize the logger module with the default log4perl.conf file or the default | ||||||||||||||||||||||||||||
| 115 | # values if the file is not found. | ||||||||||||||||||||||||||||
| 116 | # The logger module can only be initialized once, so the log settings in the | ||||||||||||||||||||||||||||
| 117 | # code before current method call will override the default settings. | ||||||||||||||||||||||||||||
| 118 | 8 | Google::Ads::GoogleAds::Logging::GoogleAdsLogger::initialize_logging(); | |||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||
| 120 | # Enable STDOUT output in utf8. | ||||||||||||||||||||||||||||
| 121 | 8 | binmode(STDOUT, ":utf8"); | |||||||||||||||||||||||||||
| 122 | } | ||||||||||||||||||||||||||||
| 123 | |||||||||||||||||||||||||||||
| 124 | # Automatically called by Class::Std when an unknown method is invoked on an | ||||||||||||||||||||||||||||
| 125 | # instance of this class. It is used to handle creating singletons (local to | ||||||||||||||||||||||||||||
| 126 | # each Google::Ads::GoogleAds::Client instance) of all the services. The names | ||||||||||||||||||||||||||||
| 127 | # of the services may change and shouldn't be hardcoded. | ||||||||||||||||||||||||||||
| 128 | 5 | ▶ | sub AUTOMETHOD { | ||||||||||||||||||||||||||
|
Subroutine
AUTOMETHOD: called CC=5 SCAR=16.8
Pod
undocumented
| |||||||||||||||||||||||||||||
| 129 | 5 | my ($self, $ident) = @_; | |||||||||||||||||||||||||||
| 130 | 5 | my $service_name = $_; | |||||||||||||||||||||||||||
| 131 | |||||||||||||||||||||||||||||
| 132 | 5 | ▶ | if ($service_name =~ /^\w+Service$/) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 133 | 3 | ▶ | if ($self->get_services()->{$service_name}) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 134 | # To emulate a singleton, return the existing instance of the service if | ||||||||||||||||||||||||||||
| 135 | # we already have it. The return value of AUTOMETHOD must be a sub | ||||||||||||||||||||||||||||
| 136 | # reference which is then invoked, so wrap the service in sub { }. | ||||||||||||||||||||||||||||
| 137 | 0 | ▶ | return sub { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||
| 138 | 0 | return $self->get_services()->{$service_name}; | |||||||||||||||||||||||||||
| 139 | 0 | }; | |||||||||||||||||||||||||||
| 140 | } else { | ||||||||||||||||||||||||||||
| 141 | 3 | my $version = $self->get_version(); | |||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||
| 143 | # Check to see if the module with that service name exists. | ||||||||||||||||||||||||||||
| 144 | # - is Google::Ads::GoogleAds::LongRunning::OperationService | ||||||||||||||||||||||||||||
| 145 | # - under Google::Ads::GoogleAds::$version | ||||||||||||||||||||||||||||
| 146 | # If not we warn and return nothing. | ||||||||||||||||||||||||||||
| 147 | 3 | ▶ | my $module_name = | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 148 | $service_name eq | ||||||||||||||||||||||||||||
| 149 | Google::Ads::GoogleAds::Constants::OPERATION_SERVICE_NAME | ||||||||||||||||||||||||||||
| 150 | ? Google::Ads::GoogleAds::Constants::OPERATION_SERVICE_CLASS_NAME | ||||||||||||||||||||||||||||
| 151 | : sprintf | ||||||||||||||||||||||||||||
| 152 | Google::Ads::GoogleAds::Constants::GOOGLE_ADS_SERVICES_CLASS_NAME, | ||||||||||||||||||||||||||||
| 153 | $version, $service_name; | ||||||||||||||||||||||||||||
| 154 | |||||||||||||||||||||||||||||
| 155 | 3 | eval("require $module_name"); # require module name | |||||||||||||||||||||||||||
| 156 | 3 | ▶ | if ($@) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 157 | 0 | warn("Module $module_name was not found."); | |||||||||||||||||||||||||||
| 158 | 0 | return; | |||||||||||||||||||||||||||
| 159 | } else { | ||||||||||||||||||||||||||||
| 160 | # Pass in this API client, so each service has access to the | ||||||||||||||||||||||||||||
| 161 | # current properties as developer_token, login_customer_id, | ||||||||||||||||||||||||||||
| 162 | # die_on_faults and these may change dynamically during runtime. | ||||||||||||||||||||||||||||
| 163 | 3 | my $service = $module_name->new({api_client => $self}); | |||||||||||||||||||||||||||
| 164 | 3 | $self->get_services()->{$service_name} = $service; | |||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||||
| 166 | 1 | ▶ | return sub { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 167 | 1 | return $self->get_services()->{$service_name}; | |||||||||||||||||||||||||||
| 168 | 3 | }; | |||||||||||||||||||||||||||
| 169 | } | ||||||||||||||||||||||||||||
| 170 | } | ||||||||||||||||||||||||||||
| 171 | } | ||||||||||||||||||||||||||||
| 172 | } | ||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | # Protected method to retrieve the proper enabled authorization handler. | ||||||||||||||||||||||||||||
| 175 | 0 | ▶ | sub _get_auth_handler { | ||||||||||||||||||||||||||
|
Subroutine
_get_auth_handler: not called CC=4 SCAR=30.0
| |||||||||||||||||||||||||||||
| 176 | 0 | my $self = shift; | |||||||||||||||||||||||||||
| 177 | |||||||||||||||||||||||||||||
| 178 | # Check if we have cached the enabled auth_handler. | ||||||||||||||||||||||||||||
| 179 | 0 | ▶ | if ($self->get___enabled_auth_handler()) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 180 | 0 | return $self->get___enabled_auth_handler(); | |||||||||||||||||||||||||||
| 181 | } | ||||||||||||||||||||||||||||
| 182 | |||||||||||||||||||||||||||||
| 183 | 0 | my $auth_handlers = $self->get_auth_handlers(); | |||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||
| 185 | 0 | foreach my $handler_id (AUTH_HANDLERS_ORDER) { | |||||||||||||||||||||||||||
| 186 | 0 | ▶ | if ($auth_handlers->{$handler_id}->is_auth_enabled()) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 187 | 0 | $self->set___enabled_auth_handler($auth_handlers->{$handler_id}); | |||||||||||||||||||||||||||
| 188 | 0 | last; | |||||||||||||||||||||||||||
| 189 | } | ||||||||||||||||||||||||||||
| 190 | } | ||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||
| 192 | 0 | return $self->get___enabled_auth_handler(); | |||||||||||||||||||||||||||
| 193 | } | ||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||
| 195 | # Private method to parse values in a properties file. | ||||||||||||||||||||||||||||
| 196 | 6 | ▶ | sub __parse_properties_file { | ||||||||||||||||||||||||||
|
Subroutine
__parse_properties_file: called CC=5 SCAR=16.2
| |||||||||||||||||||||||||||||
| 197 | 6 | my ($properties_file) = @_; | |||||||||||||||||||||||||||
| 198 | 6 | my %properties; | |||||||||||||||||||||||||||
| 199 | |||||||||||||||||||||||||||||
| 200 | # glob() to expand any metacharacters. | ||||||||||||||||||||||||||||
| 201 | 11 | ▶ | ($properties_file) = glob($properties_file); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 202 | |||||||||||||||||||||||||||||
| 203 | 6 | ▶ | if (open(PROP_FILE, $properties_file)) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 204 | # The data in the file should be in the following format: | ||||||||||||||||||||||||||||
| 205 | # key1=value1 | ||||||||||||||||||||||||||||
| 206 | # key2=value2 | ||||||||||||||||||||||||||||
| 207 | 6 | ▶ | while (my $line = <PROP_FILE>) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 208 | 54 | chomp($line); | |||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | # Skip comments. | ||||||||||||||||||||||||||||
| 211 | 54 | ▶ | next if ($line =~ /^#/ || $line =~ /^\s*$/); | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$line =~ /^#/ or $line =~ /^\s*$/
MC/DC50%1/2
$line =~ /^#/ or $line =~ /^\s*$/
$line =~ /^#/
$line =~ /^\s*$/
Truth table66%2/3
A or B
A= $line =~ /^#/B= $line =~ /^\s*$/
| |||||||||||||||||||||||||||||
| 212 | 48 | my ($key, $value) = split(/=/, $line, 2); | |||||||||||||||||||||||||||
| 213 | 48 | $properties{$key} = $value; | |||||||||||||||||||||||||||
| 214 | } | ||||||||||||||||||||||||||||
| 215 | 6 | close(PROP_FILE); | |||||||||||||||||||||||||||
| 216 | } else { | ||||||||||||||||||||||||||||
| 217 | 0 | die("Couldn't open properties file $properties_file for reading: $!\n"); | |||||||||||||||||||||||||||
| 218 | } | ||||||||||||||||||||||||||||
| 219 | 6 | return %properties; | |||||||||||||||||||||||||||
| 220 | } | ||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | 10 | ▶ | sub get_oauth2_handler { | ||||||||||||||||||||||||||
|
Subroutine
get_oauth2_handler: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||
| 223 | 10 | my $self = shift; | |||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||
| 225 | 10 | return $self->get_auth_handlers()->{OAUTH2_APPLICATIONS_HANDLER}; | |||||||||||||||||||||||||||
| 226 | } | ||||||||||||||||||||||||||||
| 227 | |||||||||||||||||||||||||||||
| 228 | 1 | ▶ | sub get_oauth2_applications_handler { | ||||||||||||||||||||||||||
|
Subroutine
get_oauth2_applications_handler: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 229 | 1 | my $self = shift; | |||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||
| 231 | 1 | return $self->get_auth_handlers()->{OAUTH2_APPLICATIONS_HANDLER}; | |||||||||||||||||||||||||||
| 232 | } | ||||||||||||||||||||||||||||
| 233 | |||||||||||||||||||||||||||||
| 234 | 1 | ▶ | sub get_oauth2_service_accounts_handler { | ||||||||||||||||||||||||||
|
Subroutine
get_oauth2_service_accounts_handler: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 235 | 1 | my ($self) = @_; | |||||||||||||||||||||||||||
| 236 | |||||||||||||||||||||||||||||
| 237 | 1 | return $self->get_auth_handlers()->{OAUTH2_SERVICE_ACCOUNTS_HANDLER}; | |||||||||||||||||||||||||||
| 238 | } | ||||||||||||||||||||||||||||
| 239 | |||||||||||||||||||||||||||||
| 240 | # Loads the environment variables to configure this API client. | ||||||||||||||||||||||||||||
| 241 | 1 | ▶ | sub configure_from_environment_variables { | ||||||||||||||||||||||||||
|
Subroutine
configure_from_environment_variables: called CC=12 SCAR=29.1
Pod
documented
| |||||||||||||||||||||||||||||
| 242 | 1 | my $self = shift; | |||||||||||||||||||||||||||
| 243 | 1 | my $ident = ident $self; | |||||||||||||||||||||||||||
| 244 | |||||||||||||||||||||||||||||
| 245 | $developer_token_of{$ident} = | ||||||||||||||||||||||||||||
| 246 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_DEVELOPER_TOKEN} | ||||||||||||||||||||||||||||
| 247 | 1 | ▶ | || $developer_token_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_DEVELOPER_TOKEN'} || $developer_token_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_DEVELOPER_TOKEN'} || $developer_token_of{$ident}
$ENV{'GOOGLE_ADS_DEVELOPER_TOKEN'}
$developer_token_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_DEVELOPER_TOKEN'}B= $developer_token_of{$ident}
| |||||||||||||||||||||||||||||
| 248 | $login_customer_id_of{$ident} = | ||||||||||||||||||||||||||||
| 249 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_LOGIN_CUSTOMER_ID} | ||||||||||||||||||||||||||||
| 250 | 1 | ▶ | || $login_customer_id_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_LOGIN_CUSTOMER_ID'} || $login_customer_id_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_LOGIN_CUSTOMER_ID'} || $login_customer_id_of{$ident}
$ENV{'GOOGLE_ADS_LOGIN_CUSTOMER_ID'}
$login_customer_id_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_LOGIN_CUSTOMER_ID'}B= $login_customer_id_of{$ident}
| |||||||||||||||||||||||||||||
| 251 | $linked_customer_id_of{$ident} = | ||||||||||||||||||||||||||||
| 252 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_LINKED_CUSTOMER_ID} | ||||||||||||||||||||||||||||
| 253 | 1 | ▶ | || $linked_customer_id_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_LINKED_CUSTOMER_ID'} || $linked_customer_id_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_LINKED_CUSTOMER_ID'} || $linked_customer_id_of{$ident}
$ENV{'GOOGLE_ADS_LINKED_CUSTOMER_ID'}
$linked_customer_id_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_LINKED_CUSTOMER_ID'}B= $linked_customer_id_of{$ident}
| |||||||||||||||||||||||||||||
| 254 | $service_address_of{$ident} = | ||||||||||||||||||||||||||||
| 255 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_ENDPOINT} | ||||||||||||||||||||||||||||
| 256 | 1 | ▶ | || $service_address_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_ENDPOINT'} || $service_address_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_ENDPOINT'} || $service_address_of{$ident}
$ENV{'GOOGLE_ADS_ENDPOINT'}
$service_address_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_ENDPOINT'}B= $service_address_of{$ident}
| |||||||||||||||||||||||||||||
| 257 | $user_agent_of{$ident} = | ||||||||||||||||||||||||||||
| 258 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_USER_AGENT} | ||||||||||||||||||||||||||||
| 259 | 1 | ▶ | || $user_agent_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_PERL_USER_AGENT'} || $user_agent_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_PERL_USER_AGENT'} || $user_agent_of{$ident}
$ENV{'GOOGLE_ADS_PERL_USER_AGENT'}
$user_agent_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_PERL_USER_AGENT'}B= $user_agent_of{$ident}
| |||||||||||||||||||||||||||||
| 260 | $proxy_of{$ident} = | ||||||||||||||||||||||||||||
| 261 | 1 | ▶ | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_PROXY} || $proxy_of{$ident}; | ||||||||||||||||||||||||||
|
Condition33%1/3
$ENV{'GOOGLE_ADS_PERL_PROXY'} || $proxy_of{$ident}
MC/DC0%0/2
$ENV{'GOOGLE_ADS_PERL_PROXY'} || $proxy_of{$ident}
$ENV{'GOOGLE_ADS_PERL_PROXY'}
$proxy_of{$ident}
Truth table33%1/3
A || B
A= $ENV{'GOOGLE_ADS_PERL_PROXY'}B= $proxy_of{$ident}
| |||||||||||||||||||||||||||||
| 262 | |||||||||||||||||||||||||||||
| 263 | 1 | my $auth_handler = $self->get_oauth2_applications_handler(); | |||||||||||||||||||||||||||
| 264 | 1 | my $client_id = $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_CLIENT_ID}; | |||||||||||||||||||||||||||
| 265 | my $client_secret = | ||||||||||||||||||||||||||||
| 266 | 1 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_CLIENT_SECRET}; | |||||||||||||||||||||||||||
| 267 | my $refresh_token = | ||||||||||||||||||||||||||||
| 268 | 1 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_REFRESH_TOKEN}; | |||||||||||||||||||||||||||
| 269 | |||||||||||||||||||||||||||||
| 270 | 1 | ▶ | $auth_handler->set_client_id($client_id) if $client_id; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 271 | 1 | ▶ | $auth_handler->set_client_secret($client_secret) if $client_secret; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 272 | 1 | ▶ | $auth_handler->set_refresh_token($refresh_token) if $refresh_token; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 273 | |||||||||||||||||||||||||||||
| 274 | 1 | $auth_handler = $self->get_oauth2_service_accounts_handler(); | |||||||||||||||||||||||||||
| 275 | my $json_key_file_path = | ||||||||||||||||||||||||||||
| 276 | 1 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_JSON_KEY_FILE_PATH}; | |||||||||||||||||||||||||||
| 277 | my $impersonated_email = | ||||||||||||||||||||||||||||
| 278 | 1 | $ENV{Google::Ads::GoogleAds::Constants::ENV_VAR_IMPERSONATED_EMAIL}; | |||||||||||||||||||||||||||
| 279 | |||||||||||||||||||||||||||||
| 280 | 1 | ▶ | $auth_handler->set_json_key_file_path($json_key_file_path) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 281 | if $json_key_file_path; | ||||||||||||||||||||||||||||
| 282 | 1 | ▶ | $auth_handler->set_impersonated_email($impersonated_email) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 283 | if $impersonated_email; | ||||||||||||||||||||||||||||
| 284 | } | ||||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||
| 286 | 11 | 1; | |||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||
| 288 | =pod | ||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||
| 290 | =head1 NAME | ||||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||||
| 292 | Google::Ads::GoogleAds::Client | ||||||||||||||||||||||||||||
| 293 | |||||||||||||||||||||||||||||
| 294 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 295 | |||||||||||||||||||||||||||||
| 296 | use Google::Ads::GoogleAds::Client; | ||||||||||||||||||||||||||||
| 297 | |||||||||||||||||||||||||||||
| 298 | my $api_client = Google::Ads::GoogleAds::Client->new(); | ||||||||||||||||||||||||||||
| 299 | |||||||||||||||||||||||||||||
| 300 | my $customer_id = "1234567890"; | ||||||||||||||||||||||||||||
| 301 | |||||||||||||||||||||||||||||
| 302 | my $query = "SELECT campaign.id, campaign.name FROM campaign"; | ||||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||||
| 304 | my $response = $api_client->GoogleAdsService()->search({ | ||||||||||||||||||||||||||||
| 305 | customer_id => $customer_id, | ||||||||||||||||||||||||||||
| 306 | query => $query, | ||||||||||||||||||||||||||||
| 307 | pageSize => PAGE_SIZE | ||||||||||||||||||||||||||||
| 308 | }); | ||||||||||||||||||||||||||||
| 309 | |||||||||||||||||||||||||||||
| 310 | foreach my $row (@{$response->{results}}) { | ||||||||||||||||||||||||||||
| 311 | # Do something with the results | ||||||||||||||||||||||||||||
| 312 | } | ||||||||||||||||||||||||||||
| 313 | |||||||||||||||||||||||||||||
| 314 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 315 | |||||||||||||||||||||||||||||
| 316 | Google::Ads::GoogleAds::Client is the main interface to the Google Ads API. It | ||||||||||||||||||||||||||||
| 317 | takes care of handling your API credentials, and exposes all of the underlying | ||||||||||||||||||||||||||||
| 318 | services that make up the Google Ads API. | ||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||
| 320 | The C<Google::Ads::GoogleAds::Client> module should be loaded before other | ||||||||||||||||||||||||||||
| 321 | C<Google::Ads::> modules. A warning will occur if modules are loaded in the | ||||||||||||||||||||||||||||
| 322 | wrong order. | ||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||
| 324 | =head1 ATTRIBUTES | ||||||||||||||||||||||||||||
| 325 | |||||||||||||||||||||||||||||
| 326 | Each of these attributes can be set via Google::Ads::GoogleAds::Client->new(). | ||||||||||||||||||||||||||||
| 327 | |||||||||||||||||||||||||||||
| 328 | Alternatively, there is a get_ and set_ method associated with each attribute | ||||||||||||||||||||||||||||
| 329 | for retrieving or setting them dynamically. For example, the set_login_customer_id() | ||||||||||||||||||||||||||||
| 330 | allows you to change the value of the L</login_customer_id> attribute and | ||||||||||||||||||||||||||||
| 331 | get_login_customer_id() returns the current value of the attribute. | ||||||||||||||||||||||||||||
| 332 | |||||||||||||||||||||||||||||
| 333 | =head2 login_customer_id | ||||||||||||||||||||||||||||
| 334 | |||||||||||||||||||||||||||||
| 335 | This is the customer ID of the authorized customer to use in the request, without | ||||||||||||||||||||||||||||
| 336 | hyphens. If your access to the customer account is through a manager account, | ||||||||||||||||||||||||||||
| 337 | this attribute is required and must be set to the customer ID of the manager account. | ||||||||||||||||||||||||||||
| 338 | |||||||||||||||||||||||||||||
| 339 | =head2 linked_customer_id | ||||||||||||||||||||||||||||
| 340 | |||||||||||||||||||||||||||||
| 341 | This header is only required for methods that update the resources of an entity | ||||||||||||||||||||||||||||
| 342 | when permissioned via Linked Accounts in the Google Ads UI (AccountLink resource | ||||||||||||||||||||||||||||
| 343 | in the Google Ads API). Set this value to the customer ID of the data provider | ||||||||||||||||||||||||||||
| 344 | that updates the resources of the specified customer ID. It should be set without | ||||||||||||||||||||||||||||
| 345 | dashes. | ||||||||||||||||||||||||||||
| 346 | |||||||||||||||||||||||||||||
| 347 | =head2 service_address | ||||||||||||||||||||||||||||
| 348 | |||||||||||||||||||||||||||||
| 349 | The Google Ads API service address. | ||||||||||||||||||||||||||||
| 350 | |||||||||||||||||||||||||||||
| 351 | =head2 user_agent | ||||||||||||||||||||||||||||
| 352 | |||||||||||||||||||||||||||||
| 353 | The user-agent request header used to identify this application. | ||||||||||||||||||||||||||||
| 354 | |||||||||||||||||||||||||||||
| 355 | =head2 proxy | ||||||||||||||||||||||||||||
| 356 | |||||||||||||||||||||||||||||
| 357 | The proxy server URL to be used for internet connectivity. | ||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||
| 359 | =head2 http_timeout | ||||||||||||||||||||||||||||
| 360 | |||||||||||||||||||||||||||||
| 361 | The HTTP timeout value in seconds. | ||||||||||||||||||||||||||||
| 362 | |||||||||||||||||||||||||||||
| 363 | =head2 http_retry_timing | ||||||||||||||||||||||||||||
| 364 | |||||||||||||||||||||||||||||
| 365 | The HTTP retry timing for LWP::UserAgent::Determined. The string controls how | ||||||||||||||||||||||||||||
| 366 | many times it should retry, and how long the pauses should be in seconds. | ||||||||||||||||||||||||||||
| 367 | |||||||||||||||||||||||||||||
| 368 | =head2 version | ||||||||||||||||||||||||||||
| 369 | |||||||||||||||||||||||||||||
| 370 | The version of the Google Ads API to use. The latest is the default. | ||||||||||||||||||||||||||||
| 371 | |||||||||||||||||||||||||||||
| 372 | =head2 die_on_faults | ||||||||||||||||||||||||||||
| 373 | |||||||||||||||||||||||||||||
| 374 | By default the client returns a L<Google::Ads::GoogleAds::GoogleAdsException> object | ||||||||||||||||||||||||||||
| 375 | if an error has occurred at the server side. However if this flag is set to true, | ||||||||||||||||||||||||||||
| 376 | the client will issue a die() command on received API faults. | ||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||
| 378 | The default is "false". | ||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||
| 380 | =head2 properties_file | ||||||||||||||||||||||||||||
| 381 | |||||||||||||||||||||||||||||
| 382 | The path of the configuration file. The default value is F<googleads.properties> | ||||||||||||||||||||||||||||
| 383 | file in the home directory. | ||||||||||||||||||||||||||||
| 384 | |||||||||||||||||||||||||||||
| 385 | =head2 last_request | ||||||||||||||||||||||||||||
| 386 | |||||||||||||||||||||||||||||
| 387 | The last HTTP request sent by this client. | ||||||||||||||||||||||||||||
| 388 | |||||||||||||||||||||||||||||
| 389 | =head2 last_response | ||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||
| 391 | The last HTTP response received by this client. | ||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||
| 393 | =head1 METHODS | ||||||||||||||||||||||||||||
| 394 | |||||||||||||||||||||||||||||
| 395 | =head2 new | ||||||||||||||||||||||||||||
| 396 | |||||||||||||||||||||||||||||
| 397 | Initializes a new Google::Ads::GoogleAds::Client object. | ||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||
| 399 | =head3 Parameters | ||||||||||||||||||||||||||||
| 400 | |||||||||||||||||||||||||||||
| 401 | The new() method takes parameters as a hash reference. The attributes of this | ||||||||||||||||||||||||||||
| 402 | object can be populated in a number of ways: | ||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||
| 404 | =over | ||||||||||||||||||||||||||||
| 405 | |||||||||||||||||||||||||||||
| 406 | =item * | ||||||||||||||||||||||||||||
| 407 | |||||||||||||||||||||||||||||
| 408 | If the L</properties_file> parameter is given, then properties are read from that | ||||||||||||||||||||||||||||
| 409 | file and the corresponding attributes are populated. | ||||||||||||||||||||||||||||
| 410 | |||||||||||||||||||||||||||||
| 411 | =item * | ||||||||||||||||||||||||||||
| 412 | |||||||||||||||||||||||||||||
| 413 | If no L</properties_file> parameter is given, then the code checks to see if there | ||||||||||||||||||||||||||||
| 414 | is a file named F<googleads.properties> in the home directory of the current user. | ||||||||||||||||||||||||||||
| 415 | If there is, then properties are read from there. | ||||||||||||||||||||||||||||
| 416 | |||||||||||||||||||||||||||||
| 417 | =item * | ||||||||||||||||||||||||||||
| 418 | |||||||||||||||||||||||||||||
| 419 | Any of the L</ATTRIBUTES> can be passed in as keys in the parameters hash reference. | ||||||||||||||||||||||||||||
| 420 | If any attribute is explicitly passed in then it will override the value for that | ||||||||||||||||||||||||||||
| 421 | attribute that might be in the properties file. | ||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||
| 423 | =back | ||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||
| 425 | =head3 Returns | ||||||||||||||||||||||||||||
| 426 | |||||||||||||||||||||||||||||
| 427 | A new Google::Ads::GoogleAds::Client object with the appropriate attributes set. | ||||||||||||||||||||||||||||
| 428 | |||||||||||||||||||||||||||||
| 429 | =head3 Exceptions | ||||||||||||||||||||||||||||
| 430 | |||||||||||||||||||||||||||||
| 431 | If a L</properties_file> is passed in but the file cannot be read, the code will | ||||||||||||||||||||||||||||
| 432 | die() with an error message describing the failure. | ||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||
| 434 | =head3 Example | ||||||||||||||||||||||||||||
| 435 | |||||||||||||||||||||||||||||
| 436 | # Basic use case. Attributes will be read from ~/googleads.properties file. | ||||||||||||||||||||||||||||
| 437 | my $api_client = Google::Ads::GoogleAds::Client->new(); | ||||||||||||||||||||||||||||
| 438 | |||||||||||||||||||||||||||||
| 439 | # Most attributes from a custom properties file, but override login_customer_id. | ||||||||||||||||||||||||||||
| 440 | eval { | ||||||||||||||||||||||||||||
| 441 | my $api_client = Google::Ads::GoogleAds::Client->new({ | ||||||||||||||||||||||||||||
| 442 | properties_file => "/path/to/googleads.properties", | ||||||||||||||||||||||||||||
| 443 | login_customer_id => "1234567890" | ||||||||||||||||||||||||||||
| 444 | }); | ||||||||||||||||||||||||||||
| 445 | }; | ||||||||||||||||||||||||||||
| 446 | if ($@) { | ||||||||||||||||||||||||||||
| 447 | # The properties file couldn't be read; handle error as appropriate. | ||||||||||||||||||||||||||||
| 448 | } | ||||||||||||||||||||||||||||
| 449 | |||||||||||||||||||||||||||||
| 450 | # Specify attributes explicitly. The properties file will not override. | ||||||||||||||||||||||||||||
| 451 | my $api_client = Google::Ads::GoogleAds::Client->new({ | ||||||||||||||||||||||||||||
| 452 | login_customer_id => "1234567890" | ||||||||||||||||||||||||||||
| 453 | }); | ||||||||||||||||||||||||||||
| 454 | |||||||||||||||||||||||||||||
| 455 | $api_client->get_oauth2_applications_handler()->set_refresh_token('1/Abc...'); | ||||||||||||||||||||||||||||
| 456 | |||||||||||||||||||||||||||||
| 457 | =head2 set_die_on_faults | ||||||||||||||||||||||||||||
| 458 | |||||||||||||||||||||||||||||
| 459 | This module supports two approaches for handling API faults (i.e. errors | ||||||||||||||||||||||||||||
| 460 | returned by the underlying REST API service). | ||||||||||||||||||||||||||||
| 461 | |||||||||||||||||||||||||||||
| 462 | One approach is to issue a die() with a description of the error when an API | ||||||||||||||||||||||||||||
| 463 | fault occurs. This die() would ideally be contained within an eval { }; block, | ||||||||||||||||||||||||||||
| 464 | thereby emulating try { } / catch { } exception functionality in other | ||||||||||||||||||||||||||||
| 465 | languages. | ||||||||||||||||||||||||||||
| 466 | |||||||||||||||||||||||||||||
| 467 | A different approach is to require developers to explicitly check for API | ||||||||||||||||||||||||||||
| 468 | faults being returned after each Google Ads API request. This approach requires | ||||||||||||||||||||||||||||
| 469 | a bit more work, but has the advantage of exposing the full details of the API | ||||||||||||||||||||||||||||
| 470 | fault, like the fault code. | ||||||||||||||||||||||||||||
| 471 | |||||||||||||||||||||||||||||
| 472 | Refer to the object L<Google::Ads::GoogleAds::GoogleAdsException> for more details | ||||||||||||||||||||||||||||
| 473 | on how faults get returned. | ||||||||||||||||||||||||||||
| 474 | |||||||||||||||||||||||||||||
| 475 | The default value is false, i.e. you must explicitly check for faults. | ||||||||||||||||||||||||||||
| 476 | |||||||||||||||||||||||||||||
| 477 | =head3 Parameters | ||||||||||||||||||||||||||||
| 478 | |||||||||||||||||||||||||||||
| 479 | A true value will cause this module to die() when an API fault occurs. | ||||||||||||||||||||||||||||
| 480 | |||||||||||||||||||||||||||||
| 481 | A false value will suppress this die(). This is the default behavior. | ||||||||||||||||||||||||||||
| 482 | |||||||||||||||||||||||||||||
| 483 | =head3 Returns | ||||||||||||||||||||||||||||
| 484 | |||||||||||||||||||||||||||||
| 485 | The input parameter is returned. | ||||||||||||||||||||||||||||
| 486 | |||||||||||||||||||||||||||||
| 487 | =head3 Example | ||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||
| 489 | # $api_client is a Google::Ads::GoogleAds::Client. | ||||||||||||||||||||||||||||
| 490 | |||||||||||||||||||||||||||||
| 491 | # Enable die()ing on faults. | ||||||||||||||||||||||||||||
| 492 | $api_client->set_die_on_faults(1); | ||||||||||||||||||||||||||||
| 493 | eval { my $response = $api_client->AdGroupAdService()->mutate($mutate_request); }; | ||||||||||||||||||||||||||||
| 494 | if ($@) { | ||||||||||||||||||||||||||||
| 495 | # Do something with the error information in $@. | ||||||||||||||||||||||||||||
| 496 | } | ||||||||||||||||||||||||||||
| 497 | |||||||||||||||||||||||||||||
| 498 | # Default behavior. | ||||||||||||||||||||||||||||
| 499 | $api_client->set_die_on_faults(0); | ||||||||||||||||||||||||||||
| 500 | my $response = $api_client->AdGroupAdService()->mutate($mutate_request); | ||||||||||||||||||||||||||||
| 501 | if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) { | ||||||||||||||||||||||||||||
| 502 | # Do something with this GoogleAdsException object. | ||||||||||||||||||||||||||||
| 503 | } | ||||||||||||||||||||||||||||
| 504 | |||||||||||||||||||||||||||||
| 505 | =head2 get_die_on_faults | ||||||||||||||||||||||||||||
| 506 | |||||||||||||||||||||||||||||
| 507 | =head3 Returns | ||||||||||||||||||||||||||||
| 508 | |||||||||||||||||||||||||||||
| 509 | A true or false value indicating whether the L<Google::Ads::GoogleAds::Client> | ||||||||||||||||||||||||||||
| 510 | instance is set to die() on API faults. | ||||||||||||||||||||||||||||
| 511 | |||||||||||||||||||||||||||||
| 512 | =head2 {ServiceName} | ||||||||||||||||||||||||||||
| 513 | |||||||||||||||||||||||||||||
| 514 | The client object contains a method for each service provided by the Google Ads | ||||||||||||||||||||||||||||
| 515 | API. For example it can be invoked as $api_client->AdGroupService() and it will | ||||||||||||||||||||||||||||
| 516 | return an object of type L<Google::Ads::GoogleAds::V26::Services::AdGroupService> | ||||||||||||||||||||||||||||
| 517 | when using version V26 of the API. | ||||||||||||||||||||||||||||
| 518 | |||||||||||||||||||||||||||||
| 519 | For a list of all the available services please refer to | ||||||||||||||||||||||||||||
| 520 | L<https://developers.google.com/google-ads/api/docs> and for code samples on | ||||||||||||||||||||||||||||
| 521 | how to invoke the services please refer to scripts in the examples folder. | ||||||||||||||||||||||||||||
| 522 | |||||||||||||||||||||||||||||
| 523 | =head2 get_oauth2_applications_handler | ||||||||||||||||||||||||||||
| 524 | |||||||||||||||||||||||||||||
| 525 | Returns the OAuth2 authorization handler for Web/Desktop applications | ||||||||||||||||||||||||||||
| 526 | attached to the client, for programmatically setting/overriding its properties. | ||||||||||||||||||||||||||||
| 527 | |||||||||||||||||||||||||||||
| 528 | $api_client->get_oauth2_applications_handler()->set_client_id('client-id'); | ||||||||||||||||||||||||||||
| 529 | $api_client->get_oauth2_applications_handler()->set_client_secret('client-secret'); | ||||||||||||||||||||||||||||
| 530 | $api_client->get_oauth2_applications_handler()->set_access_token('access-token'); | ||||||||||||||||||||||||||||
| 531 | $api_client->get_oauth2_applications_handler()->set_refresh_token('refresh-token'); | ||||||||||||||||||||||||||||
| 532 | $api_client->get_oauth2_applications_handler()->set_access_type('access-type'); | ||||||||||||||||||||||||||||
| 533 | $api_client->get_oauth2_applications_handler()->set_prompt('prompt'); | ||||||||||||||||||||||||||||
| 534 | $api_client->get_oauth2_applications_handler()->set_redirect_uri('redirect-url'); | ||||||||||||||||||||||||||||
| 535 | |||||||||||||||||||||||||||||
| 536 | Refer to L<Google::Ads::GoogleAds::OAuth2ApplicationsHandler> for more details. | ||||||||||||||||||||||||||||
| 537 | |||||||||||||||||||||||||||||
| 538 | =head2 get_oauth2_service_accounts_handler | ||||||||||||||||||||||||||||
| 539 | |||||||||||||||||||||||||||||
| 540 | Returns the OAuth2 authorization handler for service accounts, for | ||||||||||||||||||||||||||||
| 541 | programmatically setting/overriding its properties. | ||||||||||||||||||||||||||||
| 542 | |||||||||||||||||||||||||||||
| 543 | $api_client->get_oauth2_service_accounts_handler()->set_json_key_file_path('json-key-file-path'); | ||||||||||||||||||||||||||||
| 544 | $api_client->get_oauth2_service_accounts_handler()->set_impersonated_email('impersonated-email'); | ||||||||||||||||||||||||||||
| 545 | $api_client->get_oauth2_service_accounts_handler()->set_access_token('access-token'); | ||||||||||||||||||||||||||||
| 546 | |||||||||||||||||||||||||||||
| 547 | Refer to L<Google::Ads::GoogleAds::OAuth2ServiceAccountsHandler> for more details. | ||||||||||||||||||||||||||||
| 548 | |||||||||||||||||||||||||||||
| 549 | =head2 configure_from_environment_variables | ||||||||||||||||||||||||||||
| 550 | |||||||||||||||||||||||||||||
| 551 | Loads the environment variables to configure this API client. | ||||||||||||||||||||||||||||
| 552 | |||||||||||||||||||||||||||||
| 553 | =head2 __parse_properties_file (Private) | ||||||||||||||||||||||||||||
| 554 | |||||||||||||||||||||||||||||
| 555 | =head3 Parameters | ||||||||||||||||||||||||||||
| 556 | |||||||||||||||||||||||||||||
| 557 | The path to a properties file on disk. The data in the file should be in the | ||||||||||||||||||||||||||||
| 558 | following format: | ||||||||||||||||||||||||||||
| 559 | |||||||||||||||||||||||||||||
| 560 | key1=value1 | ||||||||||||||||||||||||||||
| 561 | key2=value2 | ||||||||||||||||||||||||||||
| 562 | |||||||||||||||||||||||||||||
| 563 | =head3 Returns | ||||||||||||||||||||||||||||
| 564 | |||||||||||||||||||||||||||||
| 565 | A hash corresponding to the keys and values in the properties file. | ||||||||||||||||||||||||||||
| 566 | |||||||||||||||||||||||||||||
| 567 | =head3 Exceptions | ||||||||||||||||||||||||||||
| 568 | |||||||||||||||||||||||||||||
| 569 | Issues a die() with an error message if the properties file could not be read. | ||||||||||||||||||||||||||||
| 570 | |||||||||||||||||||||||||||||
| 571 | =head2 _get_auth_handler (Protected) | ||||||||||||||||||||||||||||
| 572 | |||||||||||||||||||||||||||||
| 573 | Retrieves the active auth handler. All handlers are checked in the order. | ||||||||||||||||||||||||||||
| 574 | |||||||||||||||||||||||||||||
| 575 | =head3 Returns | ||||||||||||||||||||||||||||
| 576 | |||||||||||||||||||||||||||||
| 577 | An implementation of L<Google::Ads::GoogleAds::Common::AuthHandlerInterface>. | ||||||||||||||||||||||||||||
| 578 | |||||||||||||||||||||||||||||
| 579 | =head1 LICENSE AND COPYRIGHT | ||||||||||||||||||||||||||||
| 580 | |||||||||||||||||||||||||||||
| 581 | Copyright 2019 Google LLC | ||||||||||||||||||||||||||||
| 582 | |||||||||||||||||||||||||||||
| 583 | Licensed under the Apache License, Version 2.0 (the "License"); | ||||||||||||||||||||||||||||
| 584 | you may not use this file except in compliance with the License. | ||||||||||||||||||||||||||||
| 585 | You may obtain a copy of the License at | ||||||||||||||||||||||||||||
| 586 | |||||||||||||||||||||||||||||
| 587 | http://www.apache.org/licenses/LICENSE-2.0 | ||||||||||||||||||||||||||||
| 588 | |||||||||||||||||||||||||||||
| 589 | Unless required by applicable law or agreed to in writing, software | ||||||||||||||||||||||||||||
| 590 | distributed under the License is distributed on an "AS IS" BASIS, | ||||||||||||||||||||||||||||
| 591 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||||||||||||||||||||||||||||
| 592 | See the License for the specific language governing permissions and | ||||||||||||||||||||||||||||
| 593 | limitations under the License. | ||||||||||||||||||||||||||||
| 594 | |||||||||||||||||||||||||||||
| 595 | =head1 REPOSITORY INFORMATION | ||||||||||||||||||||||||||||
| 596 | |||||||||||||||||||||||||||||
| 597 | $Rev: $ | ||||||||||||||||||||||||||||
| 598 | $LastChangedBy: $ | ||||||||||||||||||||||||||||
| 599 | $Id: $ | ||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||
| 601 | =cut | ||||||||||||||||||||||||||||