Skip to content

Commit fb3dbc1

Browse files
nwbirnienwbirnie
authored
Update readme following UX review. (#300)
This consolidates the docs on to developers.google.com. Also added new authors Change-Id: I9633d7dbba0e71ba54ab79f10f93c0b45732980b
1 parent 4ca7f06 commit fb3dbc1

1 file changed

Lines changed: 5 additions & 326 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 326 deletions
Original file line numberDiff line numberDiff line change
@@ -20,333 +20,10 @@ This project hosts the Java client library for the Google Ads API.
2020
<artifactId>google-ads</artifactId>
2121
<version>5.1.0</version>
2222
</dependency>
23+
24+
## Documentation
2325

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-
Now run the following command to install the snapshot version of the library and examples
35-
project.
36-
37-
mvn clean install
38-
39-
You'll see a parent `pom.xml` for the project, as well as the following
40-
subdirectories:
41-
42-
* `google-ads`: source code for the library.
43-
* `google-ads-examples`: multiple examples that demonstrate how to use
44-
the library to execute common use cases via the Google Ads API.
45-
46-
4. Setup your OAuth2 credentials.
47-
48-
The Google Ads API uses [OAuth2](http://oauth.net/2/) as the authentication
49-
mechanism. Choose the appropriate option below based on your use case, and
50-
read and follow the instructions that the example prints to the console.
51-
52-
**If you already have credentials for the AdWords API...**
53-
54-
* You can use the same `ads.properties` file you used for the
55-
AdWords API. Simply copy the lines for the following keys and
56-
change the `api.adwords` prefix in each key from `api.adwords` to
57-
`api.googleads`:
58-
59-
api.adwords.clientId --> api.googleads.clientId
60-
api.adwords.clientSecret --> api.googleads.clientSecret
61-
api.adwords.refreshToken --> api.googleads.refreshToken
62-
api.adwords.developerToken --> api.googleads.developerToken
63-
64-
If you are authenticating as a manager account, additionally you must specify:
65-
66-
api.googleads.loginCustomerId --> Manager account ID (with hyphens removed).
67-
68-
**If you're accessing the Google Ads API using your own credentials...**
69-
70-
* Follow the instructions at
71-
https://developers.google.com/google-ads/api/docs/oauth/cloud-project
72-
to create an OAuth2 client ID and secret for the **installed application**
73-
OAuth2 flow.
74-
75-
* Run the
76-
[AuthenticateInStandaloneApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInStandaloneApplication.java)
77-
example, which will prompt you for your OAuth2 client ID and secret.
78-
79-
**If using an IDE:**
80-
81-
The example may fail with an `IllegalArgumentException`
82-
if your IDE does not support using `System.console`. If the example
83-
fails, replace the `INSERT_CLIENT_ID_HERE` and `INSERT_CLIENT_SECRET_HERE`
84-
values in the
85-
[AuthenticateInStandaloneApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInStandaloneApplication.java)
86-
example with the client ID and secret from the step above, then run the
87-
example again.
88-
89-
**If using the command line:**
90-
91-
```
92-
$ cd google-ads-java
93-
$ mvn clean install
94-
$ mvn -f google-ads-examples/pom.xml exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInStandaloneApplication"
95-
```
96-
97-
* Copy the output from the last step of the example into a file named
98-
`ads.properties` in your home directory.
99-
100-
**If you're accessing the Google Ads API on behalf of clients...**
101-
102-
* Follow the instructions at
103-
https://developers.google.com/google-ads/api/docs/oauth/cloud-project
104-
to create an OAuth2 client ID and secret for the **web application**
105-
OAuth2 flow.
106-
107-
* Run the
108-
[AuthenticateInWebApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInWebApplication.java)
109-
example, which will prompt you for your OAuth2 client ID and secret.
110-
111-
**If using an IDE:**
112-
113-
The example may fail with an `IllegalArgumentException`
114-
if your IDE does not support using `System.console`. If the example
115-
fails, replace the `INSERT_CLIENT_ID_HERE` and `INSERT_CLIENT_SECRET_HERE`
116-
values in the
117-
[AuthenticateInWebApplication](https://github.com/googleads/google-ads-java/blob/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/authentication/AuthenticateInWebApplication.java)
118-
example with the client ID and secret from the step above, then run the
119-
example again.
120-
121-
**If using the command line:**
122-
123-
```
124-
$ cd google-ads-java
125-
$ mvn clean install
126-
$ mvn -f google-ads-examples/pom.xml exec:java -Dexec.mainClass="com.google.ads.googleads.examples.authentication.AuthenticateInWebApplication"
127-
```
128-
129-
* Copy the output from the last step of the example into a file named
130-
`ads.properties` in your home directory.
131-
132-
5. After following the instructions printed to the console, you should have a
133-
file named `ads.properties` in your home directory.
134-
135-
To ensure that the credentials in that file are valid, run the
136-
[GetCampaigns example](https://github.com/googleads/google-ads-java/tree/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples/basicoperations/GetCampaigns.java),
137-
either via your IDE or from the command line using Maven.
138-
139-
First, navigate into the `google-ads-examples` directory.
140-
```
141-
$ cd google-ads-examples
142-
```
143-
144-
This example
145-
requires a `--customerId` parameter where the value is your Google Ads
146-
account's customer ID without dashes. Here's how you can pass that
147-
information if you are using Maven from the command line.
148-
149-
```
150-
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
151-
-Dexec.args="--customerId INSERT_CUSTOMER_ID_HERE"
152-
```
153-
154-
6. Explore other examples.
155-
156-
The [examples](https://github.com/googleads/google-ads-java/tree/master/google-ads-examples/src/main/java/com/google/ads/googleads/examples)
157-
package in `google-ads-examples` contains several useful examples. Most
158-
of the examples require parameters. You can either pass the parameters as
159-
arguments (recommended) or edit the `INSERT_XXXXX_HERE` values in the
160-
source code. To see a usage statement for an example, pass `--help` as the
161-
only argument.
162-
163-
$ mvn exec:java -Dexec.mainClass="com.google.ads.googleads.examples.basicoperations.GetCampaigns" \
164-
-Dexec.args="--help"
165-
166-
## Basic usage
167-
168-
### Create a GoogleAdsClient
169-
170-
To issue requests via the Google Ads API, you first need to create a
171-
[GoogleAdsClient](https://github.com/googleads/google-ads-java/blob/master/google-ads/src/main/java/com/google/ads/googleads/lib/GoogleAdsClient.java).
172-
For convenience, you can store the required settings in a properties file with
173-
the following format:
174-
175-
# Credential for accessing Google's OAuth servers.
176-
# Provided by https://console.developers.google.com.
177-
api.googleads.clientId=INSERT_CLIENT_ID_HERE
178-
179-
# Credential for accessing Google's OAuth servers.
180-
# Provided by https://console.developers.google.com.
181-
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
182-
183-
# Renewable OAuth credential associated with 1 or more Google Ads accounts.
184-
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
185-
186-
# Token which provides access to the Google Ads API in general. It does not grant access to any
187-
# particular ad account (OAuth is used for this purpose).
188-
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
189-
190-
# Required for manager accounts only: Specify the login customer ID used to
191-
# authenticate API calls. This will be the customer ID of the authenticated
192-
# manager account. You can also specify this later in code if your application
193-
# uses multiple manager account + OAuth pairs.
194-
#
195-
# api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOEMR_ID_HERE
196-
197-
# By default, this library uses reflection to build the ApiCatalog.
198-
# In order to reduce latency when creating service clients, users can set
199-
# api.googleads.enableGeneratedCatalog=true, which will use a pre-generated
200-
# ApiCatalog that does not use reflection. Excluding this property from the
201-
# ads.properties file or using any value other than true will result in the
202-
# default behavior. This feature is still experimental.
203-
#
204-
# api.googleads.enableGeneratedCatalog=true
205-
206-
This configuration file format is similar to the format used in the AdWords
207-
API's
208-
[client library for Java](https://github.com/googleads/googleads-java-lib), but
209-
uses property keys with the prefix `api.googleads` instead of `api.adwords`
210-
so you can have separate configuration settings for the AdWords API and the
211-
Google Ads API.
212-
213-
If you have an `ads.properties` configuration file in the above format in your
214-
home directory, you can use the no-arg version of `fromPropertiesFile` as
215-
follows:
216-
217-
```java
218-
GoogleAdsClient googleAdsClient =
219-
GoogleAdsClient.newBuilder()
220-
.fromPropertiesFile().build();
221-
```
222-
223-
If your configuration file is not in your home directory, you can pass the
224-
file location to the `fromPropertiesFile` method as follows:
225-
226-
```java
227-
File propertiesFile = new File("/path/to/ads.properties");
228-
GoogleAdsClient googleAdsClient =
229-
GoogleAdsClient.newBuilder()
230-
.fromPropertiesFile(propertiesFile).build();
231-
```
232-
233-
You can also construct a `Credentials` object by specifying the client ID,
234-
client secret, and refresh token at runtime, then pass that to the
235-
`GoogleAdsClient` builder as follows:
236-
237-
```java
238-
Credentials credentials =
239-
UserCredentials.newBuilder()
240-
.setClientId("INSERT_CLIENT_ID")
241-
.setClientSecret("INSERT_CLIENT_SECRET")
242-
.setRefreshToken("INSERT_REFRESH_TOKEN")
243-
.build();
244-
GoogleAdsClient googleAdsClient =
245-
GoogleAdsClient.newBuilder()
246-
.setCredentials(credentials)
247-
.setDeveloperToken("INSERT_DEVELOPER_TOKEN_HERE")
248-
.setLoginCustomerId("INSERT_LOGIN_CUSTOMER_ID_HERE") // Manager accounts only.
249-
.build();
250-
```
251-
252-
### Get a service client
253-
254-
Once you have an instance of `GoogleAdsClient`, you can obtain a service client
255-
for a particular service using one of the `get...ServiceClient()` methods.
256-
Wrapping this call in a try with resources block ensures that any
257-
resources required to make the Google Ads API request are released upon exit
258-
from the `try` block.
259-
260-
```java
261-
try (CampaignServiceClient reportingServiceClient = googleAdsClient.getCampaignServiceClient()) {
262-
// Send a request...
263-
}
264-
```
265-
266-
### Request/Response Logging
267-
268-
Logging is configured with SLF4J a generic logging library for Java, which allows logs to be
269-
directed to many different logging implementations. We provide configuration files for log4j 1.2/2.0
270-
and Java Util Logging (JUL).
271-
272-
#### Logging layout and functionality
273-
274-
Requests are logged with a one line summary and the full request/response body and
275-
headers.
276-
277-
| Log type | Log name | Success level | Failure level |
278-
| -------- | -------------------------------------------- | ------------- | ------------- |
279-
| SUMMARY | com.google.ads.googleads.lib.request.summary | INFO | WARN |
280-
| DETAIL | com.google.ads.googleads.lib.request.detail | DEBUG | INFO |
281-
282-
**Caveat**: Mutate requests where [Partial failure](https://developers.google.com/google-ads/api/docs/samples/handle-partial-failure)
283-
is true do not cause the entire request to fail. Therefore, partial failure logs are always logged
284-
at Success level, not at Failure level as may be expected.
285-
286-
#### Detail Log Truncation
287-
288-
The detailed logs are truncated by default to avoid creating large logs. To change the length at
289-
which logs are truncated, set `-Dapi.googleads.maxLogMessageLength=<number>`. Setting -1 disables
290-
log truncation.
291-
292-
#### Log4j 2.0
293-
294-
1. Add a dependency on the `log4j-slf4j-impl` library.
295-
296-
```
297-
<dependency>
298-
<groupId>org.apache.logging.log4j</groupId>
299-
<artifactId>log4j-slf4j-impl</artifactId>
300-
<version>2.11.1</version>
301-
</dependency>
302-
```
303-
304-
2. (Optional) Create a configuration file in your resources directory, e.g. in Maven
305-
`src/main/resources`. Log4j 2.0 loads its configuration file from the classpath, not the working
306-
directory, so ensure you create in a resources directory.
307-
308-
3. Run your application, specifying `-Dlog4j.configurationFile=<CONFIG_FILE_PATH>`. You can specify
309-
`CONFIG_FILE_PATH=googleads-logging/log4j2.xml` to use the default configuration file included
310-
with the client libraries.
311-
312-
#### Log4j 1.2 (legacy)
313-
314-
1. Add a dependency on the `slf4j-log4j12` library.
315-
316-
```
317-
<dependency>
318-
<groupId>org.slf4j</groupId>
319-
<artifactId>slf4j-log4j12</artifactId>
320-
<version>1.7.25</version>
321-
</dependency>
322-
```
323-
324-
2. (Optional) Create a configuration file in your projects resources directory, e.g. in Maven
325-
path is `src/main/resources`. Log4j 1.2 loads its configuration file from the classpath, not the
326-
working directory, so ensure you copy to a resources directory.
327-
328-
3. Run your application, specifying `-Dlog4j.configuration=<CONFIG_FILE_PATH>`. You can specify
329-
`CONFIG_FILE_PATH=googleads-logging/log4j.properties` to use the default configuration file included
330-
with the client libraries.
331-
332-
#### Java Util Logging
333-
334-
1. Add a dependency on the `slf4j-jdk14` library.
335-
336-
```
337-
<dependency>
338-
<groupId>org.slf4j</groupId>
339-
<artifactId>slf4j-jdk14</artifactId>
340-
<version>1.7.25</version>
341-
</dependency>
342-
```
343-
344-
2. Create a JUL configuration file on the file system in a path readable from your application. For
345-
instance `./jdk-logger.properties`. A template is provided at
346-
`google-ads/src/main/resources/googleads-logging/jdk-logger.properties`. JUL reads from the
347-
filesystem only, so do not copy to the resources directory.
348-
349-
3. Run your application specifying `-Djava.util.logging.config.file=./jdk-logger.properties`.
26+
Our documentation is available [here](https://developers.google.com/google-ads/api/docs/client-libs/java).
35027

35128
## Miscellaneous
35229

@@ -369,3 +46,5 @@ filesystem only, so do not copy to the resources directory.
36946
### Authors
37047

37148
- [Josh Radcliff](https://github.com/jradcliff)
49+
- [Nick Birnie](https://github.com/nwbirnie)
50+
- [Devin Chasanoff](https://github.com/devchas)

0 commit comments

Comments
 (0)