You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*[Eclipse and Intellij](#working-with-eclipse-and-intellij-idea)
@@ -84,7 +84,7 @@ Only Assistant:
84
84
'com.ibm.watson.developer_cloud:assistant:6.1.0'
85
85
```
86
86
87
-
##### Development Snapshots
87
+
##### Development snapshots
88
88
89
89
Snapshots of the development version are available in [Sonatype's snapshots repository][sonatype_snapshots].
90
90
@@ -116,7 +116,7 @@ Now, you are ready to see some [examples](https://github.com/watson-developer-cl
116
116
## Usage
117
117
118
118
The examples within each service assume that you already have service credentials. If not,
119
-
you will have to create a service in [IBM Cloud][ibm_cloud].
119
+
you will have to [create a service](#getting-credentials) in IBM Cloud.
120
120
121
121
If you are running your application in IBM Cloud (or other platforms based on Cloud Foundry), you don't need to specify the
122
122
credentials; the library will get them for you by looking at the [`VCAP_SERVICES`][vcap_services] environment variable.
@@ -128,54 +128,33 @@ If you have more than one plan, you can use `CredentialUtils` to get the service
128
128
129
129
## Authentication
130
130
131
-
There are three ways to authenticate with IBM Cloud through the SDK: using a `username`and `password`, using an `api_key`, and with IAM.
131
+
Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
132
132
133
-
Getting the credentials necessary for authentication is the same process for all methods. To get them, follow these steps:
133
+
- With some service instances, you authenticate to the API by using **[IAM](#iam)**.
134
+
- In other instances, you authenticate by providing the **[username and password](#username-and-password)** for the service instance.
135
+
- Visual Recognition uses a form of [API key](#api-key) only with instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
134
136
135
-
1. Log in to [IBM Cloud](https://console.bluemix.net/catalog?category=watson)
136
-
1. In the IBM Cloud **Catalog**, select the service you want to use.
137
-
1. Click **Create**.
138
-
1. On the left side of the page, click **Service Credentials**, and then **View credentials** to view your service credentials.
To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
140
139
141
-
In your code, you can use these values in the service constructor or with a method call after instantiating your service. Here are some examples:
140
+
1. Go to the IBM Cloud **[Dashboard][watson-dashboard]** page.
141
+
1. Either click an existing Watson service instance or click **Create**.
142
+
1. Click **Show** to view your service credentials.
143
+
1. Copy the `url` and either `apikey` or `username` and `password`.
142
144
143
-
### Username and Password
145
+
In your code, you can use these values in the service constructor or with a method call after instantiating your service.
144
146
145
-
```java
146
-
// in the constructor
147
-
Discovery service =newDiscovery("2017-11-07", "<username>", "<password>");
Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
155
150
156
-
### API Key
151
+
You supply either an IAM service **API key** or an **access token**:
157
152
158
-
_Important: Instantiation with API key works only with Visual Recognition service instances created before May 23, 2018. Visual Recognition instances created after May 22 use IAM._
153
+
- Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
154
+
- Use the access token if you want to manage the lifecycle yourself. Access tokens are valid. For details, see [Authenticating with IAM tokens](https://console.bluemix.net/docs/services/watson/getting-started-iam.html). If you want to switch to API key, override your stored IAM credentials with an IAM API key. Then call the `setIamCredentials()` method again.
159
155
160
-
```java
161
-
// in the constructor
162
-
VisualRecognition service =newVisualRecognition("2016-05-20", "<api_key>");
163
-
```
164
-
165
-
```java
166
-
// after instantiation
167
-
VisualRecognition service =newVisualRecognition("2016-05-20");
168
-
service.setApiKey("<api_key>");
169
-
```
170
-
171
-
### Using IAM
172
-
173
-
When authenticating with IAM, you have the option of passing in:
174
-
- the IAM API key and, optionally, the IAM service URL
175
-
- an IAM access token
176
-
177
-
**Be aware that passing in an access token means that you're assuming responsibility for maintaining that token's lifecycle.** If you instead pass in an IAM API key, the SDK will manage it for you.
178
156
157
+
#### Supplying the IAM API key
179
158
```java
180
159
// in the constructor, letting the SDK manage the IAM token
181
160
IamOptions options =newIamOptions.Builder()
@@ -194,6 +173,7 @@ IamOptions options = new IamOptions.Builder()
194
173
service.setIamCredentials(options);
195
174
```
196
175
176
+
#### Supplying the access token
197
177
```java
198
178
// in the constructor, assuming control of managing IAM token
199
179
IamOptions options =newIamOptions.Builder()
@@ -211,13 +191,39 @@ IamOptions options = new IamOptions.Builder()
211
191
service.setIamCredentials(options);
212
192
```
213
193
214
-
If at any time you would like to let the SDK take over managing your IAM token, simply override your stored IAM credentials with an IAM API key by calling the `setIamCredentials()` method again.
194
+
### Username and password
195
+
196
+
```java
197
+
// in the constructor
198
+
Discovery service =newDiscovery("2017-11-07", "<username>", "<password>");
**Important**: This type of authentication works only with Visual Recognition instances created before May 23, 2018. Newer instances of Visual Recognition use [IAM](#iam).
210
+
211
+
```java
212
+
// in the constructor
213
+
VisualRecognition service =newVisualRecognition("2016-05-20", "<api_key>");
214
+
```
215
+
216
+
```java
217
+
// after instantiation
218
+
VisualRecognition service =newVisualRecognition("2016-05-20");
219
+
service.setApiKey("<api_key>");
220
+
```
215
221
216
222
## Android
217
223
218
224
The Android SDK utilizes the Java SDK while making some Android-specific additions. This repository can be found [here](https://github.com/watson-developer-cloud/android-sdk). It depends on [OkHttp][] and [gson][].
219
225
220
-
## Using a Proxy
226
+
## Using a proxy
221
227
222
228
Override the `configureHttpClient()` method and add the proxy using the `OkHttpClient.Builder` object.
Custom headers can be passed with any request. To do so, add the header to the `ServiceCall` object before executing the request. For example, this is what it looks like to send the header `Custom-Header` along with a call to the Watson Assistant service:
The basic `execute()`, `enqueue()`, and `rx()` methods make HTTP requests to your Watson service and return models based on the requested endpoint. If you would like access to some HTTP response information along with the response model, you can use the more detailed versions of those three methods: `executeWithDetails()`, `enqueueWithDetails()`, and `rxWithDetails()`. To capture the responses, use the new `Response<T>` class, with `T` being the expected response model.
Make sure you are using the service credentials and not your IBM Cloud account/password.
323
-
Check the API Endpoint, you may need to update the default using `setEndPoint()`.
329
+
Check the API endpoint, you may need to update the default using `setEndPoint()`.
324
330
325
331
## Changes for v4.0
326
332
Version 4.0 focuses on the move to programmatically-generated code for many of the services. See the [changelog](https://github.com/watson-developer-cloud/java-sdk/wiki/Changelog) for the details. This version also includes many breaking changes as a result of standardizing behavior across the new generated services. Full details on migration from previous versions can be found [here](https://github.com/watson-developer-cloud/java-sdk/wiki/Migration).
@@ -356,7 +362,7 @@ INFO: <-- 200 OK https://gateway.watsonplatform.net/tradeoff-analytics/api/v1/di
356
362
357
363
**Warning:** The logs generated by this logger when using the level `FINE` or `ALL` has the potential to leak sensitive information such as "Authorization" or "Cookie" headers and the contents of request and response bodies. This data should only be logged in a controlled way or in a non-production environment.
358
364
359
-
## Build + Test
365
+
## Build + test
360
366
361
367
To build and test the project you can use [Gradle][] (version 1.x).
362
368
@@ -381,7 +387,7 @@ gradle idea # Intellij IDEA
381
387
gradle eclipse # Eclipse
382
388
```
383
389
384
-
## Open Source @ IBM
390
+
## Open source @ IBM
385
391
386
392
Find more open source projects on the [IBM Github Page](http://ibm.github.io/)
387
393
@@ -394,7 +400,7 @@ available in [LICENSE](LICENSE).
394
400
395
401
See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
396
402
397
-
## Code of Conduct
403
+
## Code of conduct
398
404
399
405
See [CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md).
400
406
@@ -408,12 +414,13 @@ or [Stack Overflow](http://stackoverflow.com/questions/ask?tags=ibm-watson).
0 commit comments