Google::Ads::AdWords::Client |
Google::Ads::AdWords::Client
use Google::Ads::AdWords::Client;
my $client = Google::Ads::AdWords::Client->new();
my $adGroupId = "12345678";
my $adgroupad_selector = Google::Ads::AdWords::v201109::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"; }
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.
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_password()
returns the current value of the password attribute.
The email address of a Google Account. This account could correspond to either an AdWords MCC account or a normal AdWords account.
The password associated with the Google Account given in email.
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.
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.
A string used to tie usage of the AdWords API to a specific MCC account.
In the Sandbox environment, the value should be
email++CUR
i.e. the email value, two plus signs, and then a currency code like USD
.
In the Production environment, 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
The version of the AdWords API to use. Currently v201109
is the default and
only supported version.
The URL of an alternate AdWords API server to use. The most common use case would be to specify the address of the Sandbox server.
The default value is https://adwords.google.com
To access the Sandbox, use https://adwords-sandbox.google.com
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".
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".
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".
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.
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.
The default is "true".
By default the client returns a the SOAP::WSDL::SOAP::Typelib::Fault11 manpage 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".
The OAuth consumer key and secret pair to use when your client is OAuth enabled. Refer to http://code.google.com/apis/accounts/docs/RegistrationForWebAppsAuto.html on how to obtain these values.
The OAuth access token and secret pair to use when your client is OAuth enabled. Refer to the methods the get_oauth_authorization_url manpage & the upgrade_oauth_token manpage to generate these pair of keys.
Used to identify your application when requesting access to the user to use his account via OAuth, refer to the get_oauth_authorization_url manpage for more information.
Implementation of the Google::Ads::Common::OAuthHandler manpage to handle all the required logic to access AdWords API authorized via OAuth. This attribute can be overriden to use your own implementation, it defaults to the Google::Ads::AdWords::OAuthHandler manpage.
Number of requests performed with this client so far.
Number of failed requests performed with this client so far.
Number of API units consumed by requests made with this client so far.
Number of operations made with this client so far.
An array of the Google::Ads::AdWords::RequestStats manpage containing the statistics of the last the Google::Ads::AdWords::Constants:MAX_NUM_OF_REQUEST_STATS manpage requests.
A the Google::Ads::AdWords::RequestStats manpage containing the statistics the last request performed by this client.
Initializes a new Google::Ads::AdWords::Client object.
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.
A new Google::Ads::AdWords::Client object with the appropriate attributes set.
If a properties_file is passed in but the file cannot be read, the code will
die()
with an error message describing the failure.
# 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", });
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
the Google::Ads::AdWords::v201109::AdGroupService::AdGroupServiceInterfacePort manpage
when using version v201109 of the API.
For a list of all available services please refer to
http://code.google.com/apis/adwords/docs/ and for examples on
how to invoke the services please refer to scripts in the examples folder.
Setups IO::Socket::SSL and Crypt::SSLeay enviroment variables to work with SSL certificate validation.
The path to the certificate authorites folder and the path to the certificate authorites file. Either can be null.
Nothing.
The path to a properties file on disk. The data in the file should be in the following format:
key1=value1 key2=value2
A hash corresponding to the keys and values in the properties file.
die()s with an error message if the properties file could not be read.
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 the SOAP::WSDL::SOAP::Typelib::Fault11 manpage for more detail on how faults get returned.
The default value is false, i.e. you must explicitly check for faults.
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.
The input parameter is returned.
# $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. }
A true or false value indicating whether the Google::Ads::AdWords::Client
instance is set to die()
on SOAP faults.
Used by the the Google::Ads::AdWords::Serializer manpage class to get a valid request header corresponding to the current credentials in this Google::Ads::AdWords::Client instance.
A hash reference with credentials corresponding to the values needed to be included in the request header.
Uses Google::Ads::Common::AuthToken to generate a token for use as AdWords API credentials. This method makes use of an in-memory cache to avoid generating a new token if a previously-generated one is still valid.
An auth token which can be used as AdWords API credentials.
If this instance of Google::Ads::AdWords::Client is set to die on faults, then
this method will die()
with a description of the HTTP error if it can't obtain
an auth token with the current email and password.
If die()ing on faults isn't active, then a message will be displayed with warn()
if the token can't be obtained.
head2 __make_auth_token_cache_key (Private)
An internal method used to generate a lookup key for retrieving a previously cached auth token.
The value of a lookup key, based on a combination of the current email and password.
Retrieves a fresh copy the attached OAuthHandler with the latest Client OAuth properties set.
The OAuth associated OAuth handler.
Used to generate a request token and return an authorization URL that should be presented to the user to authorize the token.
A callback URL to which the user will be redirect after granting access. A value "oob" out-of-band can be passed to have the server print out the verification code in screen.
The URL that should be presented to the user to grant access to the application.
Used to upgrade a request token (generated by the the get_oauth_authorization_url manpage) to an access token, that can then be used to access the API via OAuth.
A verification code returned by the server.
Copyright 2011 Google Inc.
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.
Jeffrey Posnick <api.jeffy at gmail.com>
David Torres <api.davidtorres at gmail.com>
$Rev: $ $LastChangedBy: $ $Id: $
Google::Ads::AdWords::Client |