Migrate to the latest version of Azure AI Language

  • Article

Tip

Just getting started with Azure AI Language? See the overview article for details on the service, available features, and links to quickstarts for information on the current version of the API.

If your applications are still using the Text Analytics API, or client library (before stable v5.1.0), this article will help you upgrade your applications to use the latest version of the Azure AI language features.

Unified Language endpoint (REST API)

This section applies to applications that use the older /text/analytics/... endpoint format for REST API calls. For example:

https://<your-custom-subdomain>.cognitiveservices.azure.cn/text/analytics/<version>/<feature>

If your application uses the above endpoint format, the REST API endpoint for the following Language service features has changed:

The Language service now provides a unified endpoint for sending REST API requests to these features. If your application uses the REST API, update its request endpoint to use the current endpoint:

https://<your-language-resource-endpoint>/language/:analyze-text?api-version=2022-05-01

Additionally, the format of the JSON request body has changed. You'll need to update the request structure that your application sends to the API, for example the following entity recognition JSON body:

{
    "kind": "EntityRecognition",
    "parameters": {
        "modelVersion": "latest"
    },
    "analysisInput":{
        "documents":[
            {
                "id":"1",
                "language": "en",
                "text": "I had a wonderful trip to Seattle last week."
            }
        ]
    }
}

Use the quickstarts linked above to see current example REST API calls for the feature(s) you're using, and the associated API output.

Client libraries

To use the latest version of the client library, you will need to download the latest software package in the Azure.AI.TextAnalytics namespace. See the quickstart articles linked above for example code and instructions for using the client library in your preferred language.

Version 2.1 functionality changes

If you're migrating an application from v2.1 of the API, there are several changes to feature functionality you should be aware of.

Sentiment analysis v2.1

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.

NER, PII, and entity linking v2.1

In version 2.1, the Text Analytics API used one endpoint for Named Entity Recognition (NER) and entity linking. The current version of this feature provides expanded named entity detection, and has 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.

You will also need to update your application to use the entity categories returned in the API's response.

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 v2.1

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 for each document.

Key phrase extraction v2.1

The key phrase extraction feature functionality currently has not changed outside of the endpoint and request format.

See also