Azure Text Analysis client library for JavaScript
Azure Cognitive Service for Language is a cloud-based service that provides advanced natural language processing over raw text, and includes the following main features:
Note: This SDK targets Azure Cognitive Service for Language API version 2023-04-01.
- Language Detection
- Sentiment Analysis
- Key Phrase Extraction
- Named Entity Recognition
- Recognition of Personally Identifiable Information
- Entity Linking
- Healthcare Analysis
- Extractive Summarization
- Abstractive Summarization
- Custom Entity Recognition
- Custom Document Classification
- Support Multiple Actions Per Document
Use the client library to:
- Detect what language input text is written in.
- Determine what customers think of your brand or topic by analyzing raw text for clues about positive or negative sentiment.
- Automatically extract key phrases to quickly identify the main points.
- Identify and categorize entities in your text as people, places, organizations, date/time, quantities, percentages, currencies, healthcare specific, and more.
- Perform multiple of the above tasks at once.
Key links:
Migrating from @azure/ai-text-analytics advisory ⚠️
Please see the Migration Guide for detailed instructions on how to update application code from version 5.x of the AI Text Analytics client library to the new AI Language Text client library.
What's New
Getting started
Currently supported environments
- LTS versions of Node.js
- Latest versions of Safari, Chrome, Edge, and Firefox.
See our support policy for more details.
Prerequisites
- An Azure subscription.
- An existing Cognitive Services or Language resource. If you need to create the resource, you can use the Azure Portal or Azure CLI following the steps in this document.
If you use the Azure CLI, replace <your-resource-group-name> and <your-resource-name> with your own unique names:
az cognitiveservices account create --kind TextAnalytics --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>Install the @azure/ai-language-text package
Install the Azure Text Analysis client library for JavaScript with npm:
npm install @azure/ai-language-textCreate and authenticate a TextAnalysisClient
To create a client object to access the Language API, you will need the endpoint of your Language resource and a credential. The Text Analysis client can use either Azure Active Directory credentials or an API key credential to authenticate.
You can find the endpoint for your Language resource either in the Azure Portal or by using the Azure CLI snippet below:
az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "properties.endpoint"Using an API Key
Use the Azure Portal to browse to your Language resource and retrieve an API key, or use the Azure CLI snippet below:
Note: Sometimes the API key is referred to as a "subscription key" or "subscription API key."
az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>Once you have an API key and endpoint, you can use the AzureKeyCredential class to authenticate the client as follows:
const { TextAnalysisClient, AzureKeyCredential } = require("@azure/ai-language-text");
const client = new TextAnalysisClient("<endpoint>", new AzureKeyCredential("<API key>"));Using an Azure Active Directory Credential
Client API key authentication is used in most of the examples, but you can also authenticate with Azure Active Directory using the Azure Identity library. To use the DefaultAzureCredential provider shown below,
or other credential providers provided with the Azure SDK, please install the @azure/identity package:
npm install @azure/identityYou will also need to register a new AAD application and grant access to Language by assigning the "Cognitive Services User" role to your service principal (note: other roles such as "Owner" will not grant the necessary permissions, only "Cognitive Services User" will suffice to run the examples and the sample code).
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.
const { TextAnalysisClient } = require("@azure/ai-language-text");
const { DefaultAzureCredential } = require("@azure/identity");
const client = new TextAnalysisClient("<endpoint>", new DefaultAzureCredential());Key concepts
TextAnalysisClient
TextAnalysisClient is the primary interface for developers using the Text Analysis client library. Explore the methods on this client object to understand the different features of the Language service that you can access.
Input
A document represents a single unit of input to be analyzed by the predictive models in the Language service. Operations on TextAnalysisClient take a collection of inputs to be analyzed as a batch. The operation methods have overloads that allow the inputs to be represented as strings, or as objects with attached metadata.
For example, each document can be passed as a string in an array, e.g.
const documents = [
"I hated the movie. It was so slow!",
"The movie made it into my top ten favorites.",
"What a great movie!",
];or, if you wish to pass in a per-item document id or language/countryHint, they can be given as a list of TextDocumentInput or DetectLanguageInput depending on the operation;
const textDocumentInputs = [
{ id: "1", language: "en", text: "I hated the movie. It was so slow!" },
{ id: "2", language: "en", text: "The movie made it into my top ten favorites." },
{ id: "3", language: "en", text: "What a great movie!" },
];See service limitations for the input, including document length limits, maximum batch size, and supported text encodings.
Return Value
The return value corresponding to a single document is either a successful result or an error object. Each TextAnalysisClient method returns a heterogeneous array of results and errors that correspond to the inputs by index. A text input and its result will have the same index in the input and result collections.
An result, such as SentimentAnalysisResult, is the result of a Language operation, containing a prediction or predictions about a single text input. An operation's result type also may optionally include information about the input document and how it was processed.
The error object, TextAnalysisErrorResult, indicates that the service encountered an error while processing the document and contains information about the error.
Document Error Handling
In the collection returned by an operation, errors are distinguished from successful responses by the presence of the error property, which contains the inner TextAnalysisError object if an error was encountered. For successful result objects, this property is always undefined.
For example, to filter out all errors, you could use the following filter:
const results = await client.analyze("SentimentAnalysis", documents);
const onlySuccessful = results.filter((result) => result.error === undefined);Note: TypeScript users can benefit from better type-checking of result and error objects if compilerOptions.strictNullChecks is set to true in the tsconfig.json configuration. For example:
const [result] = await client.analyze("SentimentAnalysis", ["Hello world!"]);
if (result.error !== undefined) {
// In this if block, TypeScript will be sure that the type of `result` is
// `TextAnalysisError` if compilerOptions.strictNullChecks is enabled in
// the tsconfig.json
console.log(result.error);
}Samples
Client Usage
Prebuilt Tasks
- Abstractive Summarization
- Language Detection
- Entity Linking
- Entity Regconition
- Extractive Summarization
- Healthcare Analysis
- Key Phrase Extraction
- Language Detection
- Opinion Mining
- PII Entity Recognition
- Sentiment Analysis
Custom Tasks
Troubleshooting
Logging
Enabling logging may help uncover useful information about failures. In order to see a log of HTTP requests and responses, set the AZURE_LOG_LEVEL environment variable to info. Alternatively, logging can be enabled at runtime by calling setLogLevel in the @azure/logger:
const { setLogLevel } = require("@azure/logger");
setLogLevel("info");For more detailed instructions on how to enable logs, you can look at the @azure/logger package docs.
Next steps
Please take a look at the samples directory for detailed examples on how to use this library.
Contributing
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.
