From 007c0511cab57b29899548e41fb8b45d8f54a493 Mon Sep 17 00:00:00 2001 From: shafang Date: Tue, 12 May 2020 23:20:59 -0700 Subject: [PATCH 01/10] update readme to align with .net and python --- .../azure-ai-textanalytics/README.md | 94 +++++++++++++------ .../src/samples/README.md | 3 +- 2 files changed, 67 insertions(+), 30 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 116121544709..bfac6f2fafbf 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -28,8 +28,8 @@ and includes six main functions: ``` [//]: # ({x-version-update-end}) - -### Create a Text Analytics resource +### Authenticate the client +#### Create a Cognitive Services or Text Analytics resource Text Analytics supports both [multi-service and single-service access][service_access]. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Text Analytics access only, create a Text Analytics resource. @@ -58,8 +58,7 @@ az cognitiveservices account create \ --location westus2 \ --yes ``` -### Authenticate the client -In order to interact with the Text Analytics service, you will need to create an instance of the `TextAnalyticsClient` +In order to interact with the Text Analytics service, you will need to create an instance of the [TextAnalyticsClient][text_analytics_sync_client] class. You will need an **endpoint** and either an **API key** or **AAD TokenCredential** to instantiate a client object. And they can be found in the [Azure Portal][azure_portal] under the "Quickstart" in your created Text Analytics resource. See the full details regarding [authentication][authentication] of Cognitive Services. @@ -67,15 +66,16 @@ Text Analytics resource. See the full details regarding [authentication][authent #### Get credentials The authentication credential may be provided as the API key to your resource or as a token from Azure Active Directory. - -##### **Option 1**: Create TextAnalyticsClient with AzureKeyCredential -To use AzureKeyCredential authentication, provide the [key][key] as a string to the [AzureKeyCredential][azure_key_credential]. This can be found in the [Azure Portal][azure_portal] - under the "Quickstart" section or by running the following Azure CLI command: +##### **Option 1**: Create TextAnalyticsClient with API Key Credential +Once you have the value for the API key, provide the [key][key] as a string to the [AzureKeyCredential][azure_key_credential]. +This can be found in the [Azure Portal][azure_portal] under the "Quickstart" section in your created Text Analytics resource +or by running the following Azure CLI command: ```bash az cognitiveservices account keys list --resource-group --name ``` -Use the key as the credential parameter to authenticate the client: + +With the value of endpoint and an `AzureKeyCredential`, you can create the [TextAnalyticsClient][text_analytics_sync_client]: ```java TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() @@ -130,11 +130,18 @@ asynchronous operations to access a specific use of Text Analytics, such as lang ### Input A **text input**, also called a **document**, is a single unit of document to be analyzed by the predictive models -in the Text Analytics service. Operations on Text Analytics client may take a single document or a collection +in the Text Analytics service. Operations on `TextAnalyticsClient` may take a single document or a collection of documents to be analyzed as a batch. See [service limitations][service_input_limitation] for the document, including document length limits, maximum batch size, and supported text encoding. +### Operation on multiple documents +For each supported operation, the `TextAnalyticsClient` provides method overloads to take a single document, a batch +of documents as strings, or a batch of either `TextDocumentInput` or `DetectLanguageInput` objects. The overload +taking the `TextDocumentInput` or `DetectLanguageInput` batch allows callers to give each document a unique ID, +indicate that the documents in the batch are written in different languages, or provide a country hint about the +language of the document. + ### Return value An operation result, such as `AnalyzeSentimentResult`, is the result of a Text Analytics operation, containing a prediction or predictions about a single document and a list of warnings inside of it. An operation's result type also @@ -150,13 +157,6 @@ An operation result collection, such as `TextAnalyticsPagedResponse ```java String document = "The hotel was dark and unclean. I like microsoft."; @@ -223,8 +232,12 @@ System.out.printf("Analyzed document sentiment: %s.%n", documentSentiment.getSen documentSentiment.getSentences().forEach(sentenceSentiment -> System.out.printf("Analyzed sentence sentiment: %s.%n", sentenceSentiment.getSentiment())); ``` +For samples on using the production recommended option `AnalyzeSentimentBatch` see [here][analyze_sentiment_sample]. +Please refer to the service documentation for a conceptual discussion of [sentiment analysis][sentiment_analysis]. ### Detect language +Run a Text Analytics predictive model to determine the language that the passed-in document or batch of documents are written in. + ```java String document = "Bonjour tout le monde"; @@ -232,8 +245,26 @@ DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document) System.out.printf("Detected language name: %s, ISO 6391 name: %s, confidence score: %f.%n", detectedLanguage.getName(), detectedLanguage.getIso6391Name(), detectedLanguage.getConfidenceScore()); ``` +For samples on using the production recommended option `DetectLanguageBatch` see [here][detect_language_sample]. +Please refer to the service documentation for a conceptual discussion of [language detection][language_detection]. + +### Extract key phrases +Run a model to identify a collection of significant phrases found in the passed-in document or batch of documents. + + +```java +String document = "My cat might need to see a veterinarian."; +System.out.println("Extracted phrases:"); +textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase)); +``` +For samples on using the production recommended option `ExtractKeyPhrasesBatch` see [here][extract_key_phrases_sample]. +Please refer to the service documentation for a conceptual discussion of [key phrase extraction][key_phrase_extraction]. ### Recognize entity +Run a predictive model to identify a collection of named entities in the passed-in document or batch of documents and +categorize those entities into categories such as person, location, or organization. For more information on available +categories, see [Text Analytics Named Entity Categories][named_entities_categories]. + ```java String document = "Satya Nadella is the CEO of Microsoft"; @@ -241,8 +272,13 @@ textAnalyticsClient.recognizeEntities(document).forEach(entity -> System.out.printf("Recognized entity: %s, category: %s, subcategory: %s, confidence score: %f.%n", entity.getText(), entity.getCategory(), entity.getSubcategory(), entity.getConfidenceScore())); ``` +For samples on using the production recommended option `RecognizeEntitiesBatch` see [here][recognize_entities_sample]. +Please refer to the service documentation for a conceptual discussion of [named entity recognition][named_entity_recognition]. ### Recognize linked entity +Run a predictive model to identify a collection of entities found in the passed-in document or batch of documents, +and include information linking the entities to their corresponding entries in a well-known knowledge base. + ```java @@ -255,16 +291,11 @@ textAnalyticsClient.recognizeLinkedEntities(document).forEach(linkedEntity -> { System.out.printf("Text: %s, confidence score: %f.%n", match.getText(), match.getConfidenceScore())); }); ``` -### Extract key phrases - -```java -String document = "My cat might need to see a veterinarian."; -System.out.println("Extracted phrases:"); -textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out.printf("%s.%n", keyPhrase)); -``` +For samples on using the production recommended option `RecognizeLinkedEntitiesBatch` see [here][recognize_linked_entities_sample]. +Please refer to the service documentation for a conceptual discussion of [entity linking][named_entity_recognition]. + -The above examples cover the scenario of having a single document as input. -For more examples, such as batch operation, refer to [here][samples_readme]. +For more examples, such as asynchronous samples, refer to [here][samples_readme]. ## Troubleshooting ### General @@ -338,19 +369,26 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [language_regional_support]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support [named_entity_recognition]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-entity-linking [named_entity_recognition_types]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/named-entity-types?tabs=personal +[named_entities_categories]: https://docs.microsoft.com/azure/cognitive-services/Text-Analytics/named-entity-types [package]: https://mvnrepository.com/artifact/com.azure/azure-ai-textanalytics [performance_tuning]: https://github.com/Azure/azure-sdk-for-java/wiki/Performance-Tuning [product_documentation]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/overview [register_AAD_application]: https://docs.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal -[samples_readme]: src/samples/README.md [service_access]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows [service_input_limitation]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/overview#data-limits [sentiment_analysis]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-sentiment-analysis [source_code]: src -[supported_language]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support#language-detection +[supported_languages]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/language-support#language-detection [text_analytics_account]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows [text_analytics_async_client]: src/main/java/com/azure/ai/textanalytics/TextAnalyticsAsyncClient.java [text_analytics_sync_client]: src/main/java/com/azure/ai/textanalytics/TextAnalyticsClient.java [LogLevels]: ../../core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java +[samples_readme]: src/samples/README.md +[detect_language_sample]: src/samples/java/com/azure/ai/textanalytics/batch/DetectLanguageBatchDocuments.java +[analyze_sentiment_sample]: src/samples/java/com/azure/ai/textanalytics/batch/AnalyzeSentimentBatchDocuments.java +[extract_key_phrases_sample]: src/samples/java/com/azure/ai/textanalytics/batch/ExtractKeyPhrasesBatchDocuments.java +[recognize_entities_sample]: src/samples/java/com/azure/ai/textanalytics/batch/RecognizeEntitiesBatchDocuments.java +[recognize_linked_entities_sample]: src/samples/java/com/azure/ai/textanalytics/batch/RecognizeLinkedEntitiesBatchDocuments.java + ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Ftextanalytics%2Fazure-ai-textanalytics%2FREADME.png) diff --git a/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md b/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md index 426a5402f6e5..7bb2213f8954 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/src/samples/README.md @@ -63,8 +63,7 @@ Troubleshooting steps can be found [here][SDK_README_TROUBLESHOOTING]. See [Next steps][SDK_README_NEXT_STEPS]. ## Contributing -If you would like to become an active contributor to this project please refer to our [Contribution -Guidelines](../../CONTRIBUTING.md) for more information. +This project welcomes contributions and suggestions. Find [more contributing][SDK_README_CONTRIBUTING] details here. [KEYS_SDK_README]: ../../README.md From 5dec052fb379164efe218b2945c23393fdbff541 Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 13:01:29 -0700 Subject: [PATCH 02/10] remove ref links to python repo and revisited authentication section readme --- .../azure-ai-textanalytics/README.md | 97 +++++++++++-------- .../azure/ai/textanalytics/ReadmeSamples.java | 4 +- 2 files changed, 60 insertions(+), 41 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index bfac6f2fafbf..0d3359d23dd6 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -58,34 +58,40 @@ az cognitiveservices account create \ --location westus2 \ --yes ``` -In order to interact with the Text Analytics service, you will need to create an instance of the [TextAnalyticsClient][text_analytics_sync_client] -class. You will need an **endpoint** and either an **API key** or **AAD TokenCredential** to instantiate a client -object. And they can be found in the [Azure Portal][azure_portal] under the "Quickstart" in your created -Text Analytics resource. See the full details regarding [authentication][authentication] of Cognitive Services. +In order to interact with the Text Analytics service, you will need to create an instance of the Text Analytics client, +both the asynchronous and synchronous clients can be created by using `TextAnalyticsClientBuilder` invoking `buildClient()` +creates a synchronous client while `buildAsyncClient()` creates its asynchronous counterpart. -#### Get credentials -The authentication credential may be provided as the API key to your resource or as a token from Azure Active Directory. +You will need an **endpoint** and either an **key** or **AAD TokenCredential** to instantiate a client object. -##### **Option 1**: Create TextAnalyticsClient with API Key Credential -Once you have the value for the API key, provide the [key][key] as a string to the [AzureKeyCredential][azure_key_credential]. -This can be found in the [Azure Portal][azure_portal] under the "Quickstart" section in your created Text Analytics resource -or by running the following Azure CLI command: +##### Looking up the endpoint +You can find the **endpoint** for your Text Analytics resource in the [Azure Portal][azure_portal] under the "Keys and Endpoint", +or [Azure CLI][azure_cli_endpoint]. +```bash +# Get the endpoint for the text analytics resource +az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint" +``` + +##### Create a Text Analytics client with key credential +Once you have the value for the [key][key], provide it as a string to the [AzureKeyCredential][azure_key_credential]. +This can be found in the [Azure Portal][azure_portal] under the "Keys and Endpoint" section in your created Text Analytics +resource or by running the following Azure CLI command: ```bash az cognitiveservices account keys list --resource-group --name ``` -With the value of endpoint and an `AzureKeyCredential`, you can create the [TextAnalyticsClient][text_analytics_sync_client]: - +Use the key as the credential parameter to authenticate the client: + ```java TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() .credential(new AzureKeyCredential("{key}")) .endpoint("{endpoint}") .buildClient(); ``` -The Azure Text Analytics client library provides a way to **rotate the existing key**. - +The Azure Text Analytics client library provides a way to **rotate the existing key**. + ```java AzureKeyCredential credential = new AzureKeyCredential("{key}"); TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() @@ -95,30 +101,40 @@ TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() credential.update("{new_key}"); ``` -##### **Option 2**: Create TextAnalyticsClient with Azure Active Directory Credential -To use an [Azure Active Directory (AAD) token credential][aad_credential], -provide an instance of the desired credential type obtained from the [azure-identity][azure_identity] library. -Note that regional endpoints do not support AAD authentication. Create a [custom subdomain][custom_subdomain] -name for your resource in order to use this type of authentication. +##### Create a Text Analytics client using Microsoft identity platform (formerly Azure Active Directory) +Azure SDK for Java supports an Azure Identity package, making it easy to get credentials from Microsoft identity +platform. Authentication with AAD requires some initial setup: -* [Install azure-identity][install_azure_identity] +* Add the Azure Identity package + +[//]: # ({x-version-update-start;com.azure:azure-identity;dependency}) +```xml + + com.azure + azure-identity + 1.0.6 + +``` +[//]: # ({x-version-update-end}) * [Register a new AAD application][register_AAD_application] * [Grant access][grant_access] to Text Analytics by assigning the `"Cognitive Services User"` role to your service principal. -After setup, you can choose which type of [credential][credential_type] from azure.identity to use. -As an example, [DefaultAzureCredential][default_azure_credential] -can be used to authenticate the client: - +After setup, you can choose which type of [credential][azure_identity_credential_type] from azure.identity to use. +As an example, [DefaultAzureCredential][wiki_identity] can be used to authenticate the client: Set the values of the client ID, tenant ID, and client secret of the AAD application as environment variables: -AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. +AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. + +Authorization is easiest using [DefaultAzureCredential][wiki_identity]. It finds the best credential to use in its +running environment. For more information about using Azure Active Directory authorization with Text Analytics, please +refer to [the associated documentation][aad_authorization]. -Use the returned token credential to authenticate the client: - + ```java +DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() .endpoint("{endpoint}") - .credential(new DefaultAzureCredentialBuilder().build()) + .credential(defaultCredential) .buildAsyncClient(); ``` @@ -205,14 +221,14 @@ 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 TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() .credential(new AzureKeyCredential("{key}")) .endpoint("{endpoint}") .buildClient(); ``` - + ``` java TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() .credential(new AzureKeyCredential("{key}")) @@ -224,7 +240,7 @@ TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() Run a Text Analytics predictive model to identify the positive, negative, neutral or mixed sentiment contained in the passed-in document or batch of documents. - + ```java String document = "The hotel was dark and unclean. I like microsoft."; DocumentSentiment documentSentiment = textAnalyticsClient.analyzeSentiment(document); @@ -238,7 +254,7 @@ Please refer to the service documentation for a conceptual discussion of [sentim ### Detect language Run a Text Analytics predictive model to determine the language that the passed-in document or batch of documents are written in. - + ```java String document = "Bonjour tout le monde"; DetectedLanguage detectedLanguage = textAnalyticsClient.detectLanguage(document); @@ -251,7 +267,7 @@ Please refer to the service documentation for a conceptual discussion of [langua ### Extract key phrases Run a model to identify a collection of significant phrases found in the passed-in document or batch of documents. - + ```java String document = "My cat might need to see a veterinarian."; System.out.println("Extracted phrases:"); @@ -265,7 +281,7 @@ Run a predictive model to identify a collection of named entities in the passed- categorize those entities into categories such as person, location, or organization. For more information on available categories, see [Text Analytics Named Entity Categories][named_entities_categories]. - + ```java String document = "Satya Nadella is the CEO of Microsoft"; textAnalyticsClient.recognizeEntities(document).forEach(entity -> @@ -279,7 +295,7 @@ Please refer to the service documentation for a conceptual discussion of [named Run a predictive model to identify a collection of entities found in the passed-in document or batch of documents, and include information linking the entities to their corresponding entries in a well-known knowledge base. - + ```java String document = "Old Faithful is a geyser at Yellowstone Park."; @@ -303,7 +319,7 @@ Text Analytics clients raise exceptions. For example, if you try to detect the l document IDs, `400` error is return that indicating bad request. In the following code snippet, the error is handled gracefully by catching the exception and display the additional information about the error. - + ```java List documents = Arrays.asList( new DetectLanguageInput("1", "This is written in English.", "us"), @@ -345,11 +361,14 @@ When you submit a pull request, a CLA-bot will automatically determine whether y This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. +[aad_authorization]: https://docs.microsoft.com/en-us/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [aad_credential]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [api_reference_doc]: https://aka.ms/azsdk-java-textanalytics-ref-docs [authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication [azure_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli?tabs=windows -[azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#credentials +[azure_cli_endpoint]: https://docs.microsoft.com/en-us/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show +[azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity +[azure_identity_credential_type]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity#credentials [azure_key_credential]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/credential/AzureKeyCredential.java [azure_portal]: https://ms.portal.azure.com [azure_subscription]: https://azure.microsoft.com/free @@ -358,11 +377,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [coc_contact]: mailto:opencode@microsoft.com [create_new_resource]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows#create-a-new-azure-cognitive-services-resource -[credential_type]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#credentials [custom_subdomain]: https://docs.microsoft.com/azure/cognitive-services/authentication#create-a-resource-with-a-custom-subdomain -[default_azure_credential]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#defaultazurecredential [grant_access]: https://docs.microsoft.com/azure/cognitive-services/authentication#assign-a-role-to-a-service-principal -[install_azure_identity]: https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/identity/azure-identity#install-the-package [key]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows#get-the-keys-for-your-resource [key_phrase_extraction]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-keyword-extraction [language_detection]: https://docs.microsoft.com/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-language-detection @@ -382,6 +398,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [text_analytics_account]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account?tabs=multiservice%2Cwindows [text_analytics_async_client]: src/main/java/com/azure/ai/textanalytics/TextAnalyticsAsyncClient.java [text_analytics_sync_client]: src/main/java/com/azure/ai/textanalytics/TextAnalyticsClient.java +[wiki_identity]: https://github.com/Azure/azure-sdk-for-java/wiki/Identity-and-Authentication [LogLevels]: ../../core/azure-core/src/main/java/com/azure/core/util/logging/ClientLogger.java [samples_readme]: src/samples/README.md 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 index de08ebd1aea1..3090756d99ec 100644 --- 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 @@ -11,6 +11,7 @@ import com.azure.core.http.HttpClient; import com.azure.core.http.netty.NettyAsyncHttpClientBuilder; import com.azure.core.util.Context; +import com.azure.identity.DefaultAzureCredential; import com.azure.identity.DefaultAzureCredentialBuilder; import java.util.Arrays; @@ -60,9 +61,10 @@ public void useAzureKeyCredentialAsyncClient() { * Code snippet for getting async client using AAD authentication. */ public void useAadAsyncClient() { + DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() .endpoint("{endpoint}") - .credential(new DefaultAzureCredentialBuilder().build()) + .credential(defaultCredential) .buildAsyncClient(); } From 6651f957ef4419bf48f3c20f30abdf6607e4a8ea Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 13:05:06 -0700 Subject: [PATCH 03/10] Use Text Analytics client instead of TextAnalyticsClient since we have sync and async --- sdk/textanalytics/azure-ai-textanalytics/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 0d3359d23dd6..3c92c8520941 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -146,13 +146,13 @@ asynchronous operations to access a specific use of Text Analytics, such as lang ### Input A **text input**, also called a **document**, is a single unit of document to be analyzed by the predictive models -in the Text Analytics service. Operations on `TextAnalyticsClient` may take a single document or a collection +in the Text Analytics service. Operations on a Text Analytics client may take a single document or a collection of documents to be analyzed as a batch. See [service limitations][service_input_limitation] for the document, including document length limits, maximum batch size, and supported text encoding. ### Operation on multiple documents -For each supported operation, the `TextAnalyticsClient` provides method overloads to take a single document, a batch +For each supported operation, the Text Analytics client provides method overloads to take a single document, a batch of documents as strings, or a batch of either `TextDocumentInput` or `DetectLanguageInput` objects. The overload taking the `TextDocumentInput` or `DetectLanguageInput` batch allows callers to give each document a unique ID, indicate that the documents in the batch are written in different languages, or provide a country hint about the From 9bbe41a9e12fa0b2a505cdbd885ecaf5377a8db3 Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 13:39:43 -0700 Subject: [PATCH 04/10] address feedbacks --- sdk/textanalytics/azure-ai-textanalytics/README.md | 6 +++--- .../java/com/azure/ai/textanalytics/ReadmeSamples.java | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 3c92c8520941..a7f9d984e972 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -117,7 +117,7 @@ Authentication with AAD requires some initial setup: ``` [//]: # ({x-version-update-end}) -* [Register a new AAD application][register_AAD_application] +* [Register a new Azure Active Directory application][register_AAD_application] * [Grant access][grant_access] to Text Analytics by assigning the `"Cognitive Services User"` role to your service principal. After setup, you can choose which type of [credential][azure_identity_credential_type] from azure.identity to use. @@ -131,7 +131,7 @@ refer to [the associated documentation][aad_authorization]. ```java -DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); +TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() .endpoint("{endpoint}") .credential(defaultCredential) @@ -252,7 +252,7 @@ For samples on using the production recommended option `AnalyzeSentimentBatch` s Please refer to the service documentation for a conceptual discussion of [sentiment analysis][sentiment_analysis]. ### Detect language -Run a Text Analytics predictive model to determine the language that the passed-in document or batch of documents are written in. +Run a Text Analytics predictive model to determine the language that the provided document or batch of documents are written in. ```java 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 index 3090756d99ec..fa6217a84059 100644 --- 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 @@ -7,11 +7,11 @@ import com.azure.ai.textanalytics.models.DetectedLanguage; import com.azure.ai.textanalytics.models.DocumentSentiment; import com.azure.core.credential.AzureKeyCredential; +import com.azure.core.credential.TokenCredential; import com.azure.core.exception.HttpResponseException; import com.azure.core.http.HttpClient; import com.azure.core.http.netty.NettyAsyncHttpClientBuilder; import com.azure.core.util.Context; -import com.azure.identity.DefaultAzureCredential; import com.azure.identity.DefaultAzureCredentialBuilder; import java.util.Arrays; @@ -61,7 +61,7 @@ public void useAzureKeyCredentialAsyncClient() { * Code snippet for getting async client using AAD authentication. */ public void useAadAsyncClient() { - DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); + TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build(); TextAnalyticsAsyncClient textAnalyticsClient = new TextAnalyticsClientBuilder() .endpoint("{endpoint}") .credential(defaultCredential) From db3e29afc3c32081e9a4644b9ea095ace6e8b9bb Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 19:39:11 -0700 Subject: [PATCH 05/10] added table content --- .../azure-ai-textanalytics/README.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index a7f9d984e972..922bc61b45d9 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -10,6 +10,30 @@ and includes six main functions: [Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][samples_readme] +## Table of contents +- [Table of contents](#table-of-contents) +- [Getting started](#getting-started) + - [Prerequisites](#prerequisites) + - [Including the package](#include-the-package) + - [Authenticate the client](#authenticate-the-client) + - [Looking up the endpoint](#looking-up-the-endpoint) + - [Create a Cognitive Services or Text Analytics resource](#create-a-cognitive-services-or-text-analytics-resource) + - [Create a Text Analytics client using Microsoft identity platform (formerly Azure Active Directory)](#create-a-text-analytics-client-using-microsoft-identity-platform-formerly-azure-active-directory) +- [Key concepts](#key-concepts) + - [Client](#client) + - [Input](#input) + - [Operation on multiple documents](#operation-on-multiple-documents) + - [Return value](#return-value) + - [Return value collection](#return-value-collection) +- [Examples](#examples) +- [Troubleshooting](#troubleshooting) + - [General](#general) + - [Enable client logging](#enable-client-logging) + - [Default HTTP Client](#default-http-client) + - [Default SSL library](#default-ssl-library) +- [Next steps](#next-steps) +- [Contributing](#contributing) + ## Getting started ### Prerequisites From b5518a4c92e4c80c5b90e86a8377c85bccf2b161 Mon Sep 17 00:00:00 2001 From: Shawn Fang <45607042+mssfang@users.noreply.github.com> Date: Thu, 14 May 2020 21:19:24 -0700 Subject: [PATCH 06/10] Update sdk/textanalytics/azure-ai-textanalytics/README.md Co-authored-by: Mariana Rios Flores --- sdk/textanalytics/azure-ai-textanalytics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 922bc61b45d9..2a308d7adaaa 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -86,7 +86,7 @@ In order to interact with the Text Analytics service, you will need to create an both the asynchronous and synchronous clients can be created by using `TextAnalyticsClientBuilder` invoking `buildClient()` creates a synchronous client while `buildAsyncClient()` creates its asynchronous counterpart. -You will need an **endpoint** and either an **key** or **AAD TokenCredential** to instantiate a client object. +You will need an **endpoint** and either a **key** or **AAD TokenCredential** to instantiate a client object. ##### Looking up the endpoint You can find the **endpoint** for your Text Analytics resource in the [Azure Portal][azure_portal] under the "Keys and Endpoint", From 80f3def7b62a5ed359fda5510c0273eb4d89fcfa Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 21:52:43 -0700 Subject: [PATCH 07/10] correct wrong link --- sdk/textanalytics/azure-ai-textanalytics/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 922bc61b45d9..0c87eb67fd1c 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -300,7 +300,7 @@ textAnalyticsClient.extractKeyPhrases(document).forEach(keyPhrase -> System.out. For samples on using the production recommended option `ExtractKeyPhrasesBatch` see [here][extract_key_phrases_sample]. Please refer to the service documentation for a conceptual discussion of [key phrase extraction][key_phrase_extraction]. -### Recognize entity +### Recognize entities Run a predictive model to identify a collection of named entities in the passed-in document or batch of documents and categorize those entities into categories such as person, location, or organization. For more information on available categories, see [Text Analytics Named Entity Categories][named_entities_categories]. @@ -315,7 +315,7 @@ textAnalyticsClient.recognizeEntities(document).forEach(entity -> For samples on using the production recommended option `RecognizeEntitiesBatch` see [here][recognize_entities_sample]. Please refer to the service documentation for a conceptual discussion of [named entity recognition][named_entity_recognition]. -### Recognize linked entity +### Recognize linked entities Run a predictive model to identify a collection of entities found in the passed-in document or batch of documents, and include information linking the entities to their corresponding entries in a well-known knowledge base. From 938c72aae3475839bfb725fc10506e06af80689f Mon Sep 17 00:00:00 2001 From: shafang Date: Thu, 14 May 2020 21:55:36 -0700 Subject: [PATCH 08/10] remove en-us in link --- sdk/textanalytics/azure-ai-textanalytics/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 0c87eb67fd1c..a794e2e0e22f 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -385,12 +385,12 @@ When you submit a pull request, a CLA-bot will automatically determine whether y This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For more information see the [Code of Conduct FAQ][coc_faq] or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. -[aad_authorization]: https://docs.microsoft.com/en-us/azure/cognitive-services/authentication#authenticate-with-azure-active-directory +[aad_authorization]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [aad_credential]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [api_reference_doc]: https://aka.ms/azsdk-java-textanalytics-ref-docs [authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication [azure_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli?tabs=windows -[azure_cli_endpoint]: https://docs.microsoft.com/en-us/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show +[azure_cli_endpoint]: https://docs.microsoft.com/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show [azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity [azure_identity_credential_type]: https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/identity/azure-identity#credentials [azure_key_credential]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/credential/AzureKeyCredential.java From 5fac7ded7da3a8102511c14d09ee72275bdd870c Mon Sep 17 00:00:00 2001 From: shafang Date: Mon, 18 May 2020 12:18:22 -0700 Subject: [PATCH 09/10] remove ToC and used a correct link --- .../azure-ai-textanalytics/README.md | 28 ++----------------- 1 file changed, 2 insertions(+), 26 deletions(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index ff2627c3076c..7cf14acf231f 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -10,30 +10,6 @@ and includes six main functions: [Source code][source_code] | [Package (Maven)][package] | [API reference documentation][api_reference_doc] | [Product Documentation][product_documentation] | [Samples][samples_readme] -## Table of contents -- [Table of contents](#table-of-contents) -- [Getting started](#getting-started) - - [Prerequisites](#prerequisites) - - [Including the package](#include-the-package) - - [Authenticate the client](#authenticate-the-client) - - [Looking up the endpoint](#looking-up-the-endpoint) - - [Create a Cognitive Services or Text Analytics resource](#create-a-cognitive-services-or-text-analytics-resource) - - [Create a Text Analytics client using Microsoft identity platform (formerly Azure Active Directory)](#create-a-text-analytics-client-using-microsoft-identity-platform-formerly-azure-active-directory) -- [Key concepts](#key-concepts) - - [Client](#client) - - [Input](#input) - - [Operation on multiple documents](#operation-on-multiple-documents) - - [Return value](#return-value) - - [Return value collection](#return-value-collection) -- [Examples](#examples) -- [Troubleshooting](#troubleshooting) - - [General](#general) - - [Enable client logging](#enable-client-logging) - - [Default HTTP Client](#default-http-client) - - [Default SSL library](#default-ssl-library) -- [Next steps](#next-steps) -- [Contributing](#contributing) - ## Getting started ### Prerequisites @@ -125,7 +101,7 @@ TextAnalyticsClient textAnalyticsClient = new TextAnalyticsClientBuilder() credential.update("{new_key}"); ``` -##### Create a Text Analytics client using Microsoft identity platform (formerly Azure Active Directory) +##### Create a Text Analytics client with Azure Active Directory credential Azure SDK for Java supports an Azure Identity package, making it easy to get credentials from Microsoft identity platform. @@ -387,7 +363,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [aad_authorization]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [aad_credential]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory -[api_reference_doc]: https://aka.ms/azsdk-java-textanalytics-ref-docs +[api_reference_doc]: https://docs.microsoft.com/java/api/overview/azure/textanalytics?view=azure-java-preview [authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication [azure_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli?tabs=windows [azure_cli_endpoint]: https://docs.microsoft.com/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show From 0c23f5512625974a35374d8c6b9b61f23793c742 Mon Sep 17 00:00:00 2001 From: shafang Date: Mon, 18 May 2020 15:24:36 -0700 Subject: [PATCH 10/10] update this link in aka but not update the link directly here --- sdk/textanalytics/azure-ai-textanalytics/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/textanalytics/azure-ai-textanalytics/README.md b/sdk/textanalytics/azure-ai-textanalytics/README.md index 7cf14acf231f..f820272ef84f 100644 --- a/sdk/textanalytics/azure-ai-textanalytics/README.md +++ b/sdk/textanalytics/azure-ai-textanalytics/README.md @@ -363,7 +363,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m [aad_authorization]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory [aad_credential]: https://docs.microsoft.com/azure/cognitive-services/authentication#authenticate-with-azure-active-directory -[api_reference_doc]: https://docs.microsoft.com/java/api/overview/azure/textanalytics?view=azure-java-preview +[api_reference_doc]: https://aka.ms/azsdk-java-textanalytics-ref-docs [authentication]: https://docs.microsoft.com/azure/cognitive-services/authentication [azure_cli]: https://docs.microsoft.com/azure/cognitive-services/cognitive-services-apis-create-account-cli?tabs=windows [azure_cli_endpoint]: https://docs.microsoft.com/cli/azure/cognitiveservices/account?view=azure-cli-latest#az-cognitiveservices-account-show