24 KiB
Migrating to @azure/ai-text-analytics
Version 6
Note ⚠️: @azure/ai-text-analytics
version 6 is currently a beta package. Certain aspects of the package's API surface and implementation may change during the course of its development, and this document is a work-in-progress and may change to reflect updates to the package. We value your feedback, and it is especially useful during the beta development cycle. Please create an issue to suggest any improvements or report any problems with this guide or with the package itself.
Major version 6 introduces a full redesign of the Azure Text Analytics client library. To leverage features of the Azure Cognitive Language Service API (version "2022-04-01-preview" and newer), the new client library is required, and application code must be updated accordingly as will be detailed below. To summarize:
- Version 5 of the
@azure/ai-text-analytics
package only supports Text Analytics service API version 3.0 and 3.1, and will not support the new Azure Cognitive Language Service. - Version 6 (beta) of the package supports Azure Cognitive Language Service API version "2022-04-01-preview", and future releases of this major version will support newer service API versions as well. It also drops support for the old Text Analytics API.
This document provides instructions for updating your application code to the new major version 6 of the client library. In this document, the examples provided use TypeScript to provide type information, but all runtime behavior changes naturally apply to plain JavaScript as well.
Partial Migration (Side-by-Side)
To avoid migrating an application all at once, major version 6 may be installed alongside major version 5 using a dependency alias. Either version may be aliased. For example, to install the new client library under an alias, add the following to the dependencies
field of package.json
:
{
...,
"dependencies": {
...,
"@azure/ai-text-analytics": "^5.1.0",
"@azure/ai-text-analytics-new": "npm:@azure/ai-text-analytics@6.0.0-beta.1"
}
}
With this configuration, imports from "@azure/ai-text-analytics"
will import from major version 5, and imports from "@azure/ai-text-analytics-new"
will import from major version 6. Of course, major version 5 could be aliased instead:
{
...,
"dependencies": {
...,
"@azure/ai-text-analytics": "6.0.0-beta.1",
"@azure/ai-text-analytics-old": "npm:@azure/ai-text-analytics@^5.1.0"
}
}
Then, the two packages may be used side-by-side, and an application may be migrated partially or over time:
import { TextAnalyticsClient } from "@azure/ai-text-analytics-old";
import { TextAnalysisClient } from "@azure/ai-text-analytics";
Understanding the New Types
In the new major version 6, several types have been introduced, renamed, restructured, and removed. This section describes the differences between the two versions.
Terminology
Some terminology has changed to reflect the enhanced capabilities of the newest Azure Cognitive Language Service APIs. For starters, the service changed its name from Azure Text Analytics to Azure Cognitive Language Service and added advanced capabilities for answering questions and analyzing conversations. However, major version 6 will only support the text analysis capabilities that are provided by the Azure Cognitive Language Service. As a result, we've made the following broad changes to the terminology used throughout the client:
- Operations are now referred to as actions in all contexts and not only when batching them.
- The actions are renamed from verb phrases to nouns, and rather than calling the corresponding individual method, a single action can be performed by passing its name as a string literal to the one method that is capable of performing single actions. For example, in major version 5, an entity recognition action is performed when calling the
recognizeEntities
method. In major version 6, this call is done by passing the"EntityRecognition"
literal to the method that performs single actions. - The plural word "Actions" has been replaced with the word "Batch" to indicate a batch of actions.
Changes to Types
The following table explores several type names from the previous (v5.x) client and shows their nearest new (v6.x) equivalent. The name changes illustrate several of the above-mentioned changes in terminology. The breaking changes between each of the pairs of types are also listed. This table provides an overview, and more detail and code samples are provided in the following sections.
Previous (v5.x) Type Name | Current (v6.x) Equivalent | Symbol Type | Change description |
---|---|---|---|
TextAnalyticsClient |
TextAnalysisClient |
Class | This class replaces the former and has no methods in common with it. See the section on TextAnalysisClient below. |
AnalysisPollOperationState , AnalyzeActionsOperationState |
AnalyzeBatchOperationState |
Interface | This interface replaces both of the former ones |
OperationMetadata and AnalyzeActionsOperationMetadata |
AnalyzeBatchOperationMetadata |
Interface | This interface replaces both of the former ones but still uses the same field names. However, all fields specific to the analyze batch operation are now read-only |
AnalyzeActionsPollerLike |
AnalyzeBatchPoller |
Interface | This interface replaces the former one. See the entries for AnalyzeBatchOperationState and PagedAnalyzeBatchResult for more details |
AnalyzeActionsResult |
AnalyzeBatchResult |
Interface | The old one contained a field for each kind of action and those fields contained arrays of results. On the other hand, the new interface is a union of a set of interfaces where each one represents the result of a particular action with kind as a common field to act as a discriminator between different results |
AnalyzeHealthcareEntitiesErrorResult |
HealthcareErrorResult |
Interface | |
AnalyzeHealthcareEntitiesResult |
HealthcareResult |
Interface | |
AnalyzeHealthcareEntitiesSuccessResult |
HealthcareSuccessResult |
Interface | |
AnalyzeSentimentAction and AnalyzeSentimentOptions |
SentimentAnalysisAction |
Interface | |
AnalyzeSentimentErrorResult |
SentimentAnalysisErrorResult |
Interface | |
AnalyzeSentimentActionErrorResult , ExtractKeyPhrasesActionErrorResult , ExtractSummaryActionErrorResult , MultiCategoryClassifyActionErrorResult , RecognizeCategorizedEntitiesActionErrorResult , RecognizeLinkedEntitiesActionErrorResult , RecognizePiiEntitiesActionErrorResult , RecongizeCustomEntitiesActionErrorResult , and SingleCategoryClassifyActionErrorResult |
BatchActionErrorResult |
Interface | The old types were strucurally similar and the new type replaces them all |
AnalyzeSentimentActionResult |
SentimentAnalysisBatchResult |
Interface | The new interface is part of the union of AnalyzeBatchResult |
AnalyzeSentimentActionSuccessResult , ExtractKeyPhrasesActionSuccessResult , ExtractSummaryActionSuccessResult , MultiCategoryClassifyActionSuccessResult , RecognizeCategorizedEntitiesActionSuccessResult , RecognizeLinkedEntitiesActionSuccessResult , RecognizePiiEntitiesActionSuccessResult , RecongizeCustomEntitiesActionSuccessResult , and SingleCategoryClassifyActionSuccessResult |
BatchActionSuccessResult |
Interface | The old types were strucurally similar and the new type replaces them all. Furthermore, the results field is now read-only |
AnalyzeSentimentResult |
SentimentAnalysisResult |
Interface | |
AnalyzeSentimentResultArray , DetectLanguageResultArray , ExtractKeyPhrasesResultArray , ExtractSummaryResultArray , RecognizeCategorizedEntitiesResultArray , RecognizeLinkedEntitiesResultArray , and RecognizePiiEntitiesResultArray |
SentimentAnalysisResult[] , LanguageDetectionResult[] , KeyPhraseExtractionResult[] , ExtractiveSummarizationResult[] , EntityRecognitionResult[] , EntityLinkingResult[] , and PiiEntityRecognitionResult[] |
Interface | The old types used to have statistics and modelVersion fields attached but the type has been deleted in the new client |
SingleCategoryClassifyResultArray , MultiCategoryClassifyResultArray , and RecognizeCustomEntitiesResultArray |
CustomSingleLabelClassificationResult , CustomMultiLabelClassificationResult[] , and CustomEntityRecognitionResult[] |
The old types used to have statistics , projectName , and deploymentName fields attached but the type has been deleted in the new client |
|
AnalyzeSentimentSuccessResult |
SentimentAnalysisSuccessResult |
Interface | All fields are now marked as read-only |
BeginAnalyzeActionsOptions |
BeginAnalyzeBatchOptions |
Interface | resumeFrom has been deleted in the new interface |
CustomTextAnalyticsAction |
ActionCustom |
Interface | disableServiceLogs has been added in the new interface and actionName has been moved to AnalyzeBatchActionCommon |
DetectLanguageErrorResult |
LanguageDetectionErrorResult |
Interface | |
DetectLanguageInput |
LanguageDetectionInput |
Interface | |
DetectLanguageOptions |
LanguageDetectionAction |
Interface | |
DetectLanguageResult |
LanguageDetectionResult |
Interface | |
DetectLanguageSuccessResult |
LanguageDetectionSuccessResult |
Interface | |
EntityAssertion |
LanguageDetectionSuccessResult |
Interface | |
ExtractKeyPhrasesAction and ExtractKeyPhrasesOptions |
KeyPhraseExtractionAction |
Interface | |
ExtractKeyPhrasesActionResult |
KeyPhraseExtractionBatchResult |
Interface | |
ExtractKeyPhrasesErrorResult |
KeyPhraseExtractionErrorResult |
Interface | |
ExtractKeyPhrasesResult |
KeyPhraseExtractionResult |
Interface | |
ExtractKeyPhrasesSuccessResult |
KeyPhraseExtractionSuccessResult |
Interface | keyPhrases is now read-only |
ExtractSummaryAction |
ExtractiveSummarizationAction |
Interface | |
ExtractSummaryActionResult |
ExtractiveSummarizationBatchResult |
Interface | |
ExtractSummaryResult |
SummarizationExtractionResult |
Interface | |
ExtractSummarySuccessResult |
SummarizationExtractionSuccessResult |
Interface | sentences is now read-only |
HealthcareEntityRelation |
HealthcareEntityRelation |
Interface | all fields are now read-only |
HealthcareEntityRelationRole |
HealthcareEntityRelationRole |
Interface | all fields are now read-only |
KnownSummarySentencesOrderBy |
ExtractiveSummarizationOrderingCriteria |
Interface | |
MultiCategoryClassifyAction |
CustomMultiLabelClassificationAction |
Interface | |
MultiCategoryClassifyActionResult |
CustomMultiLabelClassificationBatchResult |
Interface | |
MultiCategoryClassifyErrorResult |
CustomMultiLabelClassificationErrorResult |
Interface | |
MultiCategoryClassifyResult |
CustomMultiLabelClassificationResult |
Interface | |
MultiCategoryClassifySuccessResult |
CustomMultiLabelClassificationSuccessResult |
Interface | classifications is now read-only |
Opinion |
Opinion |
Interface | all fields are now read-only |
PagedAnalyzeActionsResult |
PagedAnalyzeBatchResult |
Interface | all fields are now read-only |
PagedAsyncIterableAnalyzeActionsResult |
PagedAsyncIterableIterator<AnalyzeBatchResult> |
Interface | The type of a page of results is now an array of AnalyzeBatchResult |
PiiEntity |
Entity |
Interface | |
RecognizeCategorizedEntitiesAction and RecognizeCategorizedEntitiesOptions |
EntityRecognitionAction |
Interface | |
RecognizeCategorizedEntitiesActionResult |
EntityRecognitionBatchResult |
Interface | |
RecognizeCategorizedEntitiesErrorResult |
EntityRecognitionErrorResult |
Interface | |
RecognizeCategorizedEntitiesResult |
EntityRecognitionResult |
Interface | |
RecognizeCategorizedEntitiesSuccessResult |
EntityRecognitionSuccessResult |
Interface | entities is now read-only |
RecognizeCustomEntitiesAction |
CustomEntityRecognitionAction |
Interface | |
RecognizeCustomEntitiesActionResult |
CustomEntityRecognitionBatchResult |
Interface | |
RecognizeCustomEntitiesErrorResult |
CustomEntityRecognitionErrorResult |
Interface | |
RecognizeCustomEntitiesResult |
CustomEntityRecognitionResult |
Interface | |
RecognizeCustomEntitiesSuccessResult |
CustomEntityRecognitionSuccessResult |
Interface | entities is now read-only |
RecognizeLinkedEntitiesAction and RecognizeLinkedEntitiesOptions |
EntityLinkingAction |
Interface | |
RecognizeLinkedEntitiesActionResult |
EntityLinkingBatchResult |
Interface | |
RecognizeLinkedEntitiesErrorResult |
EntityLinkingErrorResult |
Interface | |
RecognizeLinkedEntitiesResult |
EntityLinkingResult |
Interface | |
RecognizeLinkedEntitiesSuccessResult |
EntityLinkingSuccessResult |
Interface | |
RecognizePiiEntitiesAction and RecognizePiiEntitiesOptions |
PiiEntityRecognitionAction |
Interface | |
RecognizePiiEntitiesActionResult |
PiiEntityRecognitionBatchResult |
Interface | |
RecognizePiiEntitiesErrorResult |
PiiEntityRecognitionErrorResult |
Interface | |
RecognizePiiEntitiesResult |
PiiEntityRecognitionResult |
Interface | |
RecognizePiiEntitiesSuccessResult |
PiiEntityRecognitionSuccessResult |
Interface | redactedText is now read-only |
SentenceSentiment |
SentenceSentiment |
Interface | all fields are now read-only |
SingleCategoryClassifyAction |
CustomSingleLabelClassificationAction |
Interface | |
SingleCategoryClassifyActionResult |
CustomSingleLabelClassificationBatchResult |
Interface | |
SingleCategoryClassifyActionSuccessResult |
CustomSingleLabelClassificationSuccessResult |
Interface | classification has been renamed to classifications and is now an array |
StringIndexType |
StringIndexType |
Type Alias | It was a union and has been updated to be a string |
TargetConfidenceScoreLabel |
TargetConfidenceScores |
Type Alias | |
TargetSentiment |
TargetSentiment |
Interface | All fields are now read-only |
TextAnalyticsAction |
ActionPrebuilt & AnalyzeBatchActionCommon |
Interface | |
TextAnalyticsActionErrorResult |
BatchActionErrorResult |
Interface | |
TextAnalyticsActions |
AnalyzeBatchAction[] |
Interface | The old one contained a field for each kind of action and those fields contained arrays of actions. On the other hand, the new interface is a union of a set of interfaces where each one represents a particular action with kind as a common field to act as a discriminator between different ones |
TextAnalyticsActionState |
BatchActionState |
Interface | The new interface adds kind and statistics and all fields are marked as read-only |
TextAnalyticsActionSuccessState |
BatchActionSuccessResult |
Interface | The new interface adds a read-only results field |
TextAnalyticsClientOptions |
TextAnalysisClientOptions |
Interface | The new interface adds a new apiVersion field |
TextAnalyticsError |
TextAnalysisError |
Interface | |
TextAnalyticsErrorResult |
TextAnalysisErrorResult |
Interface | |
TextAnalyticsOperationOptions |
ActionPrebuilt & TextAnalysisOperationOptions |
Interface | |
TextAnalyticsOperationStatus |
OperationStatus |
Type Alias | |
TextAnalyticsSuccessResult |
TextAnalysisSuccessResult |
Interface | |
TokenSentimentValue |
TokenSentimentLabel |
Type Alias |
Migrating from TextAnalyticsClient
to TextAnalysisClient
The TextAnalysisClient
class, used for all text analysis actions, has replaced TextAnalyticsClient
(which has been removed). The constructor signature is the same, but one new option has been introduced to the client constructor, apiVersion
, which allows the application to specify the version of the Azure Cognitive Language Service API to use (the default is the most recent version at the time of the library release, e.g. 2022-04-01-preview
for @azure/ai-text-analytics@6.0.0-beta.1
).
The previous TextAnalyticsClient
class and new TextAnalysisClient
class have no methods in common. The new class only has three methods in total. They are:
analyze
, which replaces all of the following:recognizeEntities
recognizePiiEntities
extractKeyPhrases
detectLanguage
analyzeSentiment
recognizeLinkedEntities
beginAnalyzeBatch
, which replacesbeginAnalyzeActions
andbeginAnalyzeHealthcareEntities
.restoreAnalyzeBatchPoller
, which is new, and provides customers with the ability to restore a poller for a batch analysis operation from a serialized poller state.
All of these methods can produce AnalyzeResult
, AnalyzeBatchResult[]
, and AnalyzeBatchPoller
types respectively. Please see the section above about these types for more information.
Action specification
In major version 5, there is one method per action for actions that are not long-running operations. For example, the recognizeEntities
method perfoms entity recognition. In major version 6, there is only one method, analyze
, that can perform one such action at a time. Compare the following samples using recognizeEntities
and analyze
:
Previous (5.1.0):
const client = new TextAnalyticsClient(...);
const documents = [...];
// Previously, there was one method per action for most actions
const result = await client.recognizeEntities(documents);
Current (6.0.0-beta.1):
const client = new TextAnalysisClient(...);
const documents = [...];
// Now, an action can be performed by passing its name
const result = await client.analyze("EntityRecognition", documents);
On the other hand, the way to consume the results of such actions didn't change. Furthermore, in major version 5, long-running operations actions can be batched and performed using the beginAnalyzeActions
method. In major version 6, the same can be done using the beginAnalyzeBatch
method but with the following two major differences:
- Healthcare analysis is now supported. In major version 5, healthcare analysis is performed exclusively using the
beginAnalyzeHealthcareEntities
method. In major version 6, it is supported exclusively as an action inbeginAnalyzeBatch
. - Each action and their result is identified by a
kind
field in a list. In major version 5, specifying an action list of entity recognition and entity linking is done as{ recognizeEntities: [ { ... } ], recognizeLinkedEntities: [ { ... } ] }
. In major version 6, the same is done as[ { kind: "EntityRecognition", ... }, { kind: "EntityLinking", ... } ]
.
To look at those changes more closely, compare the following samples:
Healthcare analysis:
Previous (5.1.0):
const client = new TextAnalyticsClient(...);
const documents = [...];
// Previously, healthcare analysis is done by calling the following method
const poller = await client.beginAnalyzeHealthcareEntities(documents);
Current (6.0.0-beta.1):
const client = new TextAnalysisClient(...);
const documents = [...];
// Now, it can be performed by passing it as a batch action
const poller = await client.beginAnalyzeBatch([{ kind: "Healthcare" }], documents);
Specifying input actions:
Previous (5.1.0):
const client = new TextAnalyticsClient(...);
const documents = [...];
// Previously, batching actions we done in a deep object
const poller = await client.beginAnalyzeActions(documents, { recognizeEntities: [ {} ], recognizeLinkedEntities: [ {} ] });
Current (6.0.0-beta.1):
const client = new TextAnalysisClient(...);
const documents = [...];
// Now, it can be done in a flat list
const poller = await client.beginAnalyzeBatch([{ kind: "EntityRecognition" }, { kind: "EntityLinking" }], documents);
Consuming action results:
Previous (5.1.0):
const actionResults = await poller.pollUntilDone();
for await (const actionResultsPage of actionResults) {
for (const entityRecognitionActionResult of actionResultsPage.recognizeEntitiesResults) {
if (entityRecognitionActionResult.error) {
// handle errors
}
for (const doc of entityRecognitionActionResult.results) {
// do something
}
}
for (const entityLinkingActionResult of actionResultsPage.recognizeLinkedEntitiesResults) {
if (entityLinkingActionResult.error) {
// handle errors
}
for (const doc of entityLinkingActionResult.results) {
// do something
}
}
}
Current (6.0.0-beta.1):
const actionResults = await poller.pollUntilDone();
for await (const actionResult of actionResults) {
if (actionResult.error) {
throw new Error(`Unexpected error`);
}
switch (actionResult.kind) {
case "EntityLinking": {
for (const doc of actionResult.results) {
// do something
}
break;
}
case "PiiEntityRecognition": {
for (const doc of actionResult.results) {
// do something
}
break;
}
}
}
Accessing statistics and model information for analyze
results
In major version 5, statistics about an action were returned as part of the results in a statistics
property attached to the array of results. In major version 6, statistics
is no longer attached and can be accessed instead in the http response:
Previous (5.1.0):
const client = new TextAnalyticsClient(...);
const documents = [...];
// Previously, `statistics` is part of the results array
const results = await client.analyze("EntityLinking", documents, "en", { includeStatistics: true });
const stats = results.statistics;
console.log(`- Documents count: ${stats.documentCount}`);
console.log(`- Valid documents count: ${stats.validDocumentCount}`);
console.log(`- Erroneous documents count: ${stats.erroneousDocumentCount}`);
console.log(`- Transactions count: ${stats.transactionCount}`);
Current (6.0.0-beta.1):
const client = new TextAnalysisClient(...);
const documents = [...];
// Now, it can be accessed from the http response
const results = await client.analyze("EntityLinking", documents, "en", {
includeStatistics: true,
/**
* Access general statistics information about the action from the HTTP
* response.
*/
onResponse: (_rawResponse, flatResponse) => {
const stats = (flatResponse as any).results.statistics as TextDocumentBatchStatistics;
console.log(`- Documents count: ${stats.documentCount}`);
console.log(`- Valid documents count: ${stats.validDocumentCount}`);
console.log(`- Erroneous documents count: ${stats.erroneousDocumentCount}`);
console.log(`- Transactions count: ${stats.transactionCount}`);
},
});
Furthermore, in major version 5, model information about an action were returned as part of the results in a modelVersion
property attached to the array of results. In major version 6, the same information can be accessed instead from the http response:
Previous (5.1.0):
const client = new TextAnalyticsClient(...);
const documents = [...];
// Previously, `statistics` is part of the results array
const results = await client.analyze("EntityLinking", documents, "en", { includeStatistics: true });
console.log(`The result of the sentiment analysis was computed using model version: ${results.modelVersion}`);
Current (6.0.0-beta.1):
const client = new TextAnalysisClient(...);
const documents = [...];
// Now, it can be accessed from the http response
const results = await client.analyze("EntityLinking", documents, "en", {
modelVersion: "latest",
/**
* Access general model information about the action from the HTTP
* response.
*/
onResponse: (_rawResponse, flatResponse) => {
const modelVersion = (flatResponse as any).results.modelVersion;
console.log(
`The result of the entity linking was computed using model version: ${modelVersion}`
);
},
});