Skip to content

Commit 8db4ca7

Browse files
jradcliffjradcliff
authored
Create README.md
0 parents  commit 8db4ca7

File tree

1 file changed

+255
-0
lines changed

1 file changed

+255
-0
lines changed

‎README.md

+255
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
# Google Ads API Client Library for Java
2+
3+
This project hosts the Java client library for the Google Ads API.
4+
5+
## Features
6+
7+
* Distributed via [Maven](https://maven.apache.org/).
8+
* Easy management of credentials.
9+
* Easy creation of Google Ads API service clients.
10+
11+
## Requirements
12+
13+
* Java 1.7+
14+
* Maven 3.0+
15+
16+
## Maven artifacts
17+
18+
<dependency>
19+
<groupId>com.google.api-ads</groupId>
20+
<artifactId>google-ads</artifactId>
21+
<version>0.1.0</version>
22+
</dependency>
23+
24+
## Getting started
25+
26+
1. Clone this project in the directory of your choice via:
27+
28+
git clone https://github.com/googleads/google-ads-java.git
29+
30+
2. Change into the `google-ads-java` directory.
31+
32+
cd google-ads-java
33+
34+
You'll see a parent `pom.xml` for the project, as well as the following
35+
subdirectories:
36+
37+
* `google-ads`: source code for the library.
38+
* `google-ads-examples`: multiple examples that demonstrate how to use
39+
the library to execute common use cases via the Google Ads API.
40+
41+
3. To run examples, you'll need to compile the `google-ads-examples` code.
42+
43+
**If you are using an IDE...**
44+
45+
* Import the `google-ads-examples` project and confirm that your IDE
46+
builds the project successfully.
47+
48+
**If you are using Maven from the command line...**
49+
50+
* Change into the `google-ads-examples` directory.
51+
52+
cd google-ads-examples
53+
54+
* Compile the examples project via:
55+
56+
mvn compile
57+
58+
4. Setup your OAuth2 credentials.
59+
60+
The Google Ads API uses [OAuth2](http://oauth.net/2/) as the authentication
61+
mechanism. Choose the appropriate option below based on your use case, and
62+
read and follow the instructions that the example prints to the console.
63+
64+
**If you already have credentials for the AdWords API...**
65+
66+
* You can use the same `ads.properties` file you used for the
67+
AdWords API. Simply copy the lines for the following keys and
68+
change the `api.adwords` prefix in each key from `api.adwords` to
69+
`api.googleads`:
70+
71+
api.adwords.clientId --> api.googleads.clientId
72+
api.adwords.clientSecret --> api.googleads.clientSecret
73+
api.adwords.refreshToken --> api.googleads.refreshToken
74+
api.adwords.developerToken --> api.googleads.developerToken
75+
76+
**If you're accessing the Google Ads API using your own credentials...**
77+
78+
* Follow the instructions at
79+
https://developers.google.com/google-ads/api/docs/guides/authentication#installed
80+
to create an OAuth2 client ID and secret for the installed application
81+
OAuth2 flow.
82+
83+
* Run the
84+
[AuthenticateInStandaloneApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInStandaloneApplication.java)
85+
example, which will prompt you for your OAuth2 client ID and secret.
86+
87+
**If using an IDE:**
88+
89+
The example may fail with an `IllegalArgumentException`
90+
if your IDE does not support using `System.console`. If the example
91+
fails, replace the `INSERT_CLIENT_ID_HERE` and `INSERT_CLIENT_SECRET_HERE`
92+
values in the
93+
[AuthenticateInStandaloneApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInStandaloneApplication.java)
94+
example with the client ID and secret from the step above, then run the
95+
example again.
96+
97+
**If using the command line:**
98+
99+
```
100+
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInStandaloneApplication"
101+
```
102+
103+
* Copy the output from the last step of the example into a file named
104+
`ads.properties` in your home directory.
105+
106+
**If you're accessing the Google Ads API on behalf of clients...**
107+
108+
* Follow the instructions at
109+
https://developers.google.com/google-ads/api/docs/guides/authentication#webapp
110+
to create an OAuth2 client ID and secret for the web application OAuth2
111+
flow.
112+
113+
* Run the
114+
[AuthenticateInWebApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInWebApplication.java)
115+
example, which will prompt you for your OAuth2 client ID and secret.
116+
117+
**If using an IDE:**
118+
119+
The example may fail with an `IllegalArgumentException`
120+
if your IDE does not support using `System.console`. If the example
121+
fails, replace the `INSERT_CLIENT_ID_HERE` and `INSERT_CLIENT_SECRET_HERE`
122+
values in the
123+
[AuthenticateInWebApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInWebApplication.java)
124+
example with the client ID and secret from the step above, then run the
125+
example again.
126+
127+
**If using the command line:**
128+
129+
```
130+
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInWebApplication"
131+
```
132+
133+
* Copy the output from the last step of the example into a file named
134+
`ads.properties` in your home directory.
135+
136+
5. After following the instructions printed to the console, you should have a
137+
file named `ads.properties` in your home directory.
138+
139+
To ensure that the credentials in that file are valid, run the
140+
[GetCampaigns example](https://github.com/googleads/google-ads-java/tree/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/GetCampaigns),
141+
either via your IDE or from the command line using Maven. This example
142+
requires a `--customerId` parameter where the value is your AdWords
143+
account's customer ID without dashes. Here's how you can pass that
144+
information if you are using Maven from the command line.
145+
146+
```
147+
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
148+
-Dexec.args="--customerId INSERT_CUSTOMER_ID_HERE"
149+
```
150+
151+
6. Explore other examples.
152+
153+
The [examples](https://github.com/googleads/google-ads-java/tree/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples)
154+
package in `google-ads-examples` contains several useful examples. Most
155+
of the examples require parameters. You can either pass the parameters as
156+
arguments (recommended) or edit the `INSERT_XXXXX_HERE` values in the
157+
source code. To see a usage statement for an example, pass `--help` as the
158+
only argument.
159+
160+
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
161+
-Dexec.args="--help"
162+
163+
## Basic usage
164+
165+
### Create a GoogleAdsClient
166+
167+
To issue requests via the Google Ads API, you first need to create a
168+
[GoogleAdsClient](https://github.com/googleads/google-ads-java/blob/master/google-ads/src/main/java/com/google/googleads/lib/GoogleAdsClient.java).
169+
For convenience, you can store the required settings in a properties file with
170+
the following format:
171+
172+
api.googleads.clientId=INSERT_CLIENT_ID_HERE
173+
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
174+
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
175+
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
176+
177+
This configuration file format is similar to the format used in the AdWords
178+
API's
179+
[client library for Java](https://github.com/googleads/googleads-java-lib), but
180+
uses property keys with the prefix `api.googleads` instead of `api.adwords`
181+
so you can have separate configuration settings for the AdWords API and the
182+
Google Ads API.
183+
184+
If you have an `ads.properties` configuration file in the above format in your
185+
home directory, you can use the no-arg version of `fromPropertiesFile` as
186+
follows:
187+
188+
```java
189+
GoogleAdsClient googleAdsClient =
190+
GoogleAdsClient.newBuilder()
191+
.fromPropertiesFile().build();
192+
```
193+
194+
If your configuration file is not in your home directory, you can pass the
195+
file location to the `fromPropertiesFile` method as follows:
196+
197+
```java
198+
GoogleAdsClient googleAdsClient =
199+
GoogleAdsClient.newBuilder()
200+
.fromPropertiesFile("/path/to/ads.properties").build();
201+
```
202+
203+
You can also construct a `Credentials` object by specifying the client ID,
204+
client secret, and refresh token at runtime, then pass that to the
205+
`GoogleAdsClient` builder as follows:
206+
207+
```java
208+
Credentials credentials =
209+
UserCredentials.newBuilder()
210+
.setClientId("INSERT_CLIENT_ID")
211+
.setClientSecret("INSERT_CLIENT_SECRET")
212+
.setRefreshToken("INSERT_REFRESH_TOKEN")
213+
.build();
214+
GoogleAdsClient googleAdsClient =
215+
GoogleAdsClient.newBuilder()
216+
.setCredentials(credentials)
217+
.setDeveloperToken("INSERT_DEVELOPER_TOKEN_HERE")
218+
.build();
219+
```
220+
221+
### Get a service client
222+
223+
Once you have an instance of `GoogleAdsClient`, you can obtain a service client
224+
for a particular service using one of the `get...ServiceClient()` methods.
225+
Wrapping this call in a try with resources block ensures that any
226+
resources required to make the Google Ads API request are released upon exit
227+
from the `try` block.
228+
229+
```java
230+
try (CampaignServiceClient reportingServiceClient = googleAdsClient.getCampaignServiceClient()) {
231+
// Send a request...
232+
}
233+
```
234+
235+
## Miscellaneous
236+
237+
### Wiki
238+
239+
- https://github.com/googleads/google-ads-java/wiki
240+
241+
### Issue tracker
242+
243+
- https://github.com/googleads/google-ads-java/issues
244+
245+
### API Documentation:
246+
247+
- https://developers.google.com/google-ads/api/docs
248+
249+
### Support forum
250+
251+
- https://groups.google.com/forum/#!forum/adwords-api
252+
253+
### Authors
254+
255+
- [Josh Radcliff](https://github.com/jradcliff)

0 commit comments

Comments
 (0)