NAME

Google::Ads::AdWords::Client

SYNOPSIS

use Google::Ads::AdWords::Client;

my $client = Google::Ads::AdWords::Client->new();

my $adGroupId = "12345678";

my $adgroupad_selector =
    Google::Ads::AdWords::v201402::Types::AdGroupAdSelector->new({
      adGroupIds => [$adGroupId]
    });

my $page =
    $client->AdGroupAdService()->get({selector => $adgroupad_selector});

if ($page->get_totalNumEntries() > 0) {
  foreach my $entry (@{$page->get_entries()}) {
    #Do something with the results
  }
} else {
  print "No AdGroupAds found.\n";
}

DESCRIPTION

Google::Ads::AdWords::Client is the main interface to the AdWords API. It takes care of handling your API credentials, and exposes all of the underlying services that make up the AdWords API.

Due to internal patching of the SOAP::WSDL module, the Google::Ads::AdWords::Client module should be loaded before other Google::Ads:: modules. A warning will occur if modules are loaded in the wrong order.

ATTRIBUTES

Each of these attributes can be set via Google::Ads::AdWords::Client->new(). Alternatively, there is a get_ and set_ method associated with each attribute for retrieving or setting them dynamically. For example, the set_client_id() allows you to change the value of the client_id attribute and get_client_id() returns the current value of the attribute.

email

The email address of a Google Account. This account could correspond to either an AdWords MCC account or a normal AdWords account.

This property is demeed deprecated and should not be referenced. Instead use $client->get_auth_token_handler()->get_email().

password

The password associated with the Google Account given in "email".

This property is demeed deprecated and should not be referenced. Instead use $client->get_auth_token_handler()->get_password().

client_id

If the Google Account given in "email" is an MCC account, you can specify the AdWords account underneath that MCC account to act upon using client_id. The value could be either a login email address or a 10 digit client id.

user_agent

A user-generated string used to identify your application. If nothing is specified, the name of your script (i.e. $0) will be used instead.

developer_token

A string used to tie usage of the AdWords API to a specific MCC account.

The value should be a character string assigned to you by Google. This string will tie AdWords API usage to your MCC account for billing purposes. You can apply for a Developer Token at

https://adwords.google.com/select/ApiWelcome

version

The version of the AdWords API to use. Currently v201402 is the default and only supported version.

alternate_url

The URL of an alternate AdWords API server to use.

The default value is https://adwords.google.com

validate_only

If is set to "true" calls to services will only perform validation, the results will be either empty response or a SOAP fault with the API error causing the fault.

The default is "false".

partial_failure

If true, API will try to commit as many error free operations as possible and report the other operations' errors. This flag is currently only supported by the AdGroupCriterionService.

The default is "false".

auth_server

The server to use when making ClientLogin or OAuth requests. This normally doesn't need to be changed from the default value.

The default is "https://www.google.com".

auth_token

Use to manually set an existing AuthToken. If not set the client will use the auth_server to generate a token for you based on the email and password provided.

This property is demeed deprecated and should not be referenced. Instead use $client->get_auth_token_handler()->get_auth_token().

use_auth_token_cache

By default the client keeps generated auth tokens for 23 hours in a local cache, if this property is set to false then is your responsability to manually refresh tokens either setting the auth_token property or calling refresh_auth_token to auto generate a new one.

This property is demeed deprecated and should not be referenced. There is no replacement for this property since the auth token caching is now managed differently.

die_on_faults

By default the client returns a SOAP::WSDL::SOAP::Typelib::Fault11 object if an error has ocurred at the server side, however if this flag is set to true, then the client will issue a die command on received SOAP faults.

The default is "false".

requests_count

Number of requests performed with this client so far.

failed_requests_count

Number of failed requests performed with this client so far.

operations_count

Number of operations made with this client so far.

requests_stats

An array of Google::Ads::AdWords::RequestStats containing the statistics of the last Google::Ads::AdWords::Constants:MAX_NUM_OF_REQUEST_STATS requests.

last_request_stats

A Google::Ads::AdWords::RequestStats containing the statistics the last request performed by this client.

last_soap_request

A string containing the last SOAP request XML sent by this client.

last_soap_response

A string containing the last SOAP response XML sent by this client.

METHODS

new

Initializes a new Google::Ads::AdWords::Client object.

Parameters

new() takes parameters as a hash reference. The attributes of this object can be populated in a number of ways:

If the properties_file parameter is given, then properties are read from the file at that path and the corresponding attributes are populated.
If no properties_file parameter is given, then the code checks to see if there is a file named "adwords.properties" in the home directory of the current user. If there is, then properties are read from there.
Any of the "ATTRIBUTES" can be passed in as keys in the parameters hash reference. If any attribute is explicitly passed in then it will override any value for that attribute that might be in a properties file.

Returns

A new Google::Ads::AdWords::Client object with the appropriate attributes set.

Exceptions

If a properties_file is passed in but the file cannot be read, the code will die() with an error message describing the failure.

Example

# Basic use case. Attributes will be read from ~/adwords.properties file.
my $client = Google::Ads::AdWords::Client->new();

# Most attributes from a custom properties file, but override email.
eval {
  my $client = Google::Ads::AdWords::Client->new({
    properties_file => "/path/to/adwords.properties",
    email => "user\@domain.com",
  });
};
if ($@) {
  # The properties file couldn't be read; handle error as appropriate.
}

# Specify all attributes explicitly. The properties file will not override.
my $client = Google::Ads::AdWords::Client->new({
  email => "user\@domain.com",
  password => "my_password",
  client_id => "client_1+user\@domain.com",
  developer_token => "user\@domain.com++USD",
  user_agent => "My Sample Program",
});

set_die_on_faults

This module supports two approaches to handling SOAP faults (i.e. errors returned by the underlying SOAP service).

One approach is to issue a die() with a description of the error when a SOAP fault occurs. This die() would ideally be contained within an eval { }; block, thereby emulating try { } / catch { } exception functionality in other languages.

A different approach is to require developers to explicitly check for SOAP faults being returned after each AdWords API method. This approach requires a bit more work, but has the advantage of exposing the full details of the SOAP fault, like the fault code.

Refer to the object SOAP::WSDL::SOAP::Typelib::Fault11 for more detail on how faults get returned.

The default value is false, i.e. you must explicitly check for faults.

Parameters

A true value will cause this module to die() when a SOAP fault occurs.

A false value will supress this die(). This is the default behavior.

Returns

The input parameter is returned.

Example

# $client is a Google::Ads::AdWords::Client object.

# Enable die()ing on faults.
$client->set_die_on_faults(1);
eval {
  my $response = $client->AdGroupAdService->mutate($mutate_params);
};
if ($@) {
  # Do something with the error information in $@.
}

# Default behavior.
$client->set_die_on_faults(0);
my $response = $client->AdGroupAdService->mutate($mutate_params);
if ($response->isa("SOAP::WSDL::SOAP::Typelib::Fault11")) {
  my $code = $response->get_faultcode() || '';
  my $description = $response->get_faultstring() || '';
  my $actor = $response->get_faultactor() || '';
  my $detail = $response->get_faultdetail() || '';

  # Do something with this error information.
}

get_die_on_faults

Returns

A true or false value indicating whether the Google::Ads::AdWords::Client instance is set to die() on SOAP faults.

{ServiceName}

The client object contains a method for every service provided by the API. So for example it can invoked as $client->AdGroupService() and it will return an object of type Google::Ads::AdWords::v201402::AdGroupService::AdGroupServiceInterfacePort when using version v201402 of the API. For a list of all available services please refer to http://developers.google.com/adwords/api/docs and for examples on how to invoke the services please refer to scripts in the examples folder.

get_oauth_2_applications_handler

Returns the OAuth2 for Web/Installed applications authorization handler attached to the client, for programmatically setting/overriding its properties.

$client->get_oauth_2_applications_handler()->set_client_id('client-id'); $client->get_oauth_2_applications_handler()->set_client_secret('client-secret'); $client->get_oauth_2_applications_handler()->set_access_token('access-token'); $client->get_oauth_2_applications_handler()->set_refresh_token('refresh-token'); $client->get_oauth_2_applications_handler()->set_access_type('access-type'); $client->get_oauth_2_applications_handler()->set_approval_prompt('prompt'); $client->get_oauth_2_applications_handler()->set_redirect_uri('redirect-url');

Refer to Google::Ads::AdWords::OAuth2ApplicationsHandler for more details.

get_oauth_2_service_accounts_handler

Returns the OAuth2 authorization handler attached to the client, for programmatically setting/overriding its specific properties.

$client->get_oauth_2_service_accounts_handler()->set_client_id('email'); $client->get_oauth_2_service_accounts_handler()->set_email_address('email'); $client->get_oauth_2_service_accounts_handler()-> set_delegated_email_address('delegated-email'); $client->get_oauth_2_service_accounts_handler()-> set_pem_file('path-to-certificate'); $client->get_oauth_2_service_accounts_handler()->set_display_name('email');

Refer to Google::Ads::AdWords::OAuth2ApplicationsHandler for more details.

get_auth_token_handler

Returns the ClientLogin authorization handler attached to the client, for manully setting its specific properties.

$client->get_auth_token_handler()->set_email('email'); $client->get_auth_token_handler()->set_password('email');

Refer to Google::Ads::AdWords::AuthTokenHandler for more details.

__setup_SSL (Private)

Setups IO::Socket::SSL and Crypt::SSLeay enviroment variables to work with SSL certificate validation.

Parameters

The path to the certificate authorites folder and the path to the certificate authorites file. Either can be null.

Returns

Nothing.

__parse_properties_file (Private)

Parameters

The path to a properties file on disk. The data in the file should be in the following format:

key1=value1
key2=value2

Returns

A hash corresponding to the keys and values in the properties file.

Exceptions

die()s with an error message if the properties file could not be read.

_get_header (Protected)

Used by the Google::Ads::AdWords::Serializer class to get a valid request header corresponding to the current credentials in this Google::Ads::AdWords::Client instance.

Returns

A hash reference with credentials corresponding to the values needed to be included in the request header.

_auth_handler (Protected)

Retrieves the active AuthHandler. All handlers are checked in the order OAuth2 Applications -> OAuth2 Service Accounts -> AuthToken, given preference of OAuth2 over AuthToken.

Returns

An implementation of Google::Ads::Common::AuthHandlerInterface.

LICENSE AND COPYRIGHT

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

AUTHOR

Jeffrey Posnick <api.jeffy at gmail.com>

David Torres <david.t at google.com>

REPOSITORY INFORMATION

$Rev: $
$LastChangedBy: $
$Id: $

To install Google::Ads::AdWords::Client, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Google::Ads::AdWords::Client

CPAN shell

perl -MCPAN -e shell
install Google::Ads::AdWords::Client

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

email

password

client_id

user_agent

developer_token

version

alternate_url

validate_only

partial_failure

auth_server

auth_token

use_auth_token_cache

die_on_faults

requests_count

failed_requests_count

operations_count

requests_stats

last_request_stats

last_soap_request

last_soap_response

METHODS

new

Parameters

Returns

Exceptions

Example

set_die_on_faults

Parameters

Returns

Example

get_die_on_faults

Returns

{ServiceName}

get_oauth_2_applications_handler

get_oauth_2_service_accounts_handler

get_auth_token_handler

__setup_SSL (Private)

Parameters

Returns

__parse_properties_file (Private)

Parameters

Returns

Exceptions

_get_header (Protected)

Returns

_auth_handler (Protected)

Returns

LICENSE AND COPYRIGHT

AUTHOR

REPOSITORY INFORMATION

Module Install Instructions