Azure Text Analysis client library for JavaScript - version 1.1.0

  • Article

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

See our support policy for more details.

Prerequisites

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-text

Create 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/identity

You 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

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.

Impressions