lib/Google/Ads/AdWords/Client.pm

filter: Statementstmt 86.6% 13 / 15 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 5 / 5 Podpod n/a totaltotal 90.0% 18 / 20 CC 1 SCAR 0.6
CC
1
Cov
87%
BEGIN
1.3
BEGIN
1.0
BEGIN
1.0
CRAP 1.1
« blib/lib/Google/Ads/Common/XPathSAXParser.pm ↑ Summary lib/Google/Ads/AdWords/Constants.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 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
« blib/lib/Google/Ads/Common/XPathSAXParser.pm ↑ Summary lib/Google/Ads/AdWords/Constants.pm »