Google::Adwords::Service - Base class for the Service modules

Google-Adwords documentation Contained in the Google-Adwords distribution.

Index

Code Index:

NAME

Top

Google::Adwords::Service - Base class for the Service modules

VERSION

Top

This documentation refers to Google::Adwords::Service version 0.16

DESCRIPTION

Top

This module is not supposed to be used directly. Use the child Service modules. See the Google::Adwords documentation for the list of available child Service modules.

METHODS

Top

These accessors/methods are available across all the child Service modules

new()

Description

    Creates a new Google::Adwords::*Service object

Usage

    my $service = Google::Adwords::CampaignService->new();

Parameters

    NONE

Returns

    A Google::Adwords::*Service object

email()

    Set your Google Adwords account name (your email address). This 
    value should be set before calling any other API methods

password()

    Set your Google Adwords account password. This 
    value should be set before calling any other API methods

developerToken()

    Set your Google Adwords developer token. This 
    value should be set before calling any other API methods

applicationToken()

    Set your Google Adwords application token. This 
    value should be set before calling any other API methods

clientEmail()

    Use this if you have a MCC (My Client Center) account. Set the actual
    client email which will be used for the API calls.

clientCustomerId()

    Use this if you have a MCC (My Client Center) account. Set the actual
    client customerid which will be used for the API calls.
    One of clientEmail and clientCustomerId must be set but NOT both.

useragent()

    Set this to an arbitrary string that identifies the customer sending the
    request. Default value is "Google::Adwords $VERSION"

api_version()

    The Adwords API version you want to use. In format 'v*'. So, to use 
    version 7 of the API, set this to a value of 'v7'. Default value is 'v9'.

use_sandbox()

    If you do $obj->use_sandbox(1), then this module will use the 
    sandbox for all API calls.

timeout()

    Set the SOAP timeout value in seconds. Default value is 35 seconds.

debug()

    Use $obj->debug(1) if you want to trace the request/response XML

api_version()

    Returns version information for the Adwords API

factory_class_hook()

Specifies a reference to a subroutine. The subroutine will be called whenever the service is about to create a new object. It can be used to alter the class into which new objects are blessed. Default is undef.

The subroutine is passed the default class name, and a reference to the hash of values that will be used to initialise the object. It should return the class name it wishes to use. The class name returned should be a subclass of the original class. If it returns false, the original class name will be used.

For example:

  $service->factory_class_hook( sub {
      my $class_name = shift;
      # only alter Campaign objects
      return unless $class_name eq 'Google::Adwords::Campaign';
      return "My::Adwords::WhizzoCampaign";
  } );

The following accessors are available after an API call is done. These give information about the response

requestId()

Get the unique ID that identifies this request.

operations()

number of operations in the request

units()

number of quota units the request used

responseTime()

elapsed time between the web service receiving the request and sending the response

DEPENDENCIES

Top

* SOAP::Lite
* Class::Accessor::Chained

AUTHOR

Top

Rohan Almeida <rohan@almeida.in>

LICENSE AND COPYRIGHT

Top

Copyright (c) 2006 Rohan Almeida <rohan@almeida.in>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Google-Adwords documentation Contained in the Google-Adwords distribution. 
package Google::Adwords::Service;
use strict;
use warnings;

use version; our $VERSION = qv('0.16');

use base qw/ Class::Accessor::Chained Google::Adwords /;
use SOAP::Lite;
use Readonly;

Readonly my $default_api_version => 'v13';
Readonly my $user_agent          => "Google::Adwords v1.14";
Readonly my $endpoint            => 'https://adwords.google.com/api/adwords';
Readonly my $endpoint_sandbox    => 'https://sandbox.google.com/api/adwords';
Readonly my $default_timeout => 35;    # HTTP timeout in seconds

__PACKAGE__->mk_accessors(
    qw/
        email
        password
        developerToken
        applicationToken
        useragent
        api_version
        use_sandbox
        clientEmail
        clientCustomerId
        timeout
        debug
        requestId
        operations
        units
        responseTime
        factory_class_hook
        /
);

### CLASS METHOD ##################################################
# Usage      : Google::Adwords::Service->new();
# Purpose    : ????
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : This method should never be called directly
# See Also   : n/a
####################################################################
sub new
{
    my $class = shift;

    my $self = {};

    # don't use sandbox by default
    $self->{'use_sandbox'} = 0;

    # no debugging by default
    $self->{'debug'} = 0;

    # set default timeout
    $self->{'timeout'} = $default_timeout;

    # default useragent
    $self->{'useragent'} = $user_agent;

    # Adwords API version
    $self->{api_version} = $default_api_version;

    bless $self, $class;
    return $self;
} # end sub new

### INTERNAL UTILITY #################################################
# Usage      : ????
# Purpose    : ????
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _get_soap_headers
{
    my ($self) = @_;

    my @headers = (
        SOAP::Header->name("email")->value( $self->email )->type(''),
        SOAP::Header->name("password")->value( $self->password )->type(''),
        SOAP::Header->name("useragent")->value( $self->useragent )->type(''),
        SOAP::Header->name("developerToken")->value( $self->developerToken )
            ->type(''),
        SOAP::Header->name("applicationToken")
            ->value( $self->applicationToken )->type(''),
    );

    # check for clientEmail header
    if ( defined $self->clientEmail )
    {
        push @headers,
            SOAP::Header->name("clientEmail")->value( $self->clientEmail )
            ->type('');
    }

    # or the clientCustomerId header
    if ( defined $self->clientCustomerId )
    {
        push @headers,
            SOAP::Header->name("clientCustomerId")
            ->value( $self->clientCustomerId )->type('');
    }

    return @headers;
} # end sub _get_soap_headers

### INTERNAL UTILITY ##############################################
# Usage      : $self->_endpoint();
# Purpose    : Return the endpoint URL to use
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _endpoint
{
    my ($self) = @_;

    return $self->use_sandbox
        ? $endpoint_sandbox . '/' . $self->api_version
        : $endpoint . '/' . $self->api_version;
}

### INTERNAL UTILITY ##################################################
# Usage      :
#   $service = $obj->_create_soap_service({
#       service => $service_name,
#   });
# Purpose    : Create the SOAP service
# Returns    : $service => SOAP::Lite object
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _create_soap_service
{
    my ( $self, $args_ref ) = @_;

    my $endpoint = $self->_endpoint . '/' . $args_ref->{'service'};
    my $service = SOAP::Lite->proxy( $endpoint, timeout => $self->timeout );

    if ( $self->debug )
    {
        SOAP::Lite->import( +trace => 'debug' );
    }

    return $service;
}

### INTERNAL UTILITY ####################################################
# Usage      :
#   $result = $self->_call({
#       service => $service,
#       method => $method_name,
#       params => $params_ref, (optional)
#   );
# Purpose    : Call the SOAP service
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _call
{
    my ( $self, $args_ref ) = @_;

    # get the headers
    my @headers = $self->_get_soap_headers();

    # create the method
    my $method = SOAP::Data->name( $args_ref->{'method'} );

    # Blank out the earlier response header values
    $self->requestId('');
    $self->responseTime('');
    $self->operations('');
    $self->units('');

    # set uri endpoint if requested
    if ( ( defined $args_ref->{'with_uri'} ) && ( $args_ref->{'with_uri'} ) )
    {
        $method->uri( $endpoint . '/' . $self->api_version )->prefix('');
    }

    # call the SOAP service
    my $result;
    eval {
        $result = $args_ref->{'service'}->call(
            $method => @headers,
            @{ $args_ref->{'params'} },
        );
    };
    if ($@)
    {

        # TODO: return an error object
        die "Error: $@\n";
    }

    # check for SOAP faults
    if ( $result->fault )
    {
        die "Fault Code: "
            . $result->faultcode . "\n"
            . "Fault Description: "
            . $result->faultstring . "\n";
    }

    # get the SOAP response headers
    for (qw/requestId responseTime operations units/)
    {
        $self->$_( $result->headerof("//$_")->value );
    }

    return $result;
} # end sub _call

### INTERNAL UTILITY ###################################################
# Usage      :
#   $result = $self->_create_service_and_call({
#       service => $service_name,
#       method => $method_name,
#       params => \@params,
#   });
# Purpose    : ????
# Returns    : ????
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _create_service_and_call
{
    my ( $self, $args_ref ) = @_;

    # create the SOAP service
    my $service = $self->_create_soap_service(
        { service => $args_ref->{'service'}, } );

    # call the service
    my $result = $self->_call(
        {
            service  => $service,
            method   => $args_ref->{'method'},
            params   => $args_ref->{'params'},
            with_uri => $args_ref->{'with_uri'},
        }
    );

    return $result;
} # end sub _create_service_and_call

### INTERNAL UTILITY ####################################################
# Usage      : $obj = $self->_create_object_from_hash($hashref, $class_name);
# Purpose    : Create a object from a hash ref
# Returns    : $obj => an object of type $class_name
# Parameters : ????
# Throws     : no exceptions
# Comments   : none
# See Also   : n/a
#######################################################################
sub _create_object_from_hash
{
    my ( $self, $hashref, $class_name ) = @_;

    # XXX wtf?
    if ( ref $hashref ne 'HASH' )
    {
        $hashref = {};
    }

    if ( my $hook = $self->factory_class_hook )
    {
        $class_name = $hook->( $class_name, $hashref ) || $class_name;
    }

    my $obj = $class_name->new($hashref);
    return $obj;
} # end sub _create_object_from_hash

1;