快速入门:使用 .NET SDK 和 C# 调用文本分析服务Quickstart: Use the .NET SDK and C# to call the Text Analytics service

本快速入门介绍如何使用用于 .NET 的 Azure SDK 和 C# 来分析语言。This quickstart helps you begin using the Azure SDK for .NET and C# to analyze language. 虽然文本分析 REST API 与大多数编程语言兼容,但该 SDK 提供了一种简单方法来将服务集成到应用程序中。Although the Text Analytics REST API is compatible with most programming languages, the SDK provides an easy way to integrate the service into your applications.

Note

该示例的源代码可在 GitHub 上获得。The source code for this sample is available on GitHub.

先决条件Prerequisites

  • 任何版本的 [Visual Studio 2017 或更高版本]Any edition of [visual studio 2017 or later]
  • 文本分析 SDK for .NET 必须拥有可以访问文本分析 API 的认知服务 API 订阅You must have a Cognitive Services API subscription with access to the Text Analytics API. 如果没有订阅,可以创建一个 1 元试用帐户If you don't have a subscription, you can create a 1rmb trial account. 在继续操作之前,需使用激活帐户后由系统提供的文本分析订阅密钥。Before continuing, you will need the Text Analytics subscription key provided after activating your account.The Text Analytics SDK for .NET 必须拥有可以访问文本分析 API 的认知服务 API 订阅You must have a Cognitive Services API subscription with access to the Text Analytics API. 如果没有订阅,可以创建一个 1 元试用帐户If you don't have a subscription, you can create a 1rmb trial account. 在继续操作之前,需使用激活帐户后由系统提供的文本分析订阅密钥。Before continuing, you will need the Text Analytics subscription key provided after activating your account.

还需要在注册期间为你生成的终结点和访问密钥You also need the endpoint and access key that was generated for you during sign-up.

创建 Visual Studio 解决方案并安装 SDKCreate the Visual Studio solution and install the SDK

  1. 创建新的控制台应用 (.NET Core) 项目。Create a new console app (.NET Core) project. 访问 Visual StudioAccess Visual Studio.
  2. 右键单击解决方案,并选择“管理解决方案的 NuGet 包” 。Right-click the solution and select Manage NuGet Packages for Solution.
  3. 选择“浏览”按钮 。搜索“Microsoft.Azure.CognitiveServices.Language.TextAnalytics”。 Select the Browse tab. Search for Microsoft.Azure.CognitiveServices.Language.TextAnalytics.

对凭据进行验证Authenticate your credentials

  1. 向 main 类文件(默认为 Program.cs)添加以下 using 语句。Add the following using statements to the main class file (which is Program.cs by default).

    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;
    
  2. 创建用于存储凭据的新 ApiKeyServiceClientCredentials 类,并为每个请求添加此类凭据。Create a new ApiKeyServiceClientCredentials class to store the credentials and add them for each request.

    /// <summary>
    /// Allows authentication to the API by using a basic apiKey mechanism
    /// </summary>
    class ApiKeyServiceClientCredentials : ServiceClientCredentials
    {
        private readonly string subscriptionKey;
    
        /// <summary>
        /// Creates a new instance of the ApiKeyServiceClientCredentails class
        /// </summary>
        /// <param name="subscriptionKey">The subscription key to authenticate and authorize as</param>
        public ApiKeyServiceClientCredentials(string subscriptionKey)
        {
            this.subscriptionKey = subscriptionKey;
        }
    
        /// <summary>
        /// Add the Basic Authentication Header to each outgoing request
        /// </summary>
        /// <param name="request">The outgoing request</param>
        /// <param name="cancellationToken">A token to cancel the operation</param>
        public override Task ProcessHttpRequestAsync(HttpRequestMessage request, CancellationToken cancellationToken)
        {
            if (request == null)
            {
                throw new ArgumentNullException("request");
            }
    
            request.Headers.Add("Ocp-Apim-Subscription-Key", this.subscriptionKey);
            return base.ProcessHttpRequestAsync(request, cancellationToken);
        }
    }
    
  3. 更新 Program 类。Update the Program class. 为文本分析订阅密钥添加一个常量成员,为服务终结点添加另一个。Add a constant member for your Text Analytics subscription key, and another for the service endpoint. 记住使用适合文本分析订阅的 Azure 区域。Remember to use the correct Azure region for your Text Analytics subscription.

    private const string SubscriptionKey = "enter-your-key-here";
    
    private const string Endpoint = "enter-your-service-endpoint-here"; // For example: "https://chinaeast2.api.cognitive.azure.cn";
    

Tip

若要在生产系统中增强机密的安全性,建议使用 Azure Key VaultTo boost the security of secrets in production systems, we recommend that you use Azure Key Vault.

创建文本分析客户端Create a Text Analytics client

在项目的 Main 函数中,调用需要调用的示例方法。In the Main function of your project, call the sample method that you want to invoke. 传递所定义的 EndpointSubscriptionKey 参数。Pass the Endpoint and SubscriptionKey parameters that you defined.

    public static void Main(string[] args)
    {
        var credentials = new ApiKeyServiceClientCredentials(SubscriptionKey);
        var client = new TextAnalyticsClient(credentials)
        {
            Endpoint = Endpoint
        };

        // Change the console encoding to display non-ASCII characters.
        Console.OutputEncoding = System.Text.Encoding.UTF8;
        SentimentAnalysisExample(client).Wait();
        // DetectLanguageExample(client).Wait();
        // RecognizeEntitiesExample(client).Wait();
        // KeyPhraseExtractionExample(client).Wait();
        Console.ReadLine();
    }

以下部分介绍如何调用每项服务功能。The following sections describe how to call each service feature.

执行情绪分析Perform sentiment analysis

  1. 创建新函数 SentimentAnalysisExample(),该函数使用以前创建的客户端。Create a new function SentimentAnalysisExample() that takes the client that you created earlier.

  2. 生成 MultiLanguageInput 对象的列表,其中包含要分析的文档。Generate a list of MultiLanguageInput objects that contains the documents that you want to analyze.

    public static async Task SentimentAnalysisExample(TextAnalyticsClient client)
    {
        // The documents to be analyzed. Add the language of the document. The ID can be any value.
        var inputDocuments = new MultiLanguageBatchInput(
            new List<MultiLanguageInput>
            {
                new MultiLanguageInput("en", "1", "I had the best day of my life."),
                new MultiLanguageInput("en", "2", "This was a waste of my time. The speaker put me to sleep."),
                new MultiLanguageInput("es", "3", "No tengo dinero ni nada que dar..."),
                new MultiLanguageInput("it", "4", "L'hotel veneziano era meraviglioso. È un bellissimo pezzo di architettura."),
            });
        //...
    }
    
  3. 在同一函数中,调用 client.SentimentAsync() 并获取结果。In the same function, call client.SentimentAsync() and get the result. 然后循环访问这些结果。Then iterate through the results. 输出每个文档的 ID 和情绪分数。Print each document's ID and sentiment score. 评分接近 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.

    var result = await client.SentimentAsync(false, inputDocuments);
    
    // Printing sentiment results
    foreach (var document in result.Documents)
    {
        Console.WriteLine($"Document ID: {document.Id} , Sentiment Score: {document.Score:0.00}");
    }
    

输出Output

Document ID: 1 , Sentiment Score: 0.87
Document ID: 2 , Sentiment Score: 0.11
Document ID: 3 , Sentiment Score: 0.44
Document ID: 4 , Sentiment Score: 1.00

执行语言检测Perform language detection

  1. 创建新函数 DetectLanguageExample(),该函数使用以前创建的客户端。Create a new function DetectLanguageExample() that takes the client that you created earlier.

  2. 生成 LanguageInput 对象的列表,其中包含你的文档。Generate a list of LanguageInput objects that contains your documents.

    public static async Task DetectLanguageExample(TextAnalyticsClient client)
    {
    
        // The documents to be submitted for language detection. The ID can be any value.
        var inputDocuments = new LanguageBatchInput(
                new List<LanguageInput>
                    {
                        new LanguageInput(id: "1", text: "This is a document written in English."),
                        new LanguageInput(id: "2", text: "Este es un document escrito en Español."),
                        new LanguageInput(id: "3", text: "这是一个用中文写的文件")
                    });
        //...
    }
    
  3. 在同一函数中,调用 client.DetectLanguageAsync() 并获取结果。In the same function, call client.DetectLanguageAsync() and get the result. 然后循环访问这些结果。Then iterate through the results. 输出每个文档的 ID 和第一种返回的语言。Print each document's ID and the first returned language.

    var langResults = await client.DetectLanguageAsync(false, inputDocuments);
    
    // Printing detected languages
    foreach (var document in langResults.Documents)
    {
        Console.WriteLine($"Document ID: {document.Id} , Language: {document.DetectedLanguages[0].Name}");
    }
    

输出Output

===== LANGUAGE EXTRACTION ======
Document ID: 1 , Language: English
Document ID: 2 , Language: Spanish
Document ID: 3 , Language: Chinese_Simplified

执行实体识别Perform entity recognition

  1. 创建新函数 RecognizeEntitiesExample(),该函数使用以前创建的客户端。Create a new function RecognizeEntitiesExample() that takes the client that you created earlier.

  2. 生成 MultiLanguageBatchInput 对象的列表,其中包含你的文档。Generate a list of MultiLanguageBatchInput objects that contains your documents.

    public static async Task RecognizeEntitiesExample(TextAnalyticsClient client)
    {
    
        // The documents to be submitted for entity recognition. The ID can be any value.
        var inputDocuments = new MultiLanguageBatchInput(
            new List<MultiLanguageInput>
            {
                new MultiLanguageInput("en", "1", "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800."),
                new MultiLanguageInput("es", "2", "La sede principal de Microsoft se encuentra en la ciudad de Redmond, a 21 kilómetros de Seattle.")
            });
        //...
    }
    
  3. 在同一函数中,调用 client.EntitiesAsync() 并获取结果。In the same function, call client.EntitiesAsync() and get the result. 然后循环访问这些结果。Then iterate through the results. 输出每个文档的 ID。Print each document's ID. 对于每个检测到的实体,输出其维基百科名称、类型和子类型(如果存在),以及其在原始文本中的位置。For each detected entity, print its Wikipedia name and the type and subtypes (if they exist) as well as the locations in the original text.

    var entitiesResult = await client.EntitiesAsync(false, inputDocuments);
    
    // Printing recognized entities
    foreach (var document in entitiesResult.Documents)
    {
        Console.WriteLine($"Document ID: {document.Id} ");
    
        Console.WriteLine("\t Entities:");
        foreach (var entity in document.Entities)
        {
            Console.WriteLine($"\t\tName: {entity.Name},\tType: {entity.Type ?? "N/A"},\tSub-Type: {entity.SubType ?? "N/A"}");
            foreach (var match in entity.Matches)
            {
                Console.WriteLine($"\t\t\tOffset: {match.Offset},\tLength: {match.Length},\tScore: {match.EntityTypeScore:F3}");
            }
        }
    }
    

输出Output

Document ID: 1
         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
Document ID: 2
         Entities:
                Name: Microsoft,        Type: Organization,     Sub-Type: N/A
                        Offset: 21,     Length: 9,      Score: 1.000
                Name: Redmond (Washington),     Type: Location, Sub-Type: N/A
                        Offset: 60,     Length: 7,      Score: 0.991
                Name: 21 kilómetros,    Type: Quantity, Sub-Type: Dimension
                        Offset: 71,     Length: 13,     Score: 0.800
                Name: Seattle,  Type: Location, Sub-Type: N/A
                        Offset: 88,     Length: 7,      Score: 1.000

执行关键短语提取操作Perform key phrase extraction

  1. 创建新函数 KeyPhraseExtractionExample(),该函数使用以前创建的客户端。Create a new function KeyPhraseExtractionExample() that takes the client that you created earlier.

  2. 生成 MultiLanguageBatchInput 对象的列表,其中包含你的文档。Generate a list of MultiLanguageBatchInput objects that contains your documents.

    public static async Task KeyPhraseExtractionExample(TextAnalyticsClient client)
    {
        var inputDocuments = new MultiLanguageBatchInput(
                    new List<MultiLanguageInput>
                    {
                        new MultiLanguageInput("ja", "1", "猫は幸せ"),
                        new MultiLanguageInput("de", "2", "Fahrt nach Stuttgart und dann zum Hotel zu Fu."),
                        new MultiLanguageInput("en", "3", "My cat might need to see a veterinarian."),
                        new MultiLanguageInput("es", "4", "A mi me encanta el fútbol!")
                    });
        //...
    }
    
  3. 在同一函数中,调用 client.KeyPhrasesAsync() 并获取结果。In the same function, call client.KeyPhrasesAsync() and get the result. 然后循环访问这些结果。Then iterate through the results. 输出每个文档的 ID 以及任何检测到的关键短语。Print each document's ID and any detected key phrases.

    var kpResults = await client.KeyPhrasesAsync(false, inputDocuments);
    
    // Printing keyphrases
    foreach (var document in kpResults.Documents)
    {
        Console.WriteLine($"Document ID: {document.Id} ");
    
        Console.WriteLine("\t Key phrases:");
    
        foreach (string keyphrase in document.KeyPhrases)
        {
            Console.WriteLine($"\t\t{keyphrase}");
        }
    }
    

输出Output

Document ID: 1
         Key phrases:
                幸せ
Document ID: 2
         Key phrases:
                Stuttgart
                Hotel
                Fahrt
                Fu
Document ID: 3
         Key phrases:
                cat
                veterinarian
Document ID: 4
         Key phrases:
                fútbol

后续步骤Next steps