diff --git a/sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md b/sdk/textanalytics/azure-ai-textanalytics/CHANGELOG.md index 3c3d47dc2d7b..baa9b42aca21 100644 --- 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 index 67d4391f5d04..3ebd3cec3960 100644 --- 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: + ```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: + ```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: + ```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: + ```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,37 +248,33 @@ 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`, + ``` 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(); ``` - + ``` 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. - + ```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()); @@ -281,77 +282,80 @@ for(DetectedLanguage detectedLanguage : client.detectLanguage(text, "US").getDet ``` ### Recognize entity - + ```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 + ```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 + + ```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 + + ```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 [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:opencode@microsoft.com +[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 index 4d4112db8782..e0a37e74a2b4 100644 --- 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/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/AnalyzeSentimentAsync.java b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/AnalyzeSentimentAsync.java index 1f494bd95532..66339c3867bd 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/AnalyzeSentimentAsync.java +++ b/sdk/textanalytics/azure-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/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorld.java b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/DetectLanguage.java similarity index 98% rename from sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorld.java rename to sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/DetectLanguage.java index 494f72b72f63..32eddc8f19e0 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorld.java +++ b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/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/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorldAsync.java b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/DetectLanguageAsync.java similarity index 98% rename from sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorldAsync.java rename to sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/DetectLanguageAsync.java index d53fb874279e..a1dc376928d1 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/HelloWorldAsync.java +++ b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/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. * diff --git a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java new file mode 100644 index 000000000000..d78116526e29 --- /dev/null +++ b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/ReadmeSamples.java @@ -0,0 +1,164 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +package com.azure.ai.textanalytics; + +import com.azure.ai.textanalytics.models.DetectedLanguage; +import com.azure.ai.textanalytics.models.LinkedEntity; +import com.azure.ai.textanalytics.models.NamedEntity; +import com.azure.ai.textanalytics.models.TextSentiment; +import com.azure.core.http.HttpClient; +import com.azure.core.http.netty.NettyAsyncHttpClientBuilder; +import com.azure.identity.DefaultAzureCredentialBuilder; + +/** + * WARNING: MODIFYING THIS FILE WILL REQUIRE CORRESPONDING UPDATES TO README.md FILE. LINE NUMBERS ARE USED TO EXTRACT + * APPROPRIATE CODE SEGMENTS FROM THIS FILE. ADD NEW CODE AT THE BOTTOM TO AVOID CHANGING LINE NUMBERS OF EXISTING CODE + * SAMPLES. + * + * Class containing code snippets that will be injected to README.md. + */ +public class ReadmeSamples { + private static final String SUBSCRIPTION_KEY = null; + private static final String ENDPOINT = null; + + /** + * Code snippet for getting sync client using subscription key authentication. + */ + public void useSubscriptionKeySyncClient() { + TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .subscriptionKey(SUBSCRIPTION_KEY) + .endpoint(ENDPOINT) + .buildClient(); + } + + /** + * Code snippet for getting async client using subscription key authentication. + */ + public void useSubscriptionKeyAsyncClient() { + TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .subscriptionKey(SUBSCRIPTION_KEY) + .endpoint(ENDPOINT) + .buildAsyncClient(); + } + + /** + * Code snippet for getting async client using AAD authentication. + */ + public void useAadAsyncClient() { + TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .endpoint(ENDPOINT) + .credential(new DefaultAzureCredentialBuilder().build()) + .buildAsyncClient(); + } + + /** + * Code snippet for detecting language in a text. + */ + public void detectLanguages() { + TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .subscriptionKey(SUBSCRIPTION_KEY) + .endpoint(ENDPOINT) + .buildClient(); + + String inputText = "Bonjour tout le monde"; + + 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()); + } + } + + /** + * Code snippet for recognizing named entity in a text. + */ + public void recognizeNamedEntity() { + TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .subscriptionKey(SUBSCRIPTION_KEY) + .endpoint(ENDPOINT) + .buildClient(); + + String text = "Satya Nadella is the CEO of Microsoft"; + + for (NamedEntity entity : textAnalyticsClient.recognizeEntities(text).getNamedEntities()) { + System.out.printf( + "Recognized Named Entity: %s, Type: %s, Subtype: %s, Score: %s.%n", + entity.getText(), + entity.getType(), + entity.getSubtype(), + entity.getScore()); + } + } + + /** + * Code snippet for recognizing pii entity in a text. + */ + public void recognizePiiEntity() { + 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 : 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()); + } + } + + /** + * Code snippet for recognizing linked entity in a text. + */ + public void recognizeLinkedEntity() { + 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 : textAnalyticsClient.recognizeLinkedEntities(text).getLinkedEntities()) { + System.out.printf("Recognized Linked Entity: %s, Url: %s, Data Source: %s.%n", + linkedEntity.getName(), + linkedEntity.getUrl(), + linkedEntity.getDataSource()); + } + } + + /** + * Code snippet for analyzing sentiment of a text. + */ + public void analyzeSentiment() { + TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() + .subscriptionKey(SUBSCRIPTION_KEY) + .endpoint(ENDPOINT) + .buildClient(); + + String text = "The hotel was dark and unclean."; + + for (TextSentiment textSentiment : textAnalyticsClient.analyzeSentiment(text).getSentenceSentiments()) { + System.out.printf( + "Analyzed Sentence Sentiment class: %s.%n", + textSentiment.getTextSentimentClass()); + } + } + + /** + * Code snippet for configuring http client. + */ + public void configureHttpClient() { + HttpClient client = new NettyAsyncHttpClientBuilder() + .port(8080) + .wiretap(true) + .build(); + } +} diff --git a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/RecognizePiiAsync.java b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/RecognizePiiAsync.java index afd58791a33a..3186b57f3cf9 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/RecognizePiiAsync.java +++ b/sdk/textanalytics/azure-ai-textanalytics/src/samples/java/com/azure/ai/textanalytics/RecognizePiiAsync.java @@ -33,7 +33,7 @@ public static void main(String[] args) { System.out.printf( "Recognized personal identifiable information entity: %s, entity type: %s, entity subtype: %s, offset: %s, length: %s, score: %s.%n", entity.getText(), - entity.getType() , + entity.getType(), entity.getSubtype() == null || entity.getSubtype().isEmpty() ? "N/A" : entity.getSubtype(), entity.getOffset(), entity.getLength(),