Merge pull request #177453 from aahill/rec-article

updating language service files

Author: v-albemi

.openpublishing.redirection.json

@@ -7245,7 +7245,7 @@
     },
     {
       "source_path_from_root": "/articles/cognitive-services/text-analytics/migration-guide.md",
-      "redirect_url": "/azure/cognitive-services/language-service/concepts/migrate",
+      "redirect_url": "/azure/cognitive-services/language-service/concepts/migrate-from-text-analytics-v2",
       "redirect_document_id": true
     },
     {

articles/cognitive-services/language-service/concepts/migrate-from-text-analytics-v2.md

@@ -0,0 +1,166 @@
+---
+title: Migration guide for v2 of the Text Analytics API
+titleSuffix: Azure Cognitive Services
+description: Learn how to move your applications to use version 3 of the Text Analytics API.
+services: cognitive-services
+author: aahill
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: text-analytics
+ms.topic: article
+ms.date: 07/06/2021
+ms.author: aahi
+---
+
+# Migrate from version 2 of the Text Analytics API
+
+If your applications are using version 2.1 of the Text Analytics API, this article will help you upgrade your applications to use the latest version of the features, which are now a part of [Azure Cognitive Service for language](../overview.md).
+
+## Features
+
+Select one of the features below to see information you can use to update your application.
+
+## [Sentiment analysis](#tab/sentiment-analysis)
+
+> [!TIP]
+> Want to use the latest version of the API in your application? See the [sentiment analysis](../sentiment-opinion-mining/how-to/call-api.md) how-to article  and [quickstart](../sentiment-opinion-mining/quickstart.md) for information on the current version of the API. 
+
+## Feature changes 
+
+Sentiment Analysis in version 2.1 returns sentiment scores between 0 and 1 for each document sent to the API, with scores closer to 1 indicating more positive sentiment. The current version of this feature returns sentiment labels (such as "positive" or "negative")  for both the sentences and the document as a whole, and their associated confidence scores. 
+
+## Steps to migrate
+
+### REST API
+
+If your application uses the REST API, update its request endpoint to use the [current endpoint](../sentiment-opinion-mining/quickstart.md?pivots=rest-api) for sentiment analysis. For example:`https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/sentiment`. You will also need to update the application to use the sentiment labels returned in the [API's response](../sentiment-opinion-mining/how-to/call-api.md). 
+
+See the reference documentation for examples of the JSON response.
+* [Version 2.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v2-1/operations/56f30ceeeda5650db055a3c9)
+* [Version 3.0](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/Sentiment) 
+* [Version 3.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1/operations/Sentiment)
+
+### Client libraries
+
+To use the latest version of the sentiment analysis client library, you will need to download the latest software package in the `Azure.AI.TextAnalytics` namespace. The [quickstart article](../sentiment-opinion-mining/quickstart.md) lists the commands you can use for your preferred language, with example code.
+
+## [NER and entity linking](#tab/named-entity-recognition)
+
+> [!TIP]
+> Want to use the latest version of the API in your application? See the following articles for information on the current version of the APIs:
+> NER:
+> * [Quickstart](../named-entity-recognition/quickstart.md)
+> * [how to call the API](../named-entity-recognition/how-to-call.md) 
+> Entity linking
+> * [Quickstart](../entity-linking/quickstart.md)
+> * [how to call the API](../entity-linking/how-to/call-api.md)
+
+## Feature changes
+
+In version 2.1, the Text Analytics API uses one endpoint for Named Entity Recognition (NER) and entity linking. The current version of this feature provides expanded named entity detection, and uses separate endpoints for NER and entity linking requests. Additionally, you can use another feature offered in the Language service that lets you detect [detect personal (pii) and health (phi) information](../personally-identifiable-information/overview.md). 
+
+## Steps to migrate
+
+### REST API
+
+If your application uses the REST API, update its request endpoint to the [current endpoints](../named-entity-recognition/quickstart.md?pivots=rest-api) for NER and/or entity linking. For example:
+
+Entity Linking
+* `https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/entities/linking`
+
+NER
+* `https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/entities/recognition/general`
+
+You will also need to update your application to use the [entity categories](../named-entity-recognition/concepts/named-entity-categories.md) returned in the [API's response](../named-entity-recognition/how-to-call.md).
+
+See the reference documentation for examples of the JSON response.
+* [Version 2.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v2-1/operations/5ac4251d5b4ccd1554da7634)
+* [Version 3.0](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/EntitiesRecognitionGeneral) 
+* [Version 3.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1/operations/EntitiesRecognitionGeneral)
+
+### Client libraries
+
+To use the latest version of the NER and entity linking client libraries, you will need to download the latest software package in the `Azure.AI.TextAnalytics` namespace. The quickstart article for [Named Entity Recognition](../named-entity-recognition/quickstart.md) and [entity linking](../entity-linking/quickstart.md) lists the commands you can use for your preferred language, with example code.
+
+#### Version 2.1 entity categories
+
+The following table lists the entity categories returned for NER v2.1.
+
+| Category   | Description                          |
+|------------|--------------------------------------|
+| Person   |   Names of people.  |
+|Location    | Natural and human-made landmarks, structures, geographical features, and geopolitical entities |
+|Organization | Companies, political groups, musical bands, sport clubs, government bodies, and public organizations. Nationalities and religions are not included in this entity type. |
+| PhoneNumber | Phone numbers (US and EU phone numbers only). |
+| Email | Email addresses. |
+| URL | URLs to websites. |
+| IP | Network IP addresses. |
+| DateTime | Dates and times of day.| 
+| Date | Calender dates. |
+| Time | Times of day |
+| DateRange | Date ranges. |
+| TimeRange | Time ranges. |
+| Duration | Durations. |
+| Set | Set, repeated times. |
+| Quantity | Numbers and numeric quantities. |
+| Number | Numbers. |
+| Percentage | Percentages.|
+| Ordinal | Ordinal numbers. |
+| Age | Ages. |
+| Currency | Currencies. |
+| Dimension | Dimensions and measurements. |
+| Temperature | Temperatures. |
+
+## [Language detection](#tab/language-detection)
+
+> [!TIP]
+> Want to use the latest version of the API in your application? See the [language detection](../language-detection/how-to/call-api.md) how-to article and [quickstart](../language-detection/quickstart.md) for information on the current version of the API. 
+
+## Feature changes 
+
+The language detection feature output has changed in the current version. The JSON response will contain `ConfidenceScore` instead of `score`. The current version also only returns one language in a  `detectedLanguage` attribute for each document.
+
+## Steps to migrate
+
+### REST API
+
+If your application uses the REST API, update its request endpoint to the [current endpoint](../language-detection/quickstart.md?pivots=rest-api) for language detection. For example:`https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v3.1/languages`. You will also need to update the application to use `ConfidenceScore` instead of `score` in the [API's response](../language-detection/how-to/call-api.md). 
+
+See the reference documentation for examples of the JSON response.
+* [Version 2.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v2-1/operations/56f30ceeeda5650db055a3c7)
+* [Version 3.0](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/Languages) 
+* [Version 3.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1/operations/Languages)
+
+#### Client libraries
+
+To use the latest version of the sentiment analysis client library, you will need to download the latest software package in the `Azure.AI.TextAnalytics` namespace. The [quickstart article](../language-detection/quickstart.md) lists the commands you can use for your preferred language, with example code.
+
+## [Key phrase extraction](#tab/key-phrase-extraction)
+
+> [!TIP]
+> Want to use the latest version of the API in your application? See the [key phrase extraction](../key-phrase-extraction/how-to/call-api.md) how-to article and [quickstart](../key-phrase-extraction/quickstart.md) for information on the current version of the API. 
+
+## Feature changes 
+
+The key phrase extraction feature currently has not changed outside of the endpoint version.
+
+## Steps to migrate
+
+### REST API
+
+If your application uses the REST API, update its request endpoint to the [current endpoint](../key-phrase-extraction/quickstart.md?pivots=rest-api) for key phrase extraction. For example: `https://<your-custom-subdomain>.api.cognitiveservices.azure.com/text/analytics/v3.1/keyPhrases`
+
+See the reference documentation for examples of the JSON response.
+* [Version 2.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v2-1/operations/56f30ceeeda5650db055a3c6)
+* [Version 3.0](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/KeyPhrases) 
+* [Version 3.1](https://westcentralus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1/operations/KeyPhrases)
+
+### Client libraries
+
+To use the latest version of the sentiment analysis client library, you will need to download the latest software package in the `Azure.AI.TextAnalytics` namespace. The [quickstart article](../key-phrase-extraction/quickstart.md) lists the commands you can use for your preferred language, with example code.
+
+---
+
+## See also
+
+* [What is Azure Cognitive Service for language?](../overview.md)

articles/cognitive-services/language-service/concepts/migrate.md

@@ -17,7 +17,7 @@ On November 2nd 2021, Azure Cognitive Service for Language was released into pub
 
 ## Do I need to migrate to the language service if I am using Text Analytics?
 
-Text Analytics has been incorporated into the language service, and its features are still available. If you were using Text Analytics, your applications should continue to work without breaking changes.
+Text Analytics has been incorporated into the language service, and its features are still available. If you were using Text Analytics, your applications should continue to work without breaking changes. You can also see the [Text Analytics v2 migration guide](migrate-from-text-analytics-v2.md), if you need to update an older application. 
 
 Consider using one of the available quickstart articles to see the latest information on service endpoints, and API calls. 
 

articles/cognitive-services/language-service/custom-classification/definitions.md

@@ -20,7 +20,7 @@ Learn about definitions used in custom text classification.
 ## Project
 
 A project is a work area for building your custom AI models based on your data. Your project can only be accessed by you and others who have contributor access to the Azure resource being used.
-As a prerequisite to creating a Custom text classification project, you have to [connect your resource to a storage account](how-to/project-requirements.md).
+As a prerequisite to creating a Custom text classification project, you have to [connect your resource to a storage account](how-to/create-project.md).
 As part of the project creation flow, you need connect it to a blob container where you have uploaded your dataset. Your project automatically includes all the `.txt` files available in your container. You can have multiple models within your project all built on the same dataset. See the [service limits](concepts/data-limits.md) article for more information.
 
 Within your project you can do the following operations:

articles/cognitive-services/language-service/custom-classification/faq.md

@@ -18,10 +18,6 @@ ms.custom: language-service-custom-classification
 
 Find answers to commonly asked questions about concepts, and scenarios related to custom text classification in Azure Cognitive Service for Language.
 
-## What are the best practices when building a custom classification model?
-
-Get started with this [quickstart](quickstart.md) and follow the [recommended practices](concepts/recommended-practices.md).
-
 ## How many tagged files are needed?
 
 Generally, diverse and representative [tagged data](how-to/tag-data.md) leads to better results, given that the tagging is done precisely, consistently and completely. There is no set number of tagged classes that will make every model perform well. Performance highly dependent on your schema, and the ambiguity of your schema. Ambiguous classes need more tags. Performance also depends on the quality of your tagging. The recommended number of tagged instances per entity is 50. 
@@ -56,4 +52,5 @@ To clone your project you need to [export]() project assests and then [import]()
 
 ## Next steps
 
-[Recommended practices](concepts/recommended-practices.md)
+* [Custom text classification overview](overview.md)
+* [quickstart](quickstart.md)

articles/cognitive-services/language-service/custom-classification/how-to/call-api.md

@@ -19,8 +19,8 @@ After you're satisfied with your model, and made any necessary improvements, you
 
 ## Prerequisites
 
-* [A custom classification project](project-requirements.md) with a configured Azure blob storage account, 
-* Text data that has [been uploaded](project-requirements.md#prepare-training-data) to your storage account.
+* [A custom classification project](create-project.md) with a configured Azure blob storage account, 
+* Text data that has [been uploaded](create-project.md#prepare-training-data) to your storage account.
 * [Tagged data](tag-data.md) and successfully [trained model](train-model.md)
 * Reviewed the [model evaluation details](view-model-evaluation.md) to determine how your model is performing.
 * (optional) [Made improvements](improve-model.md) to your model if its performance isn't satisfactory. 
@@ -63,7 +63,7 @@ See the [application development lifecycle](../overview.md#application-developme
 
 5. In the response header you receive extract `jobId` from `operation-location`, which has the format: `{YOUR-ENDPOINT}/text/analytics/v3.2-preview.2/analyze/jobs/<jobId}>`
 
-6. Copy the retrieve request and replace `<OPERATION-ID>` with `jobId` recieved form last step and submit the request.
+6. Copy the retrieve request and replace `<OPERATION-ID>` with `jobId` received form last step and submit the request.
 
     :::image type="content" source="../media/get-prediction-url-3.png" alt-text="run-inference-3" lightbox="../media/get-prediction-url-3.png":::
 

articles/cognitive-services/language-service/custom-classification/how-to/project-requirements.md renamed to articles/cognitive-services/language-service/custom-classification/how-to/create-project.md

@@ -24,7 +24,7 @@ Before you start using custom text classification, you will need several things:
 * An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services).
 * An Azure Language resource 
 * An Azure storage account to store data for your project
-* You should have an idea of the [project schema](../concepts/recommended-practices.md) you will use for your data.
+* You should have an idea of the [project schema](design-schema.md) you will use for your data.
 
 ## Azure resources
 
@@ -138,7 +138,7 @@ To set proper roles on your storage account:
 * You can either upload tagged data, or you can tag your data in Language Studio. Tagged data must follow the [tags file format](../concepts/data-formats.md). 
 
 >[!TIP]
-> Review the [recommended practices](..//concepts/recommended-practices.md) for data selection and preparation.
+> See [How to design a schema](design-schema.md) for information on data selection and preparation.
 
 ## Create a project
 
@@ -150,5 +150,3 @@ Once your Azure resource and storage account are configured, you can create a pr
 ## Next steps
 
 After your project is created, you can start [tagging your data](tag-data.md), which will inform your text classification model how to interpret text, and is used for training and evaluation.
-
-As you work with your text classification project, review the [recommended practices](../concepts/recommended-practices.md).

articles/cognitive-services/language-service/custom-classification/concepts/recommended-practices.md renamed to articles/cognitive-services/language-service/custom-classification/how-to/design-schema.md

@@ -1,7 +1,7 @@
 ---
-title: Recommended custom classification practices 
+title: How to prepare data and define a schema
 titleSuffix: Azure Cognitive Services
-description: Learn about recommended practices when using custom classification.
+description: Learn about data selection, preparation, and creating a schema for custom classification projects.
 services: cognitive-services
 author: aahill
 manager: nitinme
@@ -62,5 +62,5 @@ The schema defines the classes that you need your model to classify your text in
 
 ## Next steps
 
-If you haven't already, create a custom classification project. If it's your first time using custom classification, consider following the [quickstart](../quickstart.md) to create an example project. You can also see the [project requirements](../how-to/project-requirements.md) for more details on what you need to create a project. 
+If you haven't already, create a custom classification project. If it's your first time using custom classification, consider following the [quickstart](../quickstart.md) to create an example project. You can also see the [project requirements](../how-to/create-project.md) for more details on what you need to create a project. 
 

articles/cognitive-services/language-service/custom-classification/how-to/improve-model.md

@@ -21,8 +21,8 @@ After you've trained your model you reviewed its evaluation details, you can dec
 
 To optionally improve a model, you will need to have:
 
-* [A custom classification project](project-requirements.md) with a configured Azure blob storage account, 
-* Text data that has [been uploaded](project-requirements.md#prepare-training-data) to your storage account.
+* [A custom classification project](create-project.md) with a configured Azure blob storage account, 
+* Text data that has [been uploaded](create-project.md#prepare-training-data) to your storage account.
 * [Tagged data](tag-data.md) to successfully [train a model](train-model.md)
 * Reviewed the [model evaluation details](view-model-evaluation.md) to determine how your model is performing.
 * Familiarized yourself with the [evaluation metrics](../concepts/evaluation.md) used for evaluation

articles/cognitive-services/language-service/custom-classification/how-to/tag-data.md

@@ -20,8 +20,8 @@ Before creating a custom text classification model, you need to have tagged data
 ## Prerequisites
 
 Before you can tag data, you need:
-* [A successfully created project](project-requirements.md) with a configured Azure blob storage account, 
-* Text data that has [been uploaded](project-requirements.md#prepare-training-data) to your storage account.
+* [A successfully created project](create-project.md) with a configured Azure blob storage account, 
+* Text data that has [been uploaded](create-project.md#prepare-training-data) to your storage account.
 
 See the [application development lifecycle](../overview.md#application-development-lifecycle) for more information.
 
@@ -35,7 +35,7 @@ As you tag your data, keep in mind:
 
 * In general, more tagged data leads to better results, provided the data is tagged accurately.
 
-* Although we recommended having around 50 tagged files per class, there is no fixed number that can guarantee your model will perform the best, because model performance also depends on possible ambiguity in your [schema](../concepts/recommended-practices.md), and the quality of your tagged data.
+* Although we recommended having around 50 tagged files per class, there is no fixed number that can guarantee your model will perform the best, because model performance also depends on possible ambiguity in your [schema](design-schema.md), and the quality of your tagged data.
 
 Use the following steps to tag your data