|
||||||||||
PREV NEXT | FRAMES NO FRAMES |
See:
Description
Packages | |
---|---|
com.google.api.adwords.lib | |
com.google.api.adwords.v10 | |
com.google.api.adwords.v11 |
The AdWords API Java client library provides a set of classes that allow you to programmatically access your AdWords account without having to worry about the complexities of interacting with a web service. All the class files are in the package com.google.api.adwords.lib, and they are provided in the jar file adwords-{version}.jar.
This page has the following sections:
The AdWords API web services enable programmatic interaction with AdWords accounts, as discussed in the AdWords API Developer's Guide. To use a web service, you write a client application that sends requests to the web service. However, developing web service clients in Java from scratch involves a set of complex steps, such as writing the code to generate the remote classes from the web service definition file (WSDL). Typically, developers use a toolkit such as the Axis toolkit to handle connection to the WSDL, but even with the toolkit you need to do additional work such as precompiling the stub classes. The AdWords API Java Client Library takes away the pain of connecting to the WSDL and precompiling the stubs; it does all that housekeeping kind of work for you. All you have to do is write the code to manage your AdWords accounts.
The classes in the client library are packaged in a jar file that includes all the Axis jars and pre-compiled stub classes needed to write Java clients that programmatically access AdWords accounts. You'll need to extract adwords-{version}.jar from the adwords_api-{version}.zip file, and put adwords-{version}.jar in your Java classpath. That's it; you don't need to put anything else in your classpath or do any pre-compiling. You don't need to worry about accessing the WSDL for the web services; the classes in the client library do it for you.
For more information about using the AdWords API to access and modify AdWords accounts, read the AdWords API Developer Guide at http://www.google.com/apis/adwords/developer/.
The client library provides full access to all the functionality of the AdWords API web services plus more. It provides:
The client library uses AspectJ to add an introduction in all the Axis generated stubs, in order to add quota management functionality to these service classes. Ths allows you to work directly with the Axis generated classes without having to worry about implementing quota management manually. When you need to perform quota management functionality on an AdWords service, just cast it to the AdWordsService interface, like the following.
(AdWordsService)campaignService.getLastUnitCount()
The client library provides all the necessary data classes. For example, it provides the Campaign data class for encapsulating campaign data.
The AdWordsUser class provides methods for setting credentials for logging into AdWords accounts as well as for creating instances of the AdWordsService classes.
In other words, for those of you who have already built Java clients without using the client library, the AdWordsUser class has methods for setting username, password, useragent and token so that you don't have to write the code to set the request headers. The methods for creating new instances of AdWordsService classes takes the place of the code for instantiating the stubs that connect to the web services.
The examples use the default constructor
AdWordsUser me = new AdWordsUser();
which uses credentials provided in ~/adwords.properties
There is sample adwords.properties file in the root of the unzipped adwords-{version}.zip.
You need to customize it with your actual credentials, and copy it in your home directory before using the samples.
Else you need to use one of the alternate constructors, passing in all the credential parameters, or a Map containing the credentials with the same keys used in the properties file.
AdWordsUser me = new AdWordsUser(email, password, useragent, developerToken, applicationToken);
This class represents the midnight-to-midnight time period as observed by the AdWords server. It has methods that allows you to specify a start or end date for campaigns and reports without worrying about issues of time zone or daylight savings time.
The AdWordsService interface that is implemented by all Axis stubs has methods for counting and timing operations and quota units.
This class provides simple methods for logging the the XML content of all requests and responses.
The Java client library converts Axis fault into ApiExceptions where possible. For an example of how to use ApiException, see the ApiExceptionDemo.java sample code. The Wrapping of Exceptions is introduced in the Axis stub classes using an around advice.
The Java client library comes with sample code in the examples directory. We encourage you to use the sample code to get started writing your own application. All the sample code is runnable out of the box, but you will have to set your credentials in ~/adwords.properties.
Note: You do not need to edit ApiExceptionDemo to fix the credentials since the point is for it to throw an exception due to invalid credentials.
To install the AdWords API java client Library, extract adwords-{version}.jar from the adwords-{version}.zip file and put it in your Java class path.
The adwords-{version}.jar file appears in the lib directory when adwords-{version}.zip is unzipped.
Note: If you haven't already downloaded the zip file for the Adwords API Java Client Library, you can get it from the Adwords API Developer Website.
To write a program that accesses AdWords accounts using the client library, do the following:
com.google.api.adwords.vi.* | contains the data classes and service classes. i is the version number of the service you want to use. Packages are versioned so that you can use multiple versions concurently in the same program. |
com.google.api.adwords.lib.AdWordsUser | |
com.google.api.adwords.lib.AdWordsServiceLogger | This package is optional, but you need it if you want to log the content of the requests and responses, which can be useful for debugging. |
com.google.api.adwords.ApiException | Axis faults get thrown as ApiExceptions. Import ApiException if you want to throw it or catch it. |
For example, a client program that manages campaigns would import the following packages and classes:
import com.google.api.adwords.v5.*; import com.google.api.adwords.lib.AdWordsUser; import com.google.api.adwords.lib.AdWordsServiceLogger; import com.google.api.adwords.ApiException;
AdWordsUser myClient = new AdWordsUser(email, password, developerToken, applicationToken, useragent);See the section Credentials for details of the credentials. You can specify an alternateUrl to target the sandbox instead of the production AdWords service, and a version if you don't want to use the latest version (which is the default).
CampaignService cs = (CampaignService)myClient.getService(me.CAMPAIGN_SERVICE);
// Create a new campaign object Campaign newCampaign = new Campaign();
newCampaign.setDailyBudget(1000000); // Add the new campaign newCampaign = campaignService.addCampaign(newCampaign);
AdWordsServiceLogger.logToFile("myLogFile.txt")
To log in to AdWords accounts programmatically, you must supply the following credentials:
Note: In other contexts, a useragent identifies the browser or client application that is sending a request. In the AdWords API, the useragent is slightly different -- it identifies the customer making the request and optionally describes the purpose of the request.
The following credential is optional:
You should provide the clientEmail in the credentials when you want to edit a client's account rather than your own account. If this credential is provided, the AdWords API assumes that the account being accessed is the one belonging to the user specified by clientEmail. You are still required to specify the email and password that specify your own email and password for authentication purposes. The client named in clientEmai must be managed by the MCC master named in email.
To get started writing your own client, you can use the demo programs in the examples directory. Copy the demo program you want to use and create a file ~/adwords.properties to set your login information. You also need to specify your client token; if you can't remember what it is, go to http://adwords.google.com/; login to your account, click the My Account tab, then click the AdWords API Center tab. Copy and paste your developer token from the resultant page.
To compile and run a program that uses the AdWords API Java client library, do the following:
javac -classpath adwords-{version}.jar CampaignServiceDemo.java
java -classpath adwords-{version}.jar CampaignServiceDemo
When you run your program, don't worry if you see warnings that attachment support is disabled. This is an Axis thing and shouldn't affect your program.
|
||||||||||
PREV NEXT | FRAMES NO FRAMES |