AdWords API Perl Client Library ================================================================ Google's AdWords services lets developers design computer programs that interact directly with the AdWords platform. With these applications, advertisers and third parties can more efficiently -- and creatively -- manage their large or complex AdWords accounts and campaigns. The AdWords API Perl Client Library makes it easier to write Perl clients to programmatically access AdWords accounts. One of the main features of this client library is that it hides SOAP layer from end user, which makes it much more easier to interact with API. The outgoing and incoming SOAP messages can be monitored and logged on demand. The backbone of the client library is based on the SOAP::WSDL module. It handles the serialization/de-serialization, transport, and generation of classes for the entities defined in the AdWords API WSDLs. SOAP::WSDL, in turn, uses SOAP::Lite under the hood for some operations. More information about compatibility can be found in the Perl Compatibility section of this README. The complete documentation for AdWords API is available at https://developers.google.com/adwords/api/. What's in the client library? ----------------------------- The client library provides full access to all the functionality of the AdWords API web services plus more. It includes: - Data classes: The client library provides all the necessary data classes. For example, it provides the Campaign data class for encapsulating campaign data. These classes are generated automatically from WSDLs and found under Google::Ads:AdWords::{API VERSION}. - Client class: The Google::Ads::AdWords::Client class provides methods for setting credentials for accessing AdWords accounts as well as for creating instances of the AdWords Service classes. - Helpful utilities: The utilities located under "Google::Ads::Common" help you manage handle API errors, manage images, fetch reports and others. - Logging class: This class provides simple methods for logging the SOAP XML messages of all requests and responses. - Examples: The Perl client library comes with code examples in the "examples/" directory. We encourage you to use code examples to get started writing your own application. All the code examples are runnable out of the box, but you will have to set your credentials in "~/adwords.properties" and you may be required to insert object IDs where you see "INSERT_***_HERE". You must specify the clientCustomerId HTTP header for most services, so make sure you set the clientId in "~/adwords.properties" to a valid customer ID. See the Basic Concepts guide for more details about headers: https://developers.google.com/adwords/api/docs/guides/basic-concepts#request_headers How do I start? --------------- 1) Make sure you have Perl 5.14 or later installed. More information on Perl can be found at http://www.perl.org/. If you are installing in Windows read the important notes in the next section. 2) From this directory, run perl Build.PL to generate your Build file. This relies on having Module::Build pre-installed. Some warnings might be print out when running this command, continue with the installation. 3) The client library has a number of dependencies which are defined in the Build.PL script. If you are missing any modules, you'll receive a warning in step 2. You can install any dependencies manually using the CPAN shell (http://search.cpan.org/~andk/CPAN-1.9304/lib/CPAN.pm) or automatically by running (sudo) perl Build installdeps Note 1: Make sure Module::Build >= 0.36 is installed so you can use installdeps. Note 2: In certain Linux installations you'll need to install openssl first. Note 3: For Windows, follow the instructions under "Windows Installation" before starting this step. 4) Install this module, making use of the Build script generated in step 2: perl Build (sudo) perl Build install 5) Sign up for a Google Account, if you don't already have one, at https://www.google.com/accounts/NewAccount 6) Copy the sample 'adwords.properties' file to your home directory, and edit it to reflect the credentials for your Google Account. 7) Try running the code examples in the 'examples' directory. 8) Read over the documentation in 'docs/' to familiarize yourself with the various classes and methods in the client library. Windows Installation -------------------- The library is only supported on Windows for ActivePerl 5.14+ x86 (32bit version). Before following the "How do I start?" steps: 1) Install the MinGW module by executing 'ppm install MinGW' in the command prompt. 2) Install OpenSSL, which can be found at: https://code.google.com/p/openssl-for-windows/. 3) If installdeps errors on Crypt::OpenSSL::RSA stating that it cannot find .h files: - Note the root location of your openssl installation. This will be referred to as e.g. C:\openssl. Note the root location or your Perl installation e.g. C:\Perl. This will be referred to as . - Copy the \include directory to \lib\CORE. - Copy all the .dll files in \bin to \lib\CORE. - Copy all the .lib files in \lib to \lib\CORE. Running the examples --------------------- Examples can be run by executing the following on command line from a sub-directory of the "examples/" directory, $ perl Example.pl Some examples require you replace object IDs in where you see placeholder like "INSERT_***_HERE" Using test accounts for development ----------------------------------- It is recommended that during development of your library, you use AdWords Test Accounts, to find more information about these type of accounts visit: https://developers.google.com/adwords/api/docs/test-accounts Authorization Options --------------------- Authorization in the client library is handled through different authorization handlers attached to the Client object. The library supports the following authorization protocols: - OAuth 2: This protocol provides a way to access an AdWords account without needing to retain the user credentials such as email and password, and it is the only way for you to authorize your API requests. An access token is required by the library to be able to send authorized requests against the API. This access token can be generated with the library via two different OAuth 2 handlers. The library Client object provides the get_oauth_2_applications_handler and the get_oauth_2_service_accounts_handler methods that allows you to get a reference of the OAuth2 authorization handler for Web/Installed Applications and the handler for Service Accounts, respectively. OAuth2 for Web/Installed Applications The handler for applications provides methods such as get_authorization_url() and issue_access_token() that can be used to follow the authorization flow (i.e. user request for consent) and generation of access and refresh tokens. Also pre-stored access and refresh tokens can be passed to the authorization handler using the method set_access_token() and set_refresh_token() to re-used tokens already authorized by the user, it is up to you to code the mechanism to preserve and restore these tokens. After setting access and refresh tokens the library will handle the refresh of access tokens automatically for you. See the example examples/oauth/generate_offline_credentials.pl for a comprehensive example on how to use this authorization protocol. OAuth2 for Service Accounts The handler for service accounts provides methods such as set_email_address(), set_pem_file() and set_delegated_email_address() that can be used to set the service account email address, private key file and the delegated account email address, respectively. These values can also be configured using the adwords.properties file. Keep in mind that the use of service accounts for accessing AdWords API requires user impersonation because a service account itself can't have direct access to an AdWords Account, that is why the delegated email address is a required parameter. Setting up impersonation requires setup a Google Apps Domain for business. Refer to this Help Center article for more information on this matter http://support.google.com/a/bin/answer.py?hl=en&answer=162106&topic=2759255&ctx=topic Additionally to use service accounts with the library you must transform the private key file as provided by the API Console from PKCS12 format to PEM format with NO password (usually the API console sets its password as 'notasecret'). In Linux/Unix environments with openssl installed this transformation can be easily done as follows: > openssl pkcs12 -in yourfile.p12 -out yourfile.pem -nodes How do I enable logging? ------------------------ The client library uses a custom class for all logging purposes and is exposed through the Google::Ads:AdWords::Logging module. This class relies in the Log::Log4perl module for all its logging tasks and provides a default configuration within the module which can be overriden by proving a log4perl.conf file in your home directory. There are two loggers within this class described below. - AWAPI_LIB_LOG: Logs all requests from the client library along with information such as the timestamp, authentication, service, method, request Id, response time, operations and units count. The default behavior is to log this information to "~/logs/aw_api_lib" relative to your project's home directory. - SOAP_XML_LOG: Logs all incoming and outgoing SOAP requests/responses. The default behavior is to log this information to "~/logs/soap_xml.log" relative to your project's home directory. Sensitive information, such as authentication tokens, will be stripped. Logging can be enabled using the following methods. - Google::Ads::AdWords::Logging::enable_all_logging(); - Enables logging both loggers. - Google::Ads::AdWords::Logging::enable_soap_logging(); - Only enables logging of SOAP traffic. - Google::Ads::AdWords::Logging::enable_awapi_logging(); - Only enables logging of API requests. You can use the methods of the Logger class directly for even more control over how requests are logged. Requests accounting ------------------- The Client class keeps a live count of requests, operations, units consumed, etc since it was instantiated. These counts are accessible using the methods get_requests_count, get_failed_requests_count, get_units_count, get_operations_count. Specific information about the last executed request is accessible using the method get_last_request_stats which returns an object of type Google::Ads::AdWords::RequestStats. Also, the last executed soap request and its response are available through the methods: get_last_soap_request, get_last_soap_response. Gzip support ------------ The library supports gzip compression in the transport layer by default. Based in the LWP:UserAgent module, the compression is detected by checking the contents of HTTP::Message::decodable. If gzip does not appear as the encodings supported in HTTP::Message::decodable, you need to make sure the Compress::Zlib module is installed. Compatibility: -------------- The library relies on the SOAP::WSDL module to send and receive all SOAP traffic from and to the AdWords API servers, however multiple patches are applied to the module in runtime in order to support all the services. In order for these patches to get correctly applied version 2.00.10 of the SOAP::WSDL module must be used and the Google::Ads::AdWords::Client module must be included before any other of the library modules. Where do I submit bug reports and/or feature requests? --------------------------------------------------- Use the issue tracker at: https://github.com/googleads/googleads-perl-lib/issues Questions can be asked on forum: http://groups.google.com/group/adwords-api Make sure to subscribe to our Google Plus page for API change announcements and other news: https://plus.google.com/+GoogleAdsDevelopers External Dependencies: ---------------------- Full dependency list is maintained in Build.PL. Authors: Jeff Posnick David Torres Maintainers: Nadine Sundquist Josh Radcliff