Inject codesnippets for readme, update changelog Text Analytics (#7118)

Azure · Jan 6, 2020 · aec20d7 · aec20d7
1 parent ad8791d
commit aec20d7
Show file tree

Hide file tree

Showing 8 changed files with 236 additions and 68 deletions.
diff --git a/sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md b/sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md
@@ -3,14 +3,12 @@
 ## 1.0.0-beta.1 (Unreleased)
 
 For details on the Azure SDK for Java (January 2020 Preview) release refer to the [release announcement]().
-
-### Added
 - Initial release of this module.
-- Support for subscription key and AAD authentication for both synchronous and asynchronous clients.
+- Added support for subscription key and AAD authentication for both synchronous and asynchronous clients.
 - Added Detect Language, Recognize Entity, Recognize PII entity, Recognize Linking Entity, Analyze Sentiment APIs.
 
 This package's 
-[documentation]() 
+[documentation](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-textanalytics_1.0.0-beta.1/sdk/textanalytics/azure-ai-textanalytics/README.md) 
 and 
-[samples]() 
+[samples](https://github.com/Azure/azure-sdk-for-java/blob/azure-ai-textanalytics_1.0.0-beta.1/sdk/textanalytics/azure-ai-textanalytics/src/samples) 
 demonstrate the new API.
diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md
@@ -9,7 +9,7 @@ and includes six main functions:
 - Recognition of Personally Identifiable Information 
 - Linked Entity Recognition
 
-[Source code][source_code] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][samples_readme]
+[Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][samples_readme]
 
 ## Getting started
 
@@ -81,6 +81,7 @@ When an HTTP client is included on the classpath, as shown above, it is not nece
 
 For starters, by having the Netty or OkHTTP dependencies on your classpath, as shown above, you can create new instances of these `HttpClient` types using their builder APIs. For example, here is how you would create a Netty HttpClient instance:
 
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L159-L162 -->
 ```java
 HttpClient client = new NettyAsyncHttpClientBuilder()
     .port(8080)
@@ -117,7 +118,7 @@ az cognitiveservices account create \
     --yes
 ```
 ### Authenticate the client
-In order to interact with the Text Analytics service, you'll need to create an instance of the [TextAnalyticsClient](#create-ta-client) class. You would need an **endpoint** and **subscription key** to instantiate a client object.
+In order to interact with the Text Analytics service, you'll need to create an instance of the [TextAnalyticsClient](#create-a-client) class. You would need an **endpoint** and **subscription key** to instantiate a client object.
 
 #### Get credentials
 ##### Types of credentials
@@ -129,13 +130,16 @@ cognitive services.
    provide the key as a string. This can be found in the Azure Portal under the "Quickstart" 
    section or by running the following Azure CLI command:
 
-    ```az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"```
+    ```bash
+    az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"
+    ```
 
     Use the key as the credential parameter to authenticate the client:
+    <!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L29-L32 -->
     ```java
-    TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-        .subscriptionKey("subscription-key")
-        .endpoint("https://servicename.cognitiveservices.azure.com/")
+    TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+        .subscriptionKey(SUBSCRIPTION_KEY)
+        .endpoint(ENDPOINT)
         .buildClient();
     ```
 
@@ -158,11 +162,12 @@ cognitive services.
    AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET
 
    Use the returned token credential to authenticate the client:
+   <!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L49-L52 -->
     ```java
-    TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-            .endpoint("https://servicename.cognitiveservices.azure.com/")
-            .credential(new DefaultAzureCredentialBuilder().build())
-            .buildClient();
+    TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+        .endpoint(ENDPOINT)
+        .credential(new DefaultAzureCredentialBuilder().build())
+        .buildAsyncClient();
     ```
 
 #### Create a Client
@@ -171,11 +176,11 @@ analyze sentiment, recognize entities, detect language, and extract key phrases
 To create a client object, you will need the cognitive services or text analytics endpoint to 
 your resource and a subscription key that allows you access:
 
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L29-L32 -->
 ```java
-// Instantiate a client that will be used to call the service.
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 ```
 
@@ -243,115 +248,114 @@ The following sections provide several code snippets covering some of the most c
 Text analytics support both synchronous and asynchronous client creation by using
 `TextAnalyticsClientBuilder`,
 
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L29-L32 -->
 ``` java
-// An example of creating a synchronous client
-
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 ```
-
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L39-L42 -->
 ``` java
-// An example of creating an asynchronous client
-
-TextAnalyticsAsyncClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildAsyncClient();
 ```
 
 ### Detect language
-Detect language in a batch of documents.
-
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L59-L71 -->
 ```java
-TextAnalyticsAsyncClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
-    .buildAsyncClient();
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
+    .buildClient();
 
 String inputText = "Bonjour tout le monde";
 
-for(DetectedLanguage detectedLanguage : client.detectLanguage(text, "US").getDetectedLanguages()) {
-    System.out.printf("Other detected languages: %s, ISO 6391 Name: %s, Score: %s.%n",
+for (DetectedLanguage detectedLanguage : textAnalyticsClient.detectLanguage(inputText).getDetectedLanguages()) {
+    System.out.printf("Detected languages name: %s, ISO 6391 Name: %s, Score: %s.%n",
         detectedLanguage.getName(),
         detectedLanguage.getIso6391Name(),
         detectedLanguage.getScore());
 }
 ```
 
 ### Recognize entity
-
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L78-L92 -->
 ```java
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 
 String text = "Satya Nadella is the CEO of Microsoft";
 
-for (NamedEntity entity : client.recognizeEntities(text).getNamedEntities()) {
+for (NamedEntity entity : textAnalyticsClient.recognizeEntities(text).getNamedEntities()) {
     System.out.printf(
-        "Recognized NamedEntity: %s, Type: %s, Subtype: %s, Score: %s.%n",
+        "Recognized Named Entity: %s, Type: %s, Subtype: %s, Score: %s.%n",
         entity.getText(),
         entity.getType(),
         entity.getSubtype(),
-        entity.getOffset(),
-        entity.getLength(),
         entity.getScore());
 }
 ```
 
 ### Recognize PII(Personally Identifiable Information) entity
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L99-L114 -->
 ```java
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 
 // The text that need be analysed.
 String text = "My SSN is 555-55-5555";
 
-for (NamedEntity entity : client.recognizePiiEntities(text).getNamedEntities()) {
+for (NamedEntity entity : textAnalyticsClient.recognizePiiEntities(text).getNamedEntities()) {
     System.out.printf(
         "Recognized PII Entity: %s, Type: %s, Subtype: %s, Score: %s.%n",
         entity.getText(),
         entity.getType(),
         entity.getSubtype(),
-        entity.getScore()));
+        entity.getScore());
 }
 ```
 
 ### Recognize linked entity
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L121-L134 -->
+
 ```java
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 
 // The text that need be analysed.
 String text = "Old Faithful is a geyser at Yellowstone Park.";
 
-for (LinkedEntity linkedEntity : client.recognizeLinkedEntities(text).getLinkedEntities()) {
-    System.out.printf("Recognized Linked NamedEntity: %s, URL: %s, Data Source: %s.%n",
+for (LinkedEntity linkedEntity : textAnalyticsClient.recognizeLinkedEntities(text).getLinkedEntities()) {
+    System.out.printf("Recognized Linked Entity: %s, Url: %s, Data Source: %s.%n",
         linkedEntity.getName(),
-        linkedEntity.getUri(),
+        linkedEntity.getUrl(),
         linkedEntity.getDataSource());
 }
 ```
 
 ### Analyze sentiment
+<!-- embedme ./src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java#L141-L152 -->
+
 ```java
-TextAnalyticsClient client = new TextAnalyticsClientBuilder()
-    .subscriptionKey("subscription-key")
-    .endpoint("https://servicename.cognitiveservices.azure.com/")
+TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder()
+    .subscriptionKey(SUBSCRIPTION_KEY)
+    .endpoint(ENDPOINT)
     .buildClient();
 
 String text = "The hotel was dark and unclean.";
 
-for (TextSentiment textSentiment : client.analyzeSentiment(text).getSentenceSentiments()) {
+for (TextSentiment textSentiment : textAnalyticsClient.analyzeSentiment(text).getSentenceSentiments()) {
     System.out.printf(
-        "Recognized Sentence TextSentiment: %s.%n",
+        "Analyzed Sentence Sentiment class: %s.%n",
         textSentiment.getTextSentimentClass());
 }
 ```
@@ -372,11 +376,12 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m
 
 <!-- LINKS -->
 [azure_subscription]: https://azure.microsoft.com/free
-[api_reference_doc]: https://azure.github.io/azure-sdk-for-java/cognitiveservices.html
+[api_reference_doc]: https://azure.github.io/azure-sdk-for-java/textanalytics.html
 [cla]: https://cla.microsoft.com
 [coc]: https://opensource.microsoft.com/codeofconduct/
 [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/
 [coc_contact]: mailto:[email protected]
+[package]: https://mvnrepository.com/artifact/com.azure/azure-ai-textanalytics
 [product_documentation]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/overview
 [samples_readme]: src/samples/README.md
 [source_code]: src

diff --git a/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md b/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md
@@ -22,6 +22,7 @@ The following sections provide several code snippets covering some of the most c
 - [Recognize linked entities in text][sample_linked_entities]
 - [Extract key phrases in text][sample_key_phrases]
 - [Analyze sentiment in text.][sample_sentiment]
+- [Async Detect language in text][async_sample_hello_world]
 
 Batch Samples:
 - [Detect language for a batch of documents][sample_language_batch]
@@ -50,7 +51,8 @@ Guidelines](../../CONTRIBUTING.md) for more information.
 [SDK_README_DEPENDENCY]: ../../README.md#adding-the-package-to-your-product
 [SDK_README_NEXT_STEPS]: ../../README.md#next-steps
 
-[sample_hello_world]: java/com/azure/ai/textanalytics/HelloWorld.java
+[async_sample_hello_world]: java/com/azure/ai/textanalytics/DetectLanguageAsync.java
+[sample_hello_world]: java/com/azure/ai/textanalytics/DetectLanguage.java
 [sample_entities]: java/com/azure/ai/textanalytics/RecognizeEntities.java
 [sample_pii_entities]: java/com/azure/ai/textanalytics/RecognizePii.java
 [sample_linked_entities]: java/com/azure/ai/textanalytics/RecognizeLinkedEntities.java

diff --git a/...e-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/AnalyzeSentimentAsync.java b/...e-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/AnalyzeSentimentAsync.java
@@ -5,7 +5,6 @@
 
 import com.azure.ai.textanalytics.models.TextSentiment;
 
-import java.util.List;
 import java.util.concurrent.TimeUnit;
 
 /**

diff --git a/...om/azure/ai/textanalytics/HelloWorld.java → ...zure/ai/textanalytics/DetectLanguage.java b/...om/azure/ai/textanalytics/HelloWorld.java → ...zure/ai/textanalytics/DetectLanguage.java
@@ -9,7 +9,7 @@
 /**
  * Sample demonstrates how to detect the language of an input text.
  */
-public class HelloWorld {
+public class DetectLanguage {
     /**
      * Main method to invoke this demo about how to detect the language of an input text.
      *

diff --git a/...ure/ai/textanalytics/HelloWorldAsync.java → ...ai/textanalytics/DetectLanguageAsync.java b/...ure/ai/textanalytics/HelloWorldAsync.java → ...ai/textanalytics/DetectLanguageAsync.java
@@ -10,7 +10,7 @@
 /**
  * Sample demonstrates how to asynchronously detect the language of an input text.
  */
-public class HelloWorldAsync {
+public class DetectLanguageAsync {
     /**
      * Main method to invoke this demo about how to detect the language of an input text.
      *
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,6 @@ @@
     import com.azure.ai.textanalytics.models.TextSentiment;
-    import java.util.List;
     import java.util.concurrent.TimeUnit;
     /**
@@ Expand Down @@