Subversion Repositories SmartDukaan

AdWords API Java Client Library

===============================

The client library is distributed in two Maven artifacts. They are:

    <dependency>

      <groupId>com.google.api-ads</groupId>

      <artifactId>ads-lib</artifactId>

      <version>RELEASE</version>

    </dependency>

    <dependency>

      <groupId>com.google.api-ads</groupId>

      <artifactId>adwords-axis</artifactId>

      <version>RELEASE</version>

    </dependency>

The "ads-lib" artifact contains all of the library and utility classes for

accessing the AdWords API, but does not support any specific SOAP framework. All

client library classes and utilities are in the package or sub-packages of

"com.google.api.ads.adwords.lib". To add support for the Apache Axis framework,

the "adwords-axis" plugin artifact is also necessary. This artifact also

includes autogenerated classes from the AdWords API. They are in the package

"com.google.api.ads.adwords.axis.{version}".

Quick Start Guide

-----------------

Before you begin, make sure retrieve your client ID and secret from

https://code.google.com/apis/console#access

Examples can be compiled and run by Maven by executing the following on the

command line:

    $ cd path/to/extracted/distribution

    $ cd src/main/resources

    Modify file with settings. This can be moved (not copied) to your home

    directory as well.

    $ vim ads.properties

    Generate OAuth2 credentials to be used with other examples

    $ cd ../../../

    $ mvn -X compile

    $ mvn -X exec:java -Dexec.mainClass="adwords.axis.auth.GetRefreshToken

    Copy the refresh token into your ads.properties file as you just did

    with your general settings and client ID/secret.

    $ vim src/main/resources/ads.properties

    You must have Maven recompile every time you modify the source code or resources

    in order for your changes to take effect.

    $ mvn -X compile

    $ mvn -X exec:java -Dexec.mainClass="adwords.axis.v201302.basicoperations.GetCampaigns"

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:

  - Generated code: Classes and service clients generated automatically from

    the WSDLs.

  - AdWordsSession class: The AdWordsSession class represents one session of

    AdWords API use. It is used to request the services the API offers. It will

    keep track of state information, such as authentication information

    generated from the API.

  - AdWordsServices class: This factory class is responsible for creating API

    service clients. It requires an AdWordsSession and the service interface

    from the autogenerated code.

  - ads.properties file: This file in the src/main/resources directory is a

    sample that shows you how to specify your credentials for the client library

    to read in. To use the credentials in an ads.properties file, make an

    AdWordsSession using the following code:

    new AdWordsSession.Builder().fromFile().build();

    The library will search for an ads.properties file in the following places

    in order: in the user's home directory, in the current directory, and

    finally in the classpath. Files in the src/main/resources directory show up

    on classpath. Every time you modify a file in src/main/resources, you must

    have Maven recompile the project to pick up the changes. If you copy it

    to your home directory, you will not need to recompile every time.

  - Examples: This distribution contains examples in the "src/main/java"

    directory. We encourage you to use code samples to get started writing your

    own application. All the code samples are runnable out of the box, but you

    will have to set your credentials in "resources/ads.properties". You may

    also have to substitute in actual values places that are marked with the

    string "INSERT_{SOMETHING}_HERE".

Basic usage

-----------

To write a program that accesses AdWords accounts with the client library, do

the following:

  1) Import the following packages or classes:

     // Contains the data classes and service classes.

     import com.google.api.ads.adwords.axis.v201306.*;

     import com.google.api.ads.adwords.lib.client.AdWordsSession;

     import com.google.api.ads.adwords.lib.axis.factory.AdWordsServices;

  2a) Create an AdWordsSession instance, loading credentials from the properties

      file:

      // Get an OAuth2 credential.

      Credential credential = new OfflineCredentials.Builder()

          .forApi(OfflineCredentials.Api.AdWords)

          .fromFile()

          .build()

          .generateCredential();

      // Construct an AdWordsSession.

      AdWordsSession session = new AdWordsSession.Builder()

          .fromFile()

          .withOAuth2Credential(credential)

          .build();

  2b) Alternatively, you can specify your credentials in the constructor:

      // Get an OAuth2 credential.

      Credential credential = new OfflineCredentials.Builder()

          .forApi(OfflineCredentials.Api.AdWords)

          .withClientSecrets(clientId, clientSecret)

          .withRefreshToken(refreshToken)

          .build()

          .generateCredential();

      // Construct an AdWordsSession.

      AdWordsSession session = new AdWordsSession.Builder()

          .withDeveloperToken(developerToken)

          // ...

          .withOAuth2Credential(credential)

          .build();

  3) Instantiate the desired service class using the AdWordsServices utility and

     a Class object representing your service.

     // Get the CampaignService.

     CampaignServiceInterface campaignService =

         new AdWordsServices().get(session, CampaignServiceInterface.class);

  4) Create data objects and invoke methods on the service class instance. The

     data objects and methods map directly to the data objects and requests for

     the corresponding web service.

      // Create selector.

      Selector selector = new Selector();

      selector.setFields(new String[] {"Id", "Name"});

      // Get all campaigns.

      CampaignPage page = campaignService.get(selector);

You'll need to pull in the library as dependencies. This example project

contains a full pom.xml that will pull in all of the necessary artifacts. There

is no need to worry about accessing the WSDLs for the web services; the classes

in the client library do it for you. Examples in the "src/main/java" directory

can be used to get started writing your own client.

OAuth2 authentication

---------------------

There are two ways to authenticate with OAuth2 in the library:

  - Use the OfflineCredentials utility to generate a simple refreshable

    Credential for small applications. You will find that all of our examples

    use this utility.

  - Create a Credential object from scratch using a GoogleAuthorizationCodeFlow

    and a CredentialStore. You may want to go this route if you are creating

    a complicated application. See the AdvancedCreateCredentialFromScratch

    example for more information.

How do I use OfflineCredentials?

--------------------------------

OfflineCredentials can use your ads.properties file to create a refreshable

Credential. It will not create a refresh token for you, or walk the user

through an authorization flow. To get a refresh token, run the GetRefreshToken

example as shown in the Quick Start Guide section.

Service accounts

----------------

You may be tempted to use a service account to access the API. However, to use

a service account, you must be a Google Apps for Business customer, with the

ability to impersonate users of your network.

If you are a Google Apps for Business customer, then you can use the

AdvancedCreateCredentialFromScratch example as a starting point for constructing

a service account Credential. See

https://code.google.com/p/google-api-java-client/wiki/OAuth2#Service_Accounts

on how to do this.

If you are unable to use service accounts, but still want to only perform the

OAuth2 flow once, consider creating an offline credential using the

OfflineCredentials utility.

How do I enable logging?

------------------------

The client library uses SLF4J for all logging. If you want to turn logging on,

you must include a plugin that bridges SLF4J with a concrete logging framework.

To quickly get you started and to serve as an example of how to do this, this

example distribution uses the log4j framework.

There are the following loggers within the library:

  - com.google.api.ads.adwords.lib.client.AdWordsServiceClient.soapXmlLogger

    Logs incoming and outgoing SOAP requests/responses. SOAP requests and

    responses are logged as WARN for exceptions and INFO for all other requests.

    You can configure your logging framework to accept logs on these parameters.

    See the example resources/log4j.properties for more information.

  - com.google.api.ads.adwords.lib.client.AdWordsServiceClient.requestInfoLogger

    Logs all requests from the client library along with information such as the

    timestamp, service, method, endpoint URL.

To bridge SLF4J for a logging framework, you must do the following:

  1) Include the plugin and logging framework dependencies in the pom.xml file's

     dependencies list.

     <!-- Adds the log4j framework -->

     <dependency>

       <groupId>log4j</groupId>

       <artifactId>log4j</artifactId>

       <version>1.2.16</version>

     </dependency>

     <!-- Make SLF4J use log4j as the logging framework -->

     <dependency>

       <groupId>org.slf4j</groupId>

       <artifactId>slf4j-log4j12</artifactId>

       <version>1.6.2</version>

     </dependency>

  2) If your logging framework requires a configuration file, you must place it

     in the resources directory. This distribution includes an example

     configuration for log4j named "log4j.properties".

Because the client library uses SLF4J, the behavior of these loggers is highly

customizable. Please see the "resources/log4j.properties" file for details on

the default behavior in this example project.

What if I am behind an HTTP Proxy server?

----------------------------------------

It is recommended that the user set JVM arguments to configure this application

for their proxy.

    https.proxyHost      Hostname of proxy server                      web-proxy

    https.proxyPort      Port on server of proxy                       8080

    https.proxyUser      Optional username for proxy authentication    someone

    https.proxyPassword  Optional proxy server password                secret

These properties can be set within the command line such as:

    $ mvn -Dhttps.proxyHost=web-proxy -Dhttps.proxyPort=8080

        -Dhttps.proxyUser=someone -Dhttps.proxyPassword=secret ...

If necessary, set this up in code by doing the following:

    System.setProperty("https.proxyHost", "web-proxy");

    System.setProperty("https.proxyPort", "8080");

    System.setProperty("https.proxyUser", "someone");

    System.setProperty("https.proxyPassword", "secret");

Where do I submit bug reports, feature requests and patches?

------------------------------------------------------------

All of these items can be submitted at

http://code.google.com/p/google-api-ads-java/issues/list.

Make sure to subscribe to our Google Plus page for API change announcements and

other news:

  https://plus.google.com/+GoogleAdsDevelopers

Authors:

    Adam Rogal

    Joseph DiLallo

Maintainer:

    Kevin Winter