« lib/Google/Ads/Common/CaptchaRequiredError.pm
↑ Summary
lib/Google/Ads/SOAP/Typelib/ComplexType.pm »
| 1 | # Copyright 2011, Google Inc. All Rights Reserved. | ||
| 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 | package Google::Ads::AdWords::Client; | ||
| 16 | |||
| 17 | 14 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 18 | 14 | ▶ | use version; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 19 | our $VERSION = qv("5.8.2"); | ||
| 20 | |||
| 21 | 14 | ▶ | use Google::Ads::AdWords::Constants; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 22 | 0 | ▶ | use Google::Ads::AdWords::Deserializer; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 23 | use Google::Ads::AdWords::OAuth2ApplicationsHandler; | ||
| 24 | use Google::Ads::AdWords::OAuth2ServiceAccountsHandler; | ||
| 25 | use Google::Ads::AdWords::Reports::ReportingConfiguration; | ||
| 26 | use Google::Ads::AdWords::Serializer; | ||
| 27 | use Google::Ads::Common::HTTPTransport; | ||
| 28 | use Google::Ads::Common::Utilities::AdsUtilityRegistry; | ||
| 29 | |||
| 30 | use Class::Std::Fast; | ||
| 31 | use SOAP::WSDL qv("2.00.10"); | ||
| 32 | |||
| 33 | use constant OAUTH_2_APPLICATIONS_HANDLER => "OAUTH_2_APPLICATIONS_HANDLER"; | ||
| 34 | use constant OAUTH_2_SERVICE_ACCOUNTS_HANDLER => | ||
| 35 | "OAUTH_2_SERVICE_ACCOUNTS_HANDLER"; | ||
| 36 | use constant AUTH_HANDLERS_ORDER => | ||
| 37 | (OAUTH_2_APPLICATIONS_HANDLER, OAUTH_2_SERVICE_ACCOUNTS_HANDLER); | ||
| 38 | |||
| 39 | # Class::Std-style attributes. Most values read from adwords.properties file. | ||
| 40 | # These need to go in the same line for older Perl interpreters to understand. | ||
| 41 | my %client_id_of : ATTR(:name<client_id> :default<>); | ||
| 42 | my %user_agent_of : ATTR(:name<user_agent> :default<>); | ||
| 43 | my %developer_token_of : ATTR(:name<developer_token> :default<>); | ||
| 44 | my %version_of : ATTR(:name<version> :default<>); | ||
| 45 | my %alternate_url_of : ATTR(:name<alternate_url> :default<>); | ||
| 46 | my %die_on_faults_of : ATTR(:name<die_on_faults> :default<0>); | ||
| 47 | my %validate_only_of : ATTR(:name<validate_only> :default<0>); | ||
| 48 | my %partial_failure_of : ATTR(:name<partial_failure> :default<0>); | ||
| 49 | my %reporting_config_of : ATTR(:name<reporting_config> :default<>); | ||
| 50 | my %include_utilities_of : ATTR(:name<include_utilities> :default<>); | ||
| 51 | # Hisorically, the SOAP XML library was XML::XPath. Due to performance issues | ||
| 52 | # and bugs, the new SOAP XML library is XML::LibXML. This will be removed | ||
| 53 | # after the new library proves itself. | ||
| 54 | my %soap_legacy_of : ATTR(:name<soap_legacy> :default<0>); | ||
| 55 | |||
| 56 | my %properties_file_of : ATTR(:init_arg<properties_file> :default<>); | ||
| 57 | my %services_of : ATTR(:name<services> :default<{}>); | ||
| 58 | my %transport_of : ATTR(:name<transport> :default<>); | ||
| 59 | my %auth_handlers_of : ATTR(:name<auth_handlers> :default<>); | ||
| 60 | my %__enabled_auth_handler_of : ATTR(:name<__enabled_auth_handler> :default<>); | ||
| 61 | |||
| 62 | # Runtime statistics. | ||
| 63 | my %requests_count_of : ATTR(:name<requests_count> :default<0>); | ||
| 64 | my %failed_requests_count_of : ATTR(:name<failed_requests_count> :default<0>); | ||
| 65 | my %operations_count_of : ATTR(:name<operations_count> :default<0>); | ||
| 66 | my %last_request_stats_of : ATTR(:name<last_request_stats> :default<>); | ||
| 67 | my %last_soap_request_of : ATTR(:name<last_soap_request> :default<>); | ||
| 68 | my %last_soap_response_of : ATTR(:name<last_soap_response> :default<>); | ||
| 69 | |||
| 70 | # Static module-level variables. | ||
| 71 | |||
| 72 | # Automatically called by Class::Std after the values for all the attributes | ||
| 73 | # have been populated but before the constuctor returns the new object. | ||
| 74 | sub START { | ||
| 75 | my ($self, $ident) = @_; | ||
| 76 | |||
| 77 | my $default_properties_file = | ||
| 78 | Google::Ads::AdWords::Constants::DEFAULT_PROPERTIES_FILE; | ||
| 79 | if (not $properties_file_of{$ident} and -e $default_properties_file) { | ||
| 80 | $properties_file_of{$ident} = $default_properties_file; | ||
| 81 | } | ||
| 82 | |||
| 83 | my %properties = (); | ||
| 84 | if ($properties_file_of{$ident}) { | ||
| 85 | |||
| 86 | # If there's a valid properties file to read from, parse it and use the | ||
| 87 | # config values to fill in any missing attributes. | ||
| 88 | %properties = __parse_properties_file($properties_file_of{$ident}); | ||
| 89 | $client_id_of{$ident} ||= $properties{clientId}; | ||
| 90 | $user_agent_of{$ident} ||= $properties{useragent} || $properties{userAgent}; | ||
| 91 | $developer_token_of{$ident} ||= $properties{developerToken}; | ||
| 92 | $version_of{$ident} ||= $properties{version}; | ||
| 93 | $alternate_url_of{$ident} ||= $properties{alternateUrl}; | ||
| 94 | $validate_only_of{$ident} ||= $properties{validateOnly}; | ||
| 95 | $partial_failure_of{$ident} ||= $properties{partialFailure}; | ||
| 96 | $include_utilities_of{$ident} ||= | ||
| 97 | $properties{"header.userAgent.includeUtilities"}; | ||
| 98 | $soap_legacy_of{$ident} ||= $properties{"soap.legacy"}; | ||
| 99 | |||
| 100 | # Construct the ReportingConfiguration. | ||
| 101 | $reporting_config_of{$ident} ||= | ||
| 102 | Google::Ads::AdWords::Reports::ReportingConfiguration->new({ | ||
| 103 | skip_header => $properties{"reporting.skipHeader"}, | ||
| 104 | skip_column_header => $properties{"reporting.skipColumnHeader"}, | ||
| 105 | skip_summary => $properties{"reporting.skipSummary"}, | ||
| 106 | include_zero_impressions => | ||
| 107 | $properties{"reporting.includeZeroImpressions"}, | ||
| 108 | use_raw_enum_values => $properties{"reporting.useRawEnumValues"}}); | ||
| 109 | |||
| 110 | # SSL Peer validation setup. | ||
| 111 | $self->__setup_SSL($properties{CAPath}, $properties{CAFile}); | ||
| 112 | } | ||
| 113 | |||
| 114 | # We want to provide default values for these attributes if they weren't | ||
| 115 | # set by parameters to new() or the properties file. | ||
| 116 | $alternate_url_of{$ident} ||= | ||
| 117 | Google::Ads::AdWords::Constants::DEFAULT_ALTERNATE_URL; | ||
| 118 | $validate_only_of{$ident} ||= | ||
| 119 | Google::Ads::AdWords::Constants::DEFAULT_VALIDATE_ONLY; | ||
| 120 | $version_of{$ident} ||= Google::Ads::AdWords::Constants::DEFAULT_VERSION; | ||
| 121 | $partial_failure_of{$ident} ||= 0; | ||
| 122 | $reporting_config_of{$ident} ||= | ||
| 123 | Google::Ads::AdWords::Reports::ReportingConfiguration->new(); | ||
| 124 | $include_utilities_of{$ident} = 1 | ||
| 125 | unless defined $include_utilities_of{$ident}; | ||
| 126 | $soap_legacy_of{$ident} ||= 0; | ||
| 127 | |||
| 128 | # Setup of auth handlers | ||
| 129 | my %auth_handlers = (); | ||
| 130 | |||
| 131 | my $auth_handler = Google::Ads::AdWords::OAuth2ApplicationsHandler->new(); | ||
| 132 | $auth_handler->initialize($self, \%properties); | ||
| 133 | $auth_handlers{OAUTH_2_APPLICATIONS_HANDLER} = $auth_handler; | ||
| 134 | |||
| 135 | $auth_handler = Google::Ads::AdWords::OAuth2ServiceAccountsHandler->new(); | ||
| 136 | $auth_handler->initialize($self, \%properties); | ||
| 137 | $auth_handlers{OAUTH_2_SERVICE_ACCOUNTS_HANDLER} = $auth_handler; | ||
| 138 | |||
| 139 | $auth_handlers_of{$ident} = \%auth_handlers; | ||
| 140 | |||
| 141 | # Setups the HTTP transport and OAuthHandler this client will use. | ||
| 142 | $transport_of{$ident} = Google::Ads::Common::HTTPTransport->new(); | ||
| 143 | $transport_of{$ident}->client($self); | ||
| 144 | } | ||
| 145 | |||
| 146 | # Automatically called by Class::Std when an unknown method is invoked on an | ||
| 147 | # instance of this class. It is used to handle creating singletons (local to | ||
| 148 | # each Google::Ads::AdWords::Client instance) of all the SOAP services. The | ||
| 149 | # names of the services may change and shouldn't be hardcoded. | ||
| 150 | sub AUTOMETHOD { | ||
| 151 | my ($self, $ident) = @_; | ||
| 152 | my $method_name = $_; | ||
| 153 | |||
| 154 | # All SOAP services should end in "Service"; fail early if the requested | ||
| 155 | # method doesn't. | ||
| 156 | if ($method_name =~ /^\w+Service$/) { | ||
| 157 | if ($self->get_services()->{$method_name}) { | ||
| 158 | |||
| 159 | # To emulate a singleton, return the existing instance of the service if | ||
| 160 | # we already have it. The return value of AUTOMETHOD must be a sub | ||
| 161 | # reference which is then invoked, so wrap the service in sub { }. | ||
| 162 | return sub { | ||
| 163 | return $self->get_services()->{$method_name}; | ||
| 164 | }; | ||
| 165 | } else { | ||
| 166 | my $version = $self->get_version(); | ||
| 167 | |||
| 168 | # Check to see if there is a module with that name under | ||
| 169 | # Google::Ads::AdWords::$version if not we warn and return nothing. | ||
| 170 | my $module_name = | ||
| 171 | "Google::Ads::AdWords::${version}::${method_name}" . | ||
| 172 | "::${method_name}InterfacePort"; | ||
| 173 | eval("require $module_name"); | ||
| 174 | if ($@) { | ||
| 175 | warn("Module $module_name was not found."); | ||
| 176 | return; | ||
| 177 | } else { | ||
| 178 | |||
| 179 | # Generating the service endpoint url of the form | ||
| 180 | # https://{server_url}/{group_name(cm/job/info/o)}/{version}/{service}. | ||
| 181 | my $server_url = | ||
| 182 | $self->get_alternate_url() =~ /\/$/ | ||
| 183 | ? substr($self->get_alternate_url(), 0, -1) | ||
| 184 | : $self->get_alternate_url(); | ||
| 185 | my $service_to_group_name = | ||
| 186 | $Google::Ads::AdWords::Constants::SERVICE_TO_GROUP{$method_name}; | ||
| 187 | if (!$service_to_group_name) { | ||
| 188 | die("Service " . $method_name . " is not configured in the library."); | ||
| 189 | } | ||
| 190 | my $endpoint_url = | ||
| 191 | sprintf(Google::Ads::AdWords::Constants::PROXY_FORMAT_STRING, | ||
| 192 | $server_url, $service_to_group_name, $self->get_version(), | ||
| 193 | $method_name); | ||
| 194 | |||
| 195 | # If a suitable module is found, instantiate it and store it in | ||
| 196 | # instance-specific storage to emulate a singleton. | ||
| 197 | my $service_port = $module_name->new({ | ||
| 198 | |||
| 199 | # Setting the server endpoint of the service. | ||
| 200 | proxy => [$endpoint_url], | ||
| 201 | |||
| 202 | # Associating our custom serializer. | ||
| 203 | serializer => | ||
| 204 | Google::Ads::AdWords::Serializer->new({client => $self}), | ||
| 205 | |||
| 206 | # Associating our custom deserializer. | ||
| 207 | deserializer => | ||
| 208 | Google::Ads::AdWords::Deserializer->new({client => $self})}); | ||
| 209 | |||
| 210 | # Injecting our own transport. | ||
| 211 | $service_port->set_transport($self->get_transport()); | ||
| 212 | |||
| 213 | if ($ENV{HTTP_PROXY}) { | ||
| 214 | $service_port->get_transport()->proxy(['http'], $ENV{HTTP_PROXY}); | ||
| 215 | } | ||
| 216 | if ($ENV{HTTPS_PROXY}) { | ||
| 217 | $service_port->get_transport()->proxy(['https'], $ENV{HTTPS_PROXY}); | ||
| 218 | } | ||
| 219 | |||
| 220 | $self->get_services()->{$method_name} = $service_port; | ||
| 221 | return sub { | ||
| 222 | return $self->get_services()->{$method_name}; | ||
| 223 | }; | ||
| 224 | } | ||
| 225 | } | ||
| 226 | } | ||
| 227 | } | ||
| 228 | |||
| 229 | # Protected method to retrieve the proper enabled authorization handler. | ||
| 230 | sub _get_auth_handler { | ||
| 231 | my $self = shift; | ||
| 232 | |||
| 233 | # Check if we have cached the enabled auth_handler. | ||
| 234 | if ($self->get___enabled_auth_handler()) { | ||
| 235 | return $self->get___enabled_auth_handler(); | ||
| 236 | } | ||
| 237 | |||
| 238 | my $auth_handlers = $self->get_auth_handlers(); | ||
| 239 | |||
| 240 | foreach my $handler_id (AUTH_HANDLERS_ORDER) { | ||
| 241 | if ($auth_handlers->{$handler_id}->is_auth_enabled()) { | ||
| 242 | $self->set___enabled_auth_handler($auth_handlers->{$handler_id}); | ||
| 243 | last; | ||
| 244 | } | ||
| 245 | } | ||
| 246 | |||
| 247 | return $self->get___enabled_auth_handler(); | ||
| 248 | } | ||
| 249 | |||
| 250 | # Private method to setup IO::Socket::SSL and Crypt::SSLeay variables | ||
| 251 | # for certificate and hostname validation. | ||
| 252 | sub __setup_SSL { | ||
| 253 | my ($self, $ca_path, $ca_file) = @_; | ||
| 254 | if ($ca_path || $ca_file) { | ||
| 255 | $ENV{HTTPS_CA_DIR} = $ca_path; | ||
| 256 | $ENV{HTTPS_CA_FILE} = $ca_file; | ||
| 257 | eval { | ||
| 258 | require IO::Socket::SSL; | ||
| 259 | require Net::SSLeay; | ||
| 260 | IO::Socket::SSL::set_ctx_defaults( | ||
| 261 | verify_mode => Net::SSLeay->VERIFY_PEER(), | ||
| 262 | SSL_verifycn_scheme => "www", | ||
| 263 | ca_file => $ca_file, | ||
| 264 | ca_path => $ca_path | ||
| 265 | ); | ||
| 266 | }; | ||
| 267 | } | ||
| 268 | } | ||
| 269 | |||
| 270 | # Private method to parse values in a properties file. | ||
| 271 | sub __parse_properties_file { | ||
| 272 | my ($properties_file) = @_; | ||
| 273 | my %properties; | ||
| 274 | |||
| 275 | # glob() to expand any metacharacters. | ||
| 276 | ($properties_file) = glob($properties_file); | ||
| 277 | |||
| 278 | if (open(PROP_FILE, $properties_file)) { | ||
| 279 | |||
| 280 | # The data in the file should be in the following format: | ||
| 281 | # key1=value1 | ||
| 282 | # key2=value2 | ||
| 283 | while (my $line = <PROP_FILE>) { | ||
| 284 | chomp($line); | ||
| 285 | |||
| 286 | # Skip comments. | ||
| 287 | next if ($line =~ /^#/ || $line =~ /^\s*$/); | ||
| 288 | my ($key, $value) = split(/=/, $line, 2); | ||
| 289 | $properties{$key} = $value; | ||
| 290 | } | ||
| 291 | close(PROP_FILE); | ||
| 292 | } else { | ||
| 293 | die("Couldn't open properties file $properties_file for reading: $!\n"); | ||
| 294 | } | ||
| 295 | return %properties; | ||
| 296 | } | ||
| 297 | |||
| 298 | # Protected method to generate the appropriate SOAP request header. | ||
| 299 | sub _get_header { | ||
| 300 | my ($self) = @_; | ||
| 301 | |||
| 302 | # A value of 1 (evaluating to true) occurs when a user explicitly defines 1 | ||
| 303 | # in the properties file or a user has ommitted the value from the properties | ||
| 304 | # file. A value of 0 (evaluating to false) occurs when a user explicitly | ||
| 305 | # defines 0 in the properties file. | ||
| 306 | my $ads_utilities = | ||
| 307 | ($self->get_include_utilities()) | ||
| 308 | ? sprintf( | ||
| 309 | ", %s", | ||
| 310 | Google::Ads::Common::Utilities::AdsUtilityRegistry | ||
| 311 | ->get_and_reset_ads_utility_registry_string( | ||
| 312 | )) | ||
| 313 | : ""; | ||
| 314 | |||
| 315 | # Set the application name to the default if not provided. | ||
| 316 | # Verify that it is ASCII. | ||
| 317 | my $application_name = | ||
| 318 | ($self->get_user_agent() | ||
| 319 | && ($self->get_user_agent() ne "INSERT_USER_AGENT_HERE") | ||
| 320 | ? $self->get_user_agent() | ||
| 321 | : Google::Ads::AdWords::Constants::DEFAULT_USER_AGENT); | ||
| 322 | if ($application_name =~ /[[:^ascii:]]/) { | ||
| 323 | my $error_message = sprintf( | ||
| 324 | "userAgent [%s] in client must be ASCII.", $application_name); | ||
| 325 | if ($self->get_die_on_faults()) { | ||
| 326 | die($error_message); | ||
| 327 | } else { | ||
| 328 | warn($error_message); | ||
| 329 | } | ||
| 330 | } | ||
| 331 | |||
| 332 | # Always prepend the module identifier to the user agent. | ||
| 333 | my $user_agent = sprintf( | ||
| 334 | "%s (AwApi-Perl/%s, Common-Perl/%s, SOAP-WSDL/%s, " . | ||
| 335 | "libwww-perl/%s, perl/%s%s)", | ||
| 336 | $application_name, | ||
| 337 | ${Google::Ads::AdWords::Constants::VERSION}, | ||
| 338 | ${Google::Ads::Common::Constants::VERSION}, | ||
| 339 | ${SOAP::WSDL::VERSION}, | ||
| 340 | ${LWP::UserAgent::VERSION}, | ||
| 341 | $], | ||
| 342 | $ads_utilities | ||
| 343 | ); | ||
| 344 | |||
| 345 | my $headers = { | ||
| 346 | userAgent => $user_agent, | ||
| 347 | developerToken => $self->get_developer_token(), | ||
| 348 | validateOnly => $self->get_validate_only(), | ||
| 349 | partialFailure => $self->get_partial_failure()}; | ||
| 350 | my $clientId = $self->get_client_id(); | ||
| 351 | |||
| 352 | # $clientId may not be set, in which case we're operating on the account | ||
| 353 | # specified by the auth credentials. | ||
| 354 | if ($clientId) { | ||
| 355 | $headers->{clientCustomerId} = $clientId; | ||
| 356 | } | ||
| 357 | |||
| 358 | return $headers; | ||
| 359 | } | ||
| 360 | |||
| 361 | sub get_oauth_2_handler { | ||
| 362 | my ($self) = @_; | ||
| 363 | |||
| 364 | return $self->get_auth_handlers()->{OAUTH_2_APPLICATIONS_HANDLER}; | ||
| 365 | } | ||
| 366 | |||
| 367 | sub get_oauth_2_applications_handler { | ||
| 368 | my ($self) = @_; | ||
| 369 | |||
| 370 | return $self->get_auth_handlers()->{OAUTH_2_APPLICATIONS_HANDLER}; | ||
| 371 | } | ||
| 372 | |||
| 373 | sub get_oauth_2_service_accounts_handler { | ||
| 374 | my ($self) = @_; | ||
| 375 | |||
| 376 | return $self->get_auth_handlers()->{OAUTH_2_SERVICE_ACCOUNTS_HANDLER}; | ||
| 377 | } | ||
| 378 | |||
| 379 | # Adds a new RequestStats object to the client and updates the aggregated | ||
| 380 | # stats. It also checks against the MAX_NUM_OF_REQUEST_STATS constant to | ||
| 381 | # not make the array of lastest stats grow infinitely. | ||
| 382 | sub _push_new_request_stats { | ||
| 383 | my ($self, $request_stats) = @_; | ||
| 384 | |||
| 385 | $self->set_last_request_stats($request_stats); | ||
| 386 | $self->set_requests_count($self->get_requests_count() + 1); | ||
| 387 | $request_stats->get_is_fault() | ||
| 388 | and | ||
| 389 | $self->set_failed_requests_count($self->get_failed_requests_count() + 1); | ||
| 390 | $self->set_operations_count( | ||
| 391 | $self->get_operations_count() + $request_stats->get_operations()); | ||
| 392 | } | ||
| 393 | |||
| 394 | 1; | ||
| 395 | |||
| 396 | =pod | ||
| 397 | |||
| 398 | =head1 NAME | ||
| 399 | |||
| 400 | Google::Ads::AdWords::Client | ||
| 401 | |||
| 402 | =head1 SYNOPSIS | ||
| 403 | |||
| 404 | use Google::Ads::AdWords::Client; | ||
| 405 | |||
| 406 | my $client = Google::Ads::AdWords::Client->new(); | ||
| 407 | |||
| 408 | my $adGroupId = "12345678"; | ||
| 409 | |||
| 410 | my $adgroupad_selector = | ||
| 411 | Google::Ads::AdWords::v201809::Types::AdGroupAdSelector->new({ | ||
| 412 | adGroupIds => [$adGroupId] | ||
| 413 | }); | ||
| 414 | |||
| 415 | my $page = | ||
| 416 | $client->AdGroupAdService()->get({selector => $adgroupad_selector}); | ||
| 417 | |||
| 418 | if ($page->get_totalNumEntries() > 0) { | ||
| 419 | foreach my $entry (@{$page->get_entries()}) { | ||
| 420 | #Do something with the results | ||
| 421 | } | ||
| 422 | } else { | ||
| 423 | print "No AdGroupAds found.\n"; | ||
| 424 | } | ||
| 425 | |||
| 426 | =head1 DESCRIPTION | ||
| 427 | |||
| 428 | Google::Ads::AdWords::Client is the main interface to the AdWords API. It takes | ||
| 429 | care of handling your API credentials, and exposes all of the underlying | ||
| 430 | services that make up the AdWords API. | ||
| 431 | |||
| 432 | Due to internal patching of the C<SOAP::WSDL> module, the | ||
| 433 | C<Google::Ads::AdWords::Client> module should be loaded before other | ||
| 434 | C<Google::Ads::> modules. A warning will occur if modules are loaded in the | ||
| 435 | wrong order. | ||
| 436 | |||
| 437 | =head1 ATTRIBUTES | ||
| 438 | |||
| 439 | Each of these attributes can be set via Google::Ads::AdWords::Client->new(). | ||
| 440 | Alternatively, there is a get_ and set_ method associated with each attribute | ||
| 441 | for retrieving or setting them dynamically. For example, the set_client_id() | ||
| 442 | allows you to change the value of the client_id attribute and get_client_id() | ||
| 443 | returns the current value of the attribute. | ||
| 444 | |||
| 445 | =head2 client_id | ||
| 446 | |||
| 447 | An optional 10 digit client id (with or without dashes) to specify the AdWords | ||
| 448 | account to act upon. | ||
| 449 | |||
| 450 | =head2 user_agent | ||
| 451 | |||
| 452 | A user-generated string used to identify your application. If nothing is | ||
| 453 | specified, "unknown" will be used instead. | ||
| 454 | |||
| 455 | =head2 developer_token | ||
| 456 | |||
| 457 | A string used to tie usage of the AdWords API to a specific AdWords manager | ||
| 458 | account. | ||
| 459 | |||
| 460 | The value should be a character string assigned to you by Google. You can | ||
| 461 | apply for a Developer Token by following the instructions at | ||
| 462 | |||
| 463 | https://developers.google.com/adwords/api/docs/signingup | ||
| 464 | |||
| 465 | =head2 version | ||
| 466 | |||
| 467 | The version of the AdWords API to use. The newest is the default. | ||
| 468 | |||
| 469 | =head2 alternate_url | ||
| 470 | |||
| 471 | The URL of an alternate AdWords API server to use. | ||
| 472 | |||
| 473 | The default value is C<https://adwords.google.com> | ||
| 474 | |||
| 475 | =head2 validate_only | ||
| 476 | |||
| 477 | If is set to "true" calls to services will only perform validation, the results | ||
| 478 | will be either empty response or a SOAP fault with the API error causing the | ||
| 479 | fault. | ||
| 480 | |||
| 481 | The default is "false". | ||
| 482 | |||
| 483 | =head2 partial_failure | ||
| 484 | |||
| 485 | If true, API will try to commit as many error free operations as possible and | ||
| 486 | report the other operations' errors. This flag is currently only supported by | ||
| 487 | the AdGroupCriterionService. | ||
| 488 | |||
| 489 | The default is "false". | ||
| 490 | |||
| 491 | =head2 reporting_config | ||
| 492 | |||
| 493 | The reporting configuration that controls additional options such as excluding | ||
| 494 | the report header or summary row. Only supported starting with | ||
| 495 | L<Google::Ads::AdWords::Reports::ReportingConfiguration:MIN_REPORT_CONFIGURATION_VERSION>. | ||
| 496 | |||
| 497 | =head2 die_on_faults | ||
| 498 | |||
| 499 | By default the client returns a L<SOAP::WSDL::SOAP::Typelib::Fault11> object | ||
| 500 | if an error has ocurred at the server side, however if this flag is set to true, | ||
| 501 | then the client will issue a die command on received SOAP faults. | ||
| 502 | |||
| 503 | The default is "false". | ||
| 504 | |||
| 505 | =head2 requests_count | ||
| 506 | |||
| 507 | Number of requests performed with this client so far. | ||
| 508 | |||
| 509 | =head2 failed_requests_count | ||
| 510 | |||
| 511 | Number of failed requests performed with this client so far. | ||
| 512 | |||
| 513 | =head2 operations_count | ||
| 514 | |||
| 515 | Number of operations made with this client so far. | ||
| 516 | |||
| 517 | =head2 requests_stats | ||
| 518 | |||
| 519 | An array of L<Google::Ads::AdWords::RequestStats> containing the statistics of | ||
| 520 | the last L<Google::Ads::AdWords::Constants:MAX_NUM_OF_REQUEST_STATS> requests. | ||
| 521 | |||
| 522 | =head2 last_request_stats | ||
| 523 | |||
| 524 | A L<Google::Ads::AdWords::RequestStats> containing the statistics the last | ||
| 525 | request performed by this client. | ||
| 526 | |||
| 527 | =head2 last_soap_request | ||
| 528 | |||
| 529 | A string containing the last SOAP request XML sent by this client. | ||
| 530 | |||
| 531 | =head2 last_soap_response | ||
| 532 | |||
| 533 | A string containing the last SOAP response XML sent by this client. | ||
| 534 | |||
| 535 | =head1 METHODS | ||
| 536 | |||
| 537 | =head2 new | ||
| 538 | |||
| 539 | Initializes a new Google::Ads::AdWords::Client object. | ||
| 540 | |||
| 541 | =head3 Parameters | ||
| 542 | |||
| 543 | new() takes parameters as a hash reference. | ||
| 544 | The attributes of this object can be populated in a number of ways: | ||
| 545 | |||
| 546 | =over | ||
| 547 | |||
| 548 | =item * | ||
| 549 | |||
| 550 | If the properties_file parameter is given, then properties are read from the | ||
| 551 | file at that path and the corresponding attributes are populated. | ||
| 552 | |||
| 553 | =item * | ||
| 554 | |||
| 555 | If no properties_file parameter is given, then the code checks to see if there | ||
| 556 | is a file named "adwords.properties" in the home directory of the current user. | ||
| 557 | If there is, then properties are read from there. | ||
| 558 | |||
| 559 | =item * | ||
| 560 | |||
| 561 | Any of the L</ATTRIBUTES> can be passed in as keys in the parameters hash | ||
| 562 | reference. If any attribute is explicitly passed in then it will override any | ||
| 563 | value for that attribute that might be in a properties file. | ||
| 564 | |||
| 565 | =back | ||
| 566 | |||
| 567 | =head3 Returns | ||
| 568 | |||
| 569 | A new Google::Ads::AdWords::Client object with the appropriate attributes set. | ||
| 570 | |||
| 571 | =head3 Exceptions | ||
| 572 | |||
| 573 | If a properties_file is passed in but the file cannot be read, the code will | ||
| 574 | die() with an error message describing the failure. | ||
| 575 | |||
| 576 | =head3 Example | ||
| 577 | |||
| 578 | # Basic use case. Attributes will be read from ~/adwords.properties file. | ||
| 579 | my $client = Google::Ads::AdWords::Client->new(); | ||
| 580 | |||
| 581 | # Most attributes from a custom properties file, but override client_id. | ||
| 582 | eval { | ||
| 583 | my $client = Google::Ads::AdWords::Client->new({ | ||
| 584 | properties_file => "/path/to/adwords.properties", | ||
| 585 | client_id => "123-456-7890", | ||
| 586 | }); | ||
| 587 | }; | ||
| 588 | if ($@) { | ||
| 589 | # The properties file couldn't be read; handle error as appropriate. | ||
| 590 | } | ||
| 591 | |||
| 592 | # Specify all attributes explicitly. The properties file will not override. | ||
| 593 | my $client = Google::Ads::AdWords::Client->new({ | ||
| 594 | client_id => "123-456-7890", | ||
| 595 | developer_token => "123xyzabc...", | ||
| 596 | user_agent => "My Sample Program", | ||
| 597 | }); | ||
| 598 | $client->get_oauth_2_applications_handler()->set_refresh_token('1/Abc...'); | ||
| 599 | |||
| 600 | =head2 set_die_on_faults | ||
| 601 | |||
| 602 | This module supports two approaches to handling SOAP faults (i.e. errors | ||
| 603 | returned by the underlying SOAP service). | ||
| 604 | |||
| 605 | One approach is to issue a die() with a description of the error when a SOAP | ||
| 606 | fault occurs. This die() would ideally be contained within an eval { }; block, | ||
| 607 | thereby emulating try { } / catch { } exception functionality in other | ||
| 608 | languages. | ||
| 609 | |||
| 610 | A different approach is to require developers to explicitly check for SOAP | ||
| 611 | faults being returned after each AdWords API method. This approach requires a | ||
| 612 | bit more work, but has the advantage of exposing the full details of the SOAP | ||
| 613 | fault, like the fault code. | ||
| 614 | |||
| 615 | Refer to the object L<SOAP::WSDL::SOAP::Typelib::Fault11> for more detail on | ||
| 616 | how faults get returned. | ||
| 617 | |||
| 618 | The default value is false, i.e. you must explicitly check for faults. | ||
| 619 | |||
| 620 | =head3 Parameters | ||
| 621 | |||
| 622 | A true value will cause this module to die() when a SOAP fault occurs. | ||
| 623 | |||
| 624 | A false value will supress this die(). This is the default behavior. | ||
| 625 | |||
| 626 | =head3 Returns | ||
| 627 | |||
| 628 | The input parameter is returned. | ||
| 629 | |||
| 630 | =head3 Example | ||
| 631 | |||
| 632 | # $client is a Google::Ads::AdWords::Client object. | ||
| 633 | |||
| 634 | # Enable die()ing on faults. | ||
| 635 | $client->set_die_on_faults(1); | ||
| 636 | eval { | ||
| 637 | my $response = $client->AdGroupAdService->mutate($mutate_params); | ||
| 638 | }; | ||
| 639 | if ($@) { | ||
| 640 | # Do something with the error information in $@. | ||
| 641 | } | ||
| 642 | |||
| 643 | # Default behavior. | ||
| 644 | $client->set_die_on_faults(0); | ||
| 645 | my $response = $client->AdGroupAdService->mutate($mutate_params); | ||
| 646 | if ($response->isa("SOAP::WSDL::SOAP::Typelib::Fault11")) { | ||
| 647 | my $code = $response->get_faultcode() || ''; | ||
| 648 | my $description = $response->get_faultstring() || ''; | ||
| 649 | my $actor = $response->get_faultactor() || ''; | ||
| 650 | my $detail = $response->get_faultdetail() || ''; | ||
| 651 | |||
| 652 | # Do something with this error information. | ||
| 653 | } | ||
| 654 | |||
| 655 | =head2 get_die_on_faults | ||
| 656 | |||
| 657 | =head3 Returns | ||
| 658 | |||
| 659 | A true or false value indicating whether the Google::Ads::AdWords::Client | ||
| 660 | instance is set to die() on SOAP faults. | ||
| 661 | |||
| 662 | =head2 {ServiceName} | ||
| 663 | |||
| 664 | The client object contains a method for every service provided by the API. | ||
| 665 | So for example it can invoked as $client->AdGroupService() and it will return | ||
| 666 | an object of type | ||
| 667 | L<Google::Ads::AdWords::v201809::AdGroupService::AdGroupServiceInterfacePort> | ||
| 668 | when using version v201809 of the API. | ||
| 669 | For a list of all available services please refer to | ||
| 670 | http://developers.google.com/adwords/api/docs and for examples on | ||
| 671 | how to invoke the services please refer to scripts in the examples folder. | ||
| 672 | |||
| 673 | =head2 get_oauth_2_applications_handler | ||
| 674 | |||
| 675 | Returns the OAuth2 for Web/Installed applications authorization handler | ||
| 676 | attached to the client, for programmatically setting/overriding its properties. | ||
| 677 | |||
| 678 | $client->get_oauth_2_applications_handler()->set_client_id('client-id'); | ||
| 679 | $client->get_oauth_2_applications_handler()->set_client_secret('client-secret'); | ||
| 680 | $client->get_oauth_2_applications_handler()->set_access_token('access-token'); | ||
| 681 | $client->get_oauth_2_applications_handler()->set_refresh_token('refresh-token'); | ||
| 682 | $client->get_oauth_2_applications_handler()->set_access_type('access-type'); | ||
| 683 | $client->get_oauth_2_applications_handler()->set_prompt('prompt'); | ||
| 684 | $client->get_oauth_2_applications_handler()->set_redirect_uri('redirect-url'); | ||
| 685 | |||
| 686 | Refer to L<Google::Ads::AdWords::OAuth2ApplicationsHandler> for more details. | ||
| 687 | |||
| 688 | =head2 get_oauth_2_service_accounts_handler | ||
| 689 | |||
| 690 | Returns the OAuth2 authorization handler attached to the client, for | ||
| 691 | programmatically setting/overriding its specific properties. | ||
| 692 | |||
| 693 | $client->get_oauth_2_service_accounts_handler()->set_client_id('email'); | ||
| 694 | $client->get_oauth_2_service_accounts_handler()->set_email_address('email'); | ||
| 695 | $client->get_oauth_2_service_accounts_handler()-> | ||
| 696 | set_delegated_email_address('delegated-email'); | ||
| 697 | $client->get_oauth_2_service_accounts_handler()-> | ||
| 698 | set_pem_file('path-to-certificate'); | ||
| 699 | $client->get_oauth_2_service_accounts_handler()->set_display_name('email'); | ||
| 700 | |||
| 701 | Refer to L<Google::Ads::AdWords::OAuth2ApplicationsHandler> for more details. | ||
| 702 | |||
| 703 | =head2 __setup_SSL (Private) | ||
| 704 | |||
| 705 | Setups IO::Socket::SSL and Crypt::SSLeay environment variables to work with | ||
| 706 | SSL certificate validation. | ||
| 707 | |||
| 708 | =head3 Parameters | ||
| 709 | |||
| 710 | The path to the certificate authorites folder and the path to the certificate | ||
| 711 | authorites file. Either can be null. | ||
| 712 | |||
| 713 | =head3 Returns | ||
| 714 | |||
| 715 | Nothing. | ||
| 716 | |||
| 717 | =head2 __parse_properties_file (Private) | ||
| 718 | |||
| 719 | =head3 Parameters | ||
| 720 | |||
| 721 | The path to a properties file on disk. The data in the file should be in the | ||
| 722 | following format: | ||
| 723 | |||
| 724 | key1=value1 | ||
| 725 | key2=value2 | ||
| 726 | |||
| 727 | =head3 Returns | ||
| 728 | |||
| 729 | A hash corresponding to the keys and values in the properties file. | ||
| 730 | |||
| 731 | =head3 Exceptions | ||
| 732 | |||
| 733 | die()s with an error message if the properties file could not be read. | ||
| 734 | |||
| 735 | =head2 _get_header (Protected) | ||
| 736 | |||
| 737 | Used by the L<Google::Ads::AdWords::Serializer> class to get a valid request | ||
| 738 | header corresponding to the current credentials in this | ||
| 739 | Google::Ads::AdWords::Client instance. | ||
| 740 | |||
| 741 | =head3 Returns | ||
| 742 | |||
| 743 | A hash reference with credentials corresponding to the values needed to be | ||
| 744 | included in the request header. | ||
| 745 | |||
| 746 | =head2 _auth_handler (Protected) | ||
| 747 | |||
| 748 | Retrieves the active AuthHandler. All handlers are checked in the order | ||
| 749 | OAuth2 Applications -> OAuth2 Service Accounts. | ||
| 750 | |||
| 751 | =head3 Returns | ||
| 752 | |||
| 753 | An implementation of L<Google::Ads::Common::AuthHandlerInterface>. | ||
| 754 | |||
| 755 | =head1 LICENSE AND COPYRIGHT | ||
| 756 | |||
| 757 | Copyright 2011 Google Inc. | ||
| 758 | |||
| 759 | Licensed under the Apache License, Version 2.0 (the "License"); | ||
| 760 | you may not use this file except in compliance with the License. | ||
| 761 | You may obtain a copy of the License at | ||
| 762 | |||
| 763 | http://www.apache.org/licenses/LICENSE-2.0 | ||
| 764 | |||
| 765 | Unless required by applicable law or agreed to in writing, software | ||
| 766 | distributed under the License is distributed on an "AS IS" BASIS, | ||
| 767 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
| 768 | See the License for the specific language governing permissions and | ||
| 769 | limitations under the License. | ||
| 770 | |||
| 771 | =head1 REPOSITORY INFORMATION | ||
| 772 | |||
| 773 | $Rev: $ | ||
| 774 | $LastChangedBy: $ | ||
| 775 | $Id: $ | ||
| 776 | |||
| 777 | =cut | ||