クイック スタート:.NET 用 Text Analytics クライアント ライブラリQuickstart: Text analytics client library for .NET

.NET 用 Text Analytics クライアント ライブラリの概要を紹介します。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 用 Text Analytics クライアント ライブラリを使って次のことを実行します。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

注意

この記事のデモ コードでは、簡単にするため、Text Analytics .NET SDK の同期メソッドを使用します。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. たとえば、Sentiment() の代わりに SentimentBatchAsync() を呼び出します。For example, calling SentimentBatchAsync() instead of Sentiment().

前提条件Prerequisites

設定Setting up

Text Analytics Azure リソースを作成するCreate a Text Analytics Azure resource

(ユーザーがサブスクライブする Azure リソースによって表される) Azure Cognitive Services によってユーザーのアプリケーションを認証するためのキーを取得します。Get a key to authenticate your applications by Azure Cognitive Services are represented by Azure resources that you subscribe to. Azure portal または Azure CLI を使用して、ローカル コンピューター上に Text Analytics のリソースを作成します。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

好みのエディターまたは IDE で、新しい .NET Core アプリケーションを作成します。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. このコマンドにより、1 つのソース ファイル (program.cs) を使用する単純な "Hello World" C# プロジェクトが作成されます。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)
...

プロジェクト ディレクトリから、好みのエディターまたは IDE で 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;

アプリケーションの Program クラスで、対象のリソースの Azure エンドポイントおよびサブスクリプション キー用の変数を作成します。In the application's Program class, create variables for your resource's Azure endpoint and subscription key. 静的コンストラクターでは、これらの値を環境変数 TEXT_ANALYTICS_SUBSCRIPTION_KEY および TEXT_ANALYTICS_ENDPOINT から取得します。In a static constructor, obtain these values from the environment variables TEXT_ANALYTICS_SUBSCRIPTION_KEY and TEXT_ANALYTICS_ENDPOINT. アプリケーションの編集開始後にこれらの環境変数を作成した場合は、その変数へのアクセスに使用しているエディター、IDE、またはシェルを閉じて、もう一度開く必要があります。If you created these environment variables after you began editing the application, you will need to close and reopen the editor, IDE, or shell you are using to access the variables.

private const string key_var = "TEXT_ANALYTICS_SUBSCRIPTION_KEY";
private static readonly string subscriptionKey = Environment.GetEnvironmentVariable(key_var);

private const string endpoint_var = "TEXT_ANALYTICS_ENDPOINT";
private static readonly string endpoint = Environment.GetEnvironmentVariable(endpoint_var);

static Program()
{
    if (null == subscriptionKey)
    {
        throw new Exception("Please set/export the environment variable: " + key_var);
    }
    if (null == endpoint)
    {
        throw new Exception("Please set/export the environment variable: " + endpoint_var);
    }
}

アプリケーションの Main メソッド内で、Text Analytics エンドポイントにアクセスするための資格情報を作成します。In the application's Main method, create credentials to access the Text Analytics endpoint. Main メソッドによって呼び出されるメソッドは、後で定義します。You will define the methods called by the Main method later.

ヒント

Azure portal でキーとエンドポイントを見つけるには、次のように操作します。To find your key and endpoint on the Azure portal:

  1. https://portal.azure.com/ で Azure リソースに移動します。Navigate to your azure resource at https://portal.azure.com/.
  2. [リソース管理] の下にある [クイック スタート] をクリックします。Click on Quick start, located under Resource Management.
static void Main(string[] args)
{
    var credentials = new ApiKeyServiceClientCredentials(subscriptionKey);
    TextAnalyticsClient client = new TextAnalyticsClient(credentials)
    {
        Endpoint = endpoint
    };

    Console.OutputEncoding = System.Text.Encoding.UTF8;
    SentimentAnalysisExample(client);
    // languageDetectionExample(client);
    // entityRecognitionExample(client);
    // KeyPhraseExtractionExample(client);
    
    Console.Write("Press any key to exit.");
    Console.ReadKey();
}

クライアント ライブラリをインストールするInstall the client library

次のコマンドを使用して、アプリケーション ディレクトリ内に .NET 用 Text Analytics クライアント ライブラリをインストールします。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 IDE を使用している場合、クライアント ライブラリは、ダウンロード可能な NuGet パッケージとして入手できます。If you're using the Visual Studio IDE, the client library is available as a downloadable NuGet package.

オブジェクト モデルObject model

Text Analytics クライアントは、ご利用のキーを使用して Azure に対して認証を行う TextAnalyticsClient オブジェクトであり、テキストを単一の文字列またはバッチとして受け取る機能を提供します。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. その中で、Ocp-Apim-Subscription-Key ヘッダーにキーを追加する ProcessHttpRequestAsync() のオーバーライドを作成します。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}");
}

OutputOutput

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 パラメーターを使用して、2 文字の国番号を指定できます。You can use the countryHint parameter to specify a 2-letter country code. API の既定では、既定の countryHint として "US" が使用されます。この動作を削除するには、この値を空の文字列 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}");
}

OutputOutput

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. 検出されたエンティティごとに、その型、サブタイプ、Wikipedia 名 (存在する場合)、および元のテキスト内の場所を出力します。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}");
        }
    }
}

OutputOutput

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.

static void KeyPhraseExtractionExample(TextAnalyticsClient client)
{
    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}");
    }
}

OutputOutput

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