您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

Azure Cognitive Services Text Analytics client library for .NET - Version 5.0.0

Azure Cognitive Services Text Analytics is a cloud service that provides advanced natural language processing over raw text, and includes the following main functions:

  • Language Detection
  • Sentiment Analysis
  • Key Phrase Extraction
  • Named Entity Recognition
  • Linked Entity Recognition

Source code | Package (NuGet) | API reference documentation | Product documentation | Samples

Getting started

Install the package

Install the Azure Text Analytics client library for .NET with NuGet:

dotnet add package Azure.AI.TextAnalytics

Note: This package version targets Azure Text Analytics service API version v3.0.

Prerequisites

Create a Cognitive Services or Text Analytics resource

Text Analytics supports both multi-service and single-service access. Create a Cognitive Services resource if you plan to access multiple cognitive services under a single endpoint/key. For Text Analytics access only, create a Text Analytics resource.

You can create either resource using:

Option 1: Azure Portal.

Option 2: Azure CLI.

Below is an example of how you can create a Text Analytics resource using the CLI:

# Create a new resource group to hold the Text Analytics resource -
# if using an existing resource group, skip this step
az group create --name <your-resource-name> --location <location>
# Create Text Analytics
az cognitiveservices account create \
    --name <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind TextAnalytics \
    --sku <sku> \
    --location <location> \
    --yes

For more information about creating the resource or how to get the location and sku information see here.

Authenticate the client

In order to interact with the Text Analytics service, you'll need to create an instance of the TextAnalyticsClient class. You will need an endpoint, and either an API key or TokenCredential to instantiate a client object. For more information regarding authenticating with cognitive services, see Authenticate requests to Azure Cognitive Services.

Get API Key

You can get the endpoint and API key from the Cognitive Services resource or Text Analytics resource information in the Azure Portal.

Alternatively, use the Azure CLI snippet below to get the API key from the Text Analytics resource.

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

Create TextAnalyticsClient with API Key Credential

Once you have the value for the API key, create an AzureKeyCredential. This will allow you to update the API key without creating a new client.

With the value of the endpoint and an AzureKeyCredential, you can create the TextAnalyticsClient:

string endpoint = "<endpoint>";
string apiKey = "<apiKey>";
var credential = new AzureKeyCredential(apiKey);
var client = new TextAnalyticsClient(new Uri(endpoint), credential);

Create TextAnalyticsClient with Azure Active Directory Credential

Client API key authentication is used in most of the examples in this getting started guide, but you can also authenticate with Azure Active Directory using the Azure Identity library. Note that regional endpoints do not support AAD authentication. Create a custom subdomain for your resource in order to use this type of authentication.

To use the DefaultAzureCredential provider shown below, or other credential providers provided with the Azure SDK, please install the Azure.Identity package:

Install-Package Azure.Identity

You will also need to register a new AAD application and grant access to Text Analytics by assigning the "Cognitive Services User" role to your service principal.

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.

string endpoint = "<endpoint>";
var client = new TextAnalyticsClient(new Uri(endpoint), new DefaultAzureCredential());

Key concepts

TextAnalyticsClient

A TextAnalyticsClient is the primary interface for developers using the Text Analytics client library. It provides both synchronous and asynchronous operations to access a specific use of Text Analytics, such as language detection or key phrase extraction.

Input

A document, is a single unit of input to be analyzed by the predictive models in the Text Analytics service. Operations on TextAnalyticsClient may take a single document or a collection of documents to be analyzed as a batch. For document length limits, maximum batch size, and supported text encoding see here.

Operation on multiple documents

For each supported operation, TextAnalyticsClient provides a method that accepts a batch of documents as strings, or a batch of either TextDocumentInput or DetectLanguageInput objects. This methods allow callers to give each document a unique ID, indicate that the documents in the batch are written in different languages, or provide a country hint about the language of the document.

Note: It is recommended to use the batch methods when working on production environments as they allow you to send one request with multiple documents. This is more performant than sending a request per each document.

Return value

Return values, such as AnalyzeSentimentResult, is the result of a Text Analytics operation, containing a prediction or predictions about a single document. An operation's return value also may optionally include information about the document and how it was processed.

Return value Collection

A Return value collection, such as AnalyzeSentimentResultCollection, is a collection of operation results, where each corresponds to one of the documents provided in the input batch. A document and its result will have the same index in the input and result collections. The return value also contains a HasError property that allows to identify if an operation executed was succesful or unsuccesful for the given document. It may optionally include information about the document batch and how it was processed.

Examples

The following section provides several code snippets using the client created above, and covers the main functions of Text Analytics.

Sync examples

Async examples

Detect Language

Run a Text Analytics predictive model to determine the language that the passed-in document or batch of documents are written in.

string document = "Este documento está en español.";

DetectedLanguage language = client.DetectLanguage(document);

Console.WriteLine($"Detected language {language.Name} with confidence score {language.ConfidenceScore}.");

For samples on using the production recommended option DetectLanguageBatch see here.

Please refer to the service documentation for a conceptual discussion of language detection.

Analyze Sentiment

Run a Text Analytics predictive model to identify the positive, negative, neutral or mixed sentiment contained in the passed-in document or batch of documents.

string document = "That was the best day of my life!";

DocumentSentiment docSentiment = client.AnalyzeSentiment(document);

Console.WriteLine($"Sentiment was {docSentiment.Sentiment}, with confidence scores: ");
Console.WriteLine($"    Positive confidence score: {docSentiment.ConfidenceScores.Positive}.");
Console.WriteLine($"    Neutral confidence score: {docSentiment.ConfidenceScores.Neutral}.");
Console.WriteLine($"    Negative confidence score: {docSentiment.ConfidenceScores.Negative}.");

For samples on using the production recommended option AnalyzeSentimentBatch see here.

Please refer to the service documentation for a conceptual discussion of sentiment analysis.

Extract Key Phrases

Run a model to identify a collection of significant phrases found in the passed-in document or batch of documents.

string document = "My cat might need to see a veterinarian.";

KeyPhraseCollection keyPhrases = client.ExtractKeyPhrases(document);

Console.WriteLine($"Extracted {keyPhrases.Count} key phrases:");
foreach (string keyPhrase in keyPhrases)
{
    Console.WriteLine(keyPhrase);
}

For samples on using the production recommended option ExtractKeyPhrasesBatch see here.

Please refer to the service documentation for a conceptual discussion of key phrase extraction.

Recognize Entities

Run a predictive model to identify a collection of named entities in the passed-in document or batch of documents and categorize those entities into categories such as person, location, or organization. For more information on available categories, see Text Analytics Named Entity Categories.

string document = "Microsoft was founded by Bill Gates and Paul Allen.";

CategorizedEntityCollection entities = client.RecognizeEntities(document);

Console.WriteLine($"Recognized {entities.Count} entities:");
foreach (CategorizedEntity entity in entities)
{
    Console.WriteLine($"Text: {entity.Text}, Category: {entity.Category}, SubCategory: {entity.SubCategory}, Confidence score: {entity.ConfidenceScore}");
}

For samples on using the production recommended option RecognizeEntitiesBatch see here.

Please refer to the service documentation for a conceptual discussion of named entity recognition.

Recognize Linked Entities

Run a predictive model to identify a collection of entities found in the passed-in document or batch of documents, and include information linking the entities to their corresponding entries in a well-known knowledge base.

string document = "Microsoft was founded by Bill Gates and Paul Allen.";

LinkedEntityCollection linkedEntities = client.RecognizeLinkedEntities(document);

Console.WriteLine($"Extracted {linkedEntities.Count} linked entit{(linkedEntities.Count > 1 ? "ies" : "y")}:");
foreach (LinkedEntity linkedEntity in linkedEntities)
{
    Console.WriteLine($"Name: {linkedEntity.Name}, Language: {linkedEntity.Language}, Data Source: {linkedEntity.DataSource}, Url: {linkedEntity.Url.ToString()}, Entity Id in Data Source: {linkedEntity.DataSourceEntityId}");
    foreach (LinkedEntityMatch match in linkedEntity.Matches)
    {
        Console.WriteLine($"    Match Text: {match.Text}, Confidence score: {match.ConfidenceScore}");
    }
}

For samples on using the production recommended option RecognizeLinkedEntitiesBatch see here.

Please refer to the service documentation for a conceptual discussion of entity linking.

Detect Language Asynchronously

Run a Text Analytics predictive model to determine the language that the passed-in document or batch of documents are written in.

string document = "Este documento está en español.";

DetectedLanguage language = await client.DetectLanguageAsync(document);

Console.WriteLine($"Detected language {language.Name} with confidence score {language.ConfidenceScore}.");

Recognize Entities Asynchronously

Run a predictive model to identify a collection of named entities in the passed-in document or batch of documents and categorize those entities into categories such as person, location, or organization. For more information on available categories, see Text Analytics Named Entity Categories.

string document = "Microsoft was founded by Bill Gates and Paul Allen.";

CategorizedEntityCollection entities = await client.RecognizeEntitiesAsync(document);

Console.WriteLine($"Recognized {entities.Count} entities:");
foreach (CategorizedEntity entity in entities)
{
    Console.WriteLine($"Text: {entity.Text}, Category: {entity.Category}, SubCategory: {entity.SubCategory}, Confidence score: {entity.ConfidenceScore}");
}

Troubleshooting

General

When you interact with the Cognitive Services Text Analytics client library using the .NET SDK, errors returned by the service correspond to the same HTTP status codes returned for REST API requests.

For example, if you submit a batch of text document inputs containing duplicate document ids, a 400 error is returned, indicating "Bad Request".

try
{
    DetectedLanguage result = client.DetectLanguage(document);
}
catch (RequestFailedException e)
{
    Console.WriteLine(e.ToString());
}

You will notice that additional information is logged, like the client request ID of the operation.

Message:
    Azure.RequestFailedException:
    Status: 400 (Bad Request)

Content:
    {"error":{"code":"InvalidRequest","innerError":{"code":"InvalidDocument","message":"Request contains duplicated Ids. Make sure each document has a unique Id."},"message":"Invalid document in request."}}

Headers:
    Transfer-Encoding: chunked
    x-aml-ta-request-id: 146ca04a-af54-43d4-9872-01a004bee5f8
    X-Content-Type-Options: nosniff
    x-envoy-upstream-service-time: 6
    apim-request-id: c650acda-2b59-4ff7-b96a-e316442ea01b
    Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
    Date: Wed, 18 Dec 2019 16:24:52 GMT
    Content-Type: application/json; charset=utf-8

Setting up console logging

The simplest way to see the logs is to enable the console logging. To create an Azure SDK log listener that outputs messages to console use AzureEventSourceListener.CreateConsoleLogger method.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

To learn more about other logging mechanisms see here.

Next steps

Samples showing how to use the Cognitive Services Text Analytics library are available in this GitHub repository. Samples are provided for each main functional area, and for each area, samples are provided for analyzing a single document, and a collection of documents in both sync and async mode.

Contributing

See the CONTRIBUTING.md for details on building, testing, and contributing to this library.

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions