From 8e074f3c07dee4efc0c6f204b57b40fd5d531dcb Mon Sep 17 00:00:00 2001 From: Thomas Coffee Date: Fri, 14 Jul 2017 01:25:58 -0400 Subject: [PATCH] Make Translate auth documentation clear and consistent (#2208) * Make Translate auth documentation clear and consistent Additional updates prompted by #1594 / #2147. * Fix doc link * Fix Spanner doc example * Work around Javadoc bug https://bugs.openjdk.java.net/browse/JDK-8130754 --- README.md | 24 +++++++++---------- .../snippets/DetectLanguageAndTranslate.java | 5 ++-- .../google/cloud/spanner/DatabaseClient.java | 8 +++---- google-cloud-translate/README.md | 6 ++--- .../google/cloud/translate/package-info.java | 12 ++++++---- 5 files changed, 29 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 661dc4a98f8f..b154e88690b3 100644 --- a/README.md +++ b/README.md @@ -178,7 +178,7 @@ Storage storage = StorageOptions.getDefaultInstance().getService(); ``` If no credentials are provided, `google-cloud` will attempt to detect them from the environment -using `GoogleCredentials.getApplicationDefault()` which will search for Default Application +using `GoogleCredentials.getApplicationDefault()` which will search for Application Default Credentials in the following locations (in order): 1. The credentials file pointed to by the `GOOGLE_APPLICATION_CREDENTIALS` environment variable @@ -498,8 +498,8 @@ Google Cloud Language (Beta) ### Preview -Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either default application -credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) +Here is a code snippet showing a simple usage example of LanguageServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) ```java try (LanguageServiceClient languageServiceClient = LanguageServiceClient.create()) { Document document = Document.newBuilder().build(); @@ -516,7 +516,7 @@ Google Cloud Vision (Beta) ### Preview Here is a code snippet showing a simple usage example of ImageAnnotatorClient. -The example assumes that either default application credentials or a valid API key +The example assumes that either Application Default Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) ```java try (ImageAnnotatorClient imageAnnotatorClient = ImageAnnotatorClient.create()) { @@ -751,8 +751,8 @@ Google Translation (Beta) #### Preview Here's a snippet showing a simple usage example. The example shows how to detect the language of -some text and how to translate some text. The example assumes that either default application -credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment +some text and how to translate some text. The example assumes that either Application Default +Credentials or a valid API key are available. An API key stored in the `GOOGLE_API_KEY` environment variable will be automatically detected. Complete source code can be found at [DetectLanguageAndTranslate.java](./google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java). @@ -784,8 +784,8 @@ Google Cloud Speech (Alpha) ### Preview -Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either default application -credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) +Here is a code snippet showing a simple usage example of SpeechClient. The example assumes that either Application Default +Credentials or a valid API key are available. (See [Authentication section](#authentication) for more information) Note that you must provide a uri to a FLAC audio file to run this. ```java @@ -814,8 +814,8 @@ Google Cloud Trace (Alpha) ### Preview -Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application -credentials or a valid API key are available. +Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere. ```java try (TraceServiceClient traceServiceClient = TraceServiceClient.create()) { @@ -832,8 +832,8 @@ Google Cloud Video Intelligence (Alpha) ### Preview -Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either default application -credentials or a valid API key are available. +Here is a code snippet showing a simple usage example of TraceServiceClient. The example assumes that either Application Default +Credentials or a valid API key are available. Note that you must [supply credentials](#authentication) and a project ID if running this snippet elsewhere. ```java try (VideoIntelligenceServiceClient videoIntelligenceServiceClient = diff --git a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java index 6a65fefa16ef..b953b9f26230 100644 --- a/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java +++ b/google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java @@ -37,8 +37,9 @@ public class DetectLanguageAndTranslate { public static void main(String... args) { // Create a service object // - // Requests are authenticated using default application credentials if available; otherwise, - // using an API key from the GOOGLE_API_KEY environment variable + // If no explicit credentials or API key are set, requests are authenticated using Application + // Default Credentials if available; otherwise, using an API key from the GOOGLE_API_KEY + // environment variable Translate translate = TranslateOptions.getDefaultInstance().getService(); // Detect the language of some text diff --git a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java index e7d18a9c9352..22e2bc8692ff 100644 --- a/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java +++ b/google-cloud-spanner/src/main/java/com/google/cloud/spanner/DatabaseClient.java @@ -218,13 +218,13 @@ public interface DatabaseClient { * returned runner can only be used once. * *

Example of a read write transaction. - * 

 {@code
+   * 
 
    * long singerId = my_singer_id;
    * TransactionRunner runner = dbClient.readWriteTransaction();
    * runner.run(
-   *     new TransactionCallable() {
+   *     new TransactionCallable<Void>() {
    * 
-   *       @Override
+   *       {@literal @}Override
    *       public Void run(TransactionContext transaction) throws Exception {
    *         String column = "FirstName";
    *         Struct row =
@@ -235,7 +235,7 @@ public interface DatabaseClient {
    *         return null;
    *       }
    *     });
-   * }

+   *
* */ TransactionRunner readWriteTransaction(); diff --git a/google-cloud-translate/README.md b/google-cloud-translate/README.md index 284a80e6348b..0d1b656cc99d 100644 --- a/google-cloud-translate/README.md +++ b/google-cloud-translate/README.md @@ -80,7 +80,7 @@ section to add `google-cloud-translate` as a dependency in your code. #### Creating an authorized service object To make authenticated requests to Google Translation, you must create a service object with -credentials or with an API key. The simplest way to authenticate is to use +credentials or use an API key. The simplest way to authenticate is to use [Application Default Credentials](https://developers.google.com/identity/protocols/application-default-credentials). These credentials are automatically inferred from your environment, so you only need the following code to create your service object: @@ -142,8 +142,8 @@ Translation translation = translate.translate( In [DetectLanguageAndTranslate.java](../google-cloud-examples/src/main/java/com/google/cloud/examples/translate/snippets/DetectLanguageAndTranslate.java) -we put together all the code shown above into one program. The program assumes that either default -application credentials or a valid api key are available. +we put together all the code shown above into one program. The program assumes that either Application +Default Credentials or a valid API key are available. Troubleshooting --------------- diff --git a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java index bb450a5be479..7a2aaa4522fb 100644 --- a/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java +++ b/google-cloud-translate/src/main/java/com/google/cloud/translate/package-info.java @@ -17,11 +17,13 @@ /** * A client to Google Translation. * - *

Here's a simple usage example for using Google Cloud Translation. This example shows how to - * detect the language of some text and how to translate some text. The example assumes that the - * {@code GOOGLE_API_KEY} is set and contains a valid API key. Alternatively, you can use - * {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set - * the API key. For the complete source code, see: Here's a simple usage example for Google Cloud Translation. This example shows how to detect + * the language of some text and how to translate some text. The example assumes that either + * Application Default Credentials are available or that the {@code GOOGLE_API_KEY} environment + * variable is set and contains a valid API key. Alternatively, you can use + * {@link com.google.cloud.ServiceOptions.Builder#setCredentials setCredentials} to set credentials, + * or {@link com.google.cloud.translate.TranslateOptions.Builder#setApiKey(java.lang.String)} to set + * an API key. For the complete source code see * DetectLanguageAndTranslate.java. 

  * {@code Translate translate = TranslateOptions.getDefaultInstance().getService();