Краткое руководство. Клиентская библиотека Аналитики текста для .NETQuickstart: Text analytics client library for .NET

Начало работы с клиентской библиотекой "Аналитика текста" для .NET.Get started with the Text Analytics client library for .NET. Выполните приведенные здесь действия, чтобы установить пакет и протестировать пример кода для выполнения базовых задач.Follow these steps to install the package and try out the example code for basic tasks.

Используйте клиентскую библиотеку "Аналитика текста" для .NET, чтобы выполнить следующие действия:Use the Text Analytics client library for .NET to perform:

  • Анализ мненийSentiment analysis
  • Определение языкаLanguage detection
  • Распознавание сущностейEntity recognition
  • Извлечение ключевой фразыKey phrase extraction

Справочная документация | Исходный код библиотеки | Пакет (NuGet) | ПримерыReference documentation | Library source code | Package (NuGet) | Samples

Примечание

В демонстрационном коде этой статьи для простоты используются синхронные методы пакета SDK .NET для Анализа текста.The demo code in this article uses the synchronous methods of the Text Analytics .NET SDK for simplicity. Но в приложениях для рабочей среды мы рекомендуем использовать пакетные асинхронные методы, чтобы обеспечить масштабируемость и высокую скорость отклика.However, for production scenarios, we recommend using the batched asynchronous methods in your own applications to keep them scalable and responsive. Например, вызовите SentimentBatchAsync() вместо Sentiment().For example, calling SentimentBatchAsync() instead of Sentiment().

Предварительные требованияPrerequisites

НастройкаSetting up

Создание ресурса для Анализа текста в AzureCreate a Text Analytics Azure resource

Получите ключ для проверки подлинности приложений в Azure Cognitive Services, представленных ресурсами Azure, на которые вы подписаны.Get a key to authenticate your applications by Azure Cognitive Services are represented by Azure resources that you subscribe to. Создайте ресурс для Аналитики текста с помощью портала Azure или интерфейса командной строки Azure (CLI) на локальном компьютере.Create a resource for Text Analytics using the Azure portal or Azure CLI on your local machine. Также можно:You can also:

После получения ключа из своего ресурса или пробной подписки задайте переменную среды для ключа с именем TEXT_ANALYTICS_SUBSCRIPTION_KEY.After you get a key from your trial subscription or resource, create an environment variable for the key, named TEXT_ANALYTICS_SUBSCRIPTION_KEY.

Создание нового приложения C#Create a new C# application

Создайте консольное приложение .NET Core на C# в предпочитаемой интегрированной среде разработки или редакторе.Create a new .NET Core application in your preferred editor or IDE.

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем text-analytics quickstart.In a console window (such as cmd, PowerShell, or Bash), use the dotnet new command to create a new console app with the name text-analytics quickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода: program.cs.This command creates a simple "Hello World" C# project with a single source file: program.cs.

dotnet new console -n text-analytics-quickstart

Измените каталог на созданную папку приложения.Change your directory to the newly created app folder. Чтобы создать приложение, выполните следующую команду:You can build the application with:

dotnet build

Выходные данные сборки не должны содержать предупреждений или ошибок.The build output should contain no warnings or errors.

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

В каталоге проекта откройте файл program.cs в предпочитаемом редакторе или интегрированной среде разработки.From the project directory, open the program.cs file in your preferred editor or IDE. Затем добавьте следующие using директивы:Add the following using directives:

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Azure.CognitiveServices.Language.TextAnalytics;
using Microsoft.Azure.CognitiveServices.Language.TextAnalytics.Models;
using Microsoft.Rest;

В методе приложения Main создайте переменные для конечной точки и ключа Azure вашего ресурса.In the application's Main method, create variables for your resource's Azure endpoint and key. Если вы создали переменную среды после запуска приложения, для доступа к переменной следует закрыть и повторно открыть редактор, интегрированную среду разработки или оболочку, где эта переменная была запущена.If you created the environment variable after you launched the application, you will need to close and reopen the editor, IDE, or shell running it to access the variable. Эти методы будут определены позже.You will define the methods later.

Совет

Чтобы найти ключ и конечную точку на портале Azure, сделайте следующее:To find your key and endpoint on the Azure portal:

  1. Перейдите к ресурсу Azure по адресу: https://portal.azure.com/Navigate to your azure resource at https://portal.azure.com/.
  2. Щелкните элемент Быстрый запуск, расположенный в разделе Управление ресурсами.Click on Quick start, located under Resource Management.

Не забудьте удалить суффикс /text/analytics/<version> в конечной точке при его наличии.Be sure to remove the /text/analytics/<version> suffix from your endpoint, if it contains one. Этот суффикс не требуется для использования с клиентскими библиотеками.This suffix isn't needed for use with the client libraries.

static void Main(string[] args)
{
    // replace this endpoint with the correct one for your Azure resource. 
    string endpoint = $"https://westus.api.cognitive.microsoft.com";
    //This sample assumes you have created an environment variable for your key
    string key = Environment.GetEnvironmentVariable("TEXT_ANALYTICS_SUBSCRIPTION_KEY");

    var credentials = new ApiKeyServiceClientCredentials(key);
    TextAnalyticsClient client = new TextAnalyticsClient(credentials)
    {
        Endpoint = endpoint
    };

    Console.OutputEncoding = System.Text.Encoding.UTF8;
    SentimentAnalysisExample(client);
    // languageDetectionExample(client);
    // RecognizeEntitiesExample(client);
    // KeyPhraseExtractionExample(client);
    Console.ReadLine();
}

Установка клиентской библиотекиInstall the client library

В каталоге приложения установите клиентскую библиотеку "Аналитика текста" для .NET с помощью следующей команды:Within the application directory, install the Text Analytics client library for .NET with the following command:

dotnet add package Microsoft.Azure.CognitiveServices.Language.TextAnalytics --version 4.0.0

Если вы используете интегрированную среду разработки Visual Studio, клиентская библиотека доступна в виде загружаемого пакета NuGet.If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

Объектная модельObject model

Клиент Аналитики текста является объектом TextAnalyticsClient, который выполняет проверку подлинности в Azure с помощью вашего ключа и предоставляет функции для приема текста в виде отдельных строк или пакета.The Text Analytics client is a TextAnalyticsClient object that authenticates to Azure using your key, and provides functions to accept text as single strings or as a batch. Текст в API можно отправлять как синхронно, так и асинхронно.You can send text to the API synchronously, or asynchronously. Объект в ответе будет содержать аналитическую информацию по каждому отправленному вами документу.The response object will contain the analysis information for each document you send.

Примеры кодаCode examples

Аутентификация клиентаAuthenticate the client

Создайте новый ApiKeyServiceClientCredentials класс для хранения учетных данных и добавьте их в запросы клиента.Create a new ApiKeyServiceClientCredentials class to store the credentials and add them to the client's requests. В нем создайте переопределитель для ProcessHttpRequestAsync(), который добавляет ваш ключ в Ocp-Apim-Subscription-Key заголовок.Within it, create an override for ProcessHttpRequestAsync() that adds your key to the Ocp-Apim-Subscription-Key header.

class ApiKeyServiceClientCredentials : ServiceClientCredentials
{
    private readonly string apiKey;

    public ApiKeyServiceClientCredentials(string apiKey)
    {
        this.apiKey = apiKey;
    }

    public override Task ProcessHttpRequestAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        if (request == null)
        {
            throw new ArgumentNullException("request");
        }
        request.Headers.Add("Ocp-Apim-Subscription-Key", this.apiKey);
        return base.ProcessHttpRequestAsync(request, cancellationToken);
    }
}

В методе main() создайте клиента с ключом и конечной точкой.In the main() method, instantiate the client with your key and endpoint.

var credentials = new ApiKeyServiceClientCredentials(key);
TextAnalyticsClient client = new TextAnalyticsClient(credentials)
{
    Endpoint = endpoint
};

Анализ мненийSentiment analysis

Создайте новую функцию с именем SentimentAnalysisExample(), которая принимает созданного ранее клиента и вызывает его функциюSentiment() (Тональность).Create a new function called SentimentAnalysisExample() that takes the client that you created earlier, and call its Sentiment() function. Возвращаемый объектSentimentResult будет содержать тональность Score, если выполнение успешное и значение errorMessage, если нет.The returned SentimentResult object will contain the sentiment Score if successful, and an errorMessage if not.

Оценка, близкая к 0, указывает на негативную тональность, а близкая к 1 — на позитивную.A score that's close to 0 indicates a negative sentiment, while a score that's closer to 1 indicates a positive sentiment.

static void SentimentAnalysisExample(TextAnalyticsClient client){
    var result = client.Sentiment("I had the best day of my life.", "en");
    Console.WriteLine($"Sentiment Score: {result.Score:0.00}");
}

Выходные данныеOutput

Sentiment Score: 0.87

Определение языкаLanguage detection

Создайте новую функцию с именем languageDetectionExample(), которая принимает созданного ранее клиента и вызывает функциюDetectLanguage(.Create a new function called languageDetectionExample() that takes the client that you created earlier, and call its DetectLanguage() function. Возвращенный объектLanguageResult будет содержать список обнаруженных языков DetectedLanguages если выполнение успешное и значение errorMessage, если нет.The returned LanguageResult object will contain the list of detected languages in DetectedLanguages if successful, and an errorMessage if not. Выведите первый возвращенный язык.Print the first returned language.

Совет

В некоторых случаях неоднозначность языков на основе входных данных может быть трудно устранить.In some cases it may be hard to disambiguate languages based on the input. Используйте параметр countryHint, чтобы указать двухбуквенный код страны.You can use the countryHint parameter to specify a 2-letter country code. По умолчанию API использует US в качестве значения countryHint по умолчанию.Чтобы отменить это поведение, вы можете сбросить этот параметр, установив для этого значения пустую строку countryHint = "".By default the API is using the "US" as the default countryHint, to remove this behavior you can reset this parameter by setting this value to empty string countryHint = "" .

static void languageDetectionExample(TextAnalyticsClient client){
    var result = client.DetectLanguage("This is a document written in English.");
    Console.WriteLine($"Language: {result.DetectedLanguages[0].Name}");
}

Выходные данныеOutput

Language: English

Распознавание сущностейEntity recognition

Создайте новую функцию с именем RecognizeEntitiesExample(), которая принимает созданного ранее клиента и вызывает его функциюEntities().Create a new function called RecognizeEntitiesExample() that takes the client that you created earlier, and call its Entities() function. Выполните итерацию результатов.Iterate through the results. Возвращенный объектEntitiesResult будет содержать список обнаруженных сущностей Entities если выполнение успешное и значение errorMessage, если нет.The returned EntitiesResult object will contain the list of detected entities in Entities if successful, and an errorMessage if not. Для каждой обнаруженной сущности выведите ее тип, подтип, имя в Википедии (если они есть), а также расположение в исходном тексте.For each detected entity, print its Type, Sub-Type, Wikipedia name (if they exist) as well as the locations in the original text.

static void entityRecognitionExample(TextAnalyticsClient client){

    var result = client.Entities("Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800.");
    Console.WriteLine("Entities:");
    foreach (var entity in result.Entities){
        Console.WriteLine($"\tName: {entity.Name},\tType: {entity.Type ?? "N/A"},\tSub-Type: {entity.SubType ?? "N/A"}");
        foreach (var match in entity.Matches){
            Console.WriteLine($"\t\tOffset: {match.Offset},\tLength: {match.Length},\tScore: {match.EntityTypeScore:F3}");
        }
    }
}

Выходные данныеOutput

Entities:
    Name: Microsoft,        Type: Organization,     Sub-Type: N/A
        Offset: 0,      Length: 9,      Score: 1.000
    Name: Bill Gates,       Type: Person,   Sub-Type: N/A
        Offset: 25,     Length: 10,     Score: 1.000
    Name: Paul Allen,       Type: Person,   Sub-Type: N/A
        Offset: 40,     Length: 10,     Score: 0.999
    Name: April 4,  Type: Other,    Sub-Type: N/A
        Offset: 54,     Length: 7,      Score: 0.800
    Name: April 4, 1975,    Type: DateTime, Sub-Type: Date
        Offset: 54,     Length: 13,     Score: 0.800
    Name: BASIC,    Type: Other,    Sub-Type: N/A
        Offset: 89,     Length: 5,      Score: 0.800
    Name: Altair 8800,      Type: Other,    Sub-Type: N/A
        Offset: 116,    Length: 11,     Score: 0.800

Извлечение ключевой фразыKey phrase extraction

Создайте новую функцию с именем KeyPhraseExtractionExample(), которая принимает созданного ранее клиента и вызывает его функциюKeyPhrases().Create a new function called KeyPhraseExtractionExample() that takes the client that you created earlier and call its KeyPhrases() function. При успешном выполнении результат будет содержать список обнаруженных ключевых фраз в KeyPhrases. В противном случае вернется errorMessage.The result will contain the list of detected key phrases in KeyPhrases if successful, and an errorMessage if not. Затем выведите все обнаруженные ключевые фразы.Print any detected key phrases.

var result = client.KeyPhrases("My cat might need to see a veterinarian.");

// Printing key phrases
Console.WriteLine("Key phrases:");

foreach (string keyphrase in result.KeyPhrases)
{
    Console.WriteLine($"\t{keyphrase}");
}

Выходные данныеOutput

Key phrases:
    cat
    veterinarian

Очистка ресурсовClean up resources

Если вы хотите очистить и удалить подписку Cognitive Services, вы можете удалить ресурс или группу ресурсов.If you want to clean up and remove a Cognitive Services subscription, you can delete the resource or resource group. При этом удаляются все ресурсы, связанные с этой группой ресурсов.Deleting the resource group also deletes any other resources associated with the resource group.

Дополнительная информацияNext steps

Text Analytics with Power BI (Анализ текста с использованием Power BI)Text Analytics With Power BI