新型コロナ対応？Text Analytics でテキスト分析 (2020年12月版) ~ Microsoft Azure Cognitive Services | Language

Cognitive Services Text Analytics は、テキスト(文章)から言語やキーフレーズ、エンティティの抽出やセンチメント(ネガポジ)分析が可能なサービスです。

[Microsoft Azure > Cognitive Services > Text Analytics](https://azure.microsoft.com/ja-jp/services/cognitive-services/text-analytics/)

新型コロナ対応か、Healthcare Analysis (医療関係用語対応のテキスト分析) が v3.1 (preview) で追加されているので、それも合わせて Text Analytics の機能を紹介します。

# Text Analytics の主な機能

## v3.0(GA)

| # | 機能 | API名称 |
|:--|:-----------|:---------------------|
| 1 | 言語検出 | [Detect Language](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/Languages) |
| 2 | キーフレーズ抽出 | [Key Phrases](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/KeyPhrases)|
| 3 | エンティティ抽出 | [Named Entity Recognition](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/EntitiesRecognitionGeneral) |
| 4 | エンティティのリンク情報検索 | [Entities Linking](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/EntitiesLinking) |
| 5 | センチメント分析 | [Sentiment](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/operations/Sentiment) |

## v3.1(Preview) で追加されている機能

| # | 機能 | API名称 |
|:--|:-----------|:---------------------|
| 6 | 個人情報エンティティ抽出 | [Entities Recognition PII](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/operations/EntitiesRecognitionPii) |
| 7 | テキスト分析<br/>(※バッチジョブ) | [Analysis Job](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/operations/Analyze) |
| 8 | Healthcare Analysis<br/>(※バッチジョブ) | [Healthcare Analysis Job](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/operations/Health) |


# Text Analytics の使い方

## 必要な準備

- Azure サブスクリプション (無料試用版でOK)
- Text Analytics サービスの作成 (Free版でOK)

[Azure 無料試用版 & Cognitive Services 準備](https://qiita.com/annie/items/3c9ddc3fb8f120769239) の手順を参考に作成しておきます。

## Web API リクエストなど使い方

Web API リクエスト、または SDK ( [.NET C#](https://docs.microsoft.com/ja-jp/azure/cognitive-services/text-analytics/quickstarts/text-analytics-sdk?tabs=version-3&pivots=programming-language-csharp), [JavaScript](https://docs.microsoft.com/ja-jp/azure/cognitive-services/text-analytics/quickstarts/text-analytics-sdk?tabs=version-3&pivots=programming-language-javascript), [Python](https://docs.microsoft.com/ja-jp/azure/cognitive-services/text-analytics/quickstarts/text-analytics-sdk?tabs=version-3&pivots=programming-language-python), [Java](https://docs.microsoft.com/ja-jp/azure/cognitive-services/text-analytics/quickstarts/text-analytics-sdk?tabs=version-3&pivots=programming-language-java)) も利用できます。

Web API の仕様は API リファレンスから確認できます
- [v3.0](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-0/)
- [v3.1 Preview](https://westus.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/)

Web API なので、例えば以下のように情報をセットしてリクエストを送信、結果を取得します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/keyPhrases
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "language": "ja",
      "id": "1",
      "text": "おはよう世界"
    }
  ]
}
```

YOUR_TA_URL(エンドポイント) と YOUR_SUB_KEY(キー) は Text Analytics のサービス作成時や Azure Portal から確認してください。

## コンテナーの利用

Web API リクエストで利用できる Text Analytics は、ローカル環境に配置して利用できる Docker コンテナー も用意されています。(Dockerコンテナーで稼働させる Web サービスに API Request して利用します。)
Text Analytics の機能では、言語検出＆キーフレーズ抽出、センチメント分析、Healthcare Analysis がコンテナーとして提供されています。

[Microsoft Docs > Azure Cognitive Services コンテナー](https://docs.microsoft.com/ja-jp/azure/cognitive-services/cognitive-services-container-support)
[Microsoft Docs > Text Analytics コンテナーをインストールして実行する](https://docs.microsoft.com/ja-jp/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-install-containers)

利用イメージ↓
[Cognitive Services Containers を利用して ローカルの Docker コンテナで Text Analytics Sentiment を試す](https://qiita.com/annie/items/21bb726e9bbc8db56e54)

# 利用できる Web API と機能

## 1. 言語検出

文章の言語を判定します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/languages
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "countryHint": "US",
      "id": "1",
      "text": "Hello world"
    },
    {
      "id": "2",
      "text": "Bonjour tout le monde"
    },
    {
      "id": "3",
      "text": "こんにちは世界"
    }
  ]
}
```

## 2. キーフレーズ抽出

文章のキーフレーズを抽出します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/keyPhrases
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "id": "1",
      "language": "en",
      "text": "Hello world! What a lovely day!"
    },
    {
      "id": "2",
      "language": "ja",
      "text": "こんにちは世界。今日はいい天気！"
    }
  ]
}
```


## 3. エンティティ抽出

一般的なエンティティ(→[リスト](https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/named-entity-types)) を抽出します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/entities/recognition/general
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "language": "ja",
      "id": "1",
      "text": "先月、京都に行ってきました"
    },
    {
      "language": "ja",
      "id": "2",
      "text": "私はマイクロソフトで働いている"
    }
  ]
}
```


## 4. エンティティの情報リンク検索

(※英語、スペイン語のみ)
文章に含まれるエンティティの情報リンク(wikiなど)を検索、提示します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/entities/linking
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "I had a wonderful trip to Seattle last week. I visited Space Needle 2 times."
    }
  ]
}
```


## 5. センチメント分析

文章に現れる感情を分析し、ポジティブ、ニュートラル、ネガティブのそれぞれの判定を行います。
1文ごと、および文章全体のセンチメントを判定します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.0/sentiment
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "language": "ja",
      "id": "1",
      "text": "明日から京都に旅行に行きます。久しぶりなので楽しみです"
    }
  ]
}
```


v3.1 preview では、Opinion (文章の"意見") 抽出およびセンチメント分析ができるようになっています。(※英語のみ)
[Microsoft Docs > How to: Sentiment analysis and Opinion Mining - Opinion Mining](https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-how-to-sentiment-analysis?tabs=version-3-1)


## 6. 個人情報エンティティ抽出

(※英語のみ)
文章に含まれる個人情報(名前、メールアドレス、住所、電話番号など)とその種類を判定し、その部分をマスキングした文章も提示します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.1-preview.3/entities/recognition/pii
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Please contact me at 09012345678"
    }
  ]
}
```


## 7. テキスト分析(バッチジョブ)

テキスト分析をジョブとして投入できるようになります。
[Submit analysis job](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/operations/Analyze) で分析したいドキュメントを Post し、発行される Job Id をパラメータとして [Get analysis status and results](https://eastus2.dev.cognitive.microsoft.com/docs/services/TextAnalytics-v3-1-preview-3/operations/AnalyzeStatus) で結果を取得します。

```
// Request URL
POST https://YOUR_TA_URL/text/analytics/v3.1-preview.3/analyze
// Header
Content-Type: application/json
Ocp-Apim-Subscription-Key: YOUR_SUB_KEY
// Body
{
    "analysisInput": {
        "documents": [
                {
                    "id": "doc1",
                    "text": "It's incredibly sunny outside! I'm so happy it's a beautiful day on my 20th birthday!"
                },
                {
                    "id": "doc2",
                    "text": "Pike place market is my favorite Seattle attraction."
                }
        ]
    },
    "tasks": {
        "entityRecognitionTasks": [
                {
                        "parameters": {
                                "model-version": "latest"
                        }
                }
        ],
        "keyPhraseExtractionTasks": [
                {
                        "parameters": {
                                "model-version": "latest"
                        }
                }
        ],
        "entityRecognitionPiiTasks": [
                {
                        "parameters": {
                                "model-version": "latest"
                        }
                }
        ]
    }
}
```


## 8. Healthcare Analysis

(※プレビュー申込が必要)
医療機関ドキュメント (カルテや投薬記録など) で利用される用語を検出、分析できるサービスです。
ただいまプレビュー提供であり、このサービスは専門家の判断に代わるものではなく、マイクロソフトは一切の責任を持たない旨、記載されています。

[Microsoft Docs > How to: Use Text Analytics for health (preview)](https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/how-tos/text-analytics-for-health?tabs=ner)

利用方法は 7 と同様に Job を投入して、結果を Job Id で引き出します。