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