クイック スタート:Python REST API を使用して Text Analytics Cognitive Service を呼び出すQuickstart: Using the Python REST API to call the Text Analytics Cognitive Service

このクイックスタートを使用して、Text Analytics REST API および Python を使用した言語の分析を開始します。Use this quickstart to begin analyzing language with the Text Analytics REST API and Python. この記事では、言語の検出感情分析キー フレーズの抽出、およびリンクされているエンティティの識別を行う方法について説明します。This article shows you how to detect language, analyze sentiment, extract key phrases, and identify linked entities.

ヒント

API の詳細な技術ドキュメントについて、および実際の動作を確認するには、次のリンクを使用してください。For detailed API technical documentation and to see it in action, use the following links. また、組み込みの API テスト コンソールから POST 要求を送信することもできます。You can also send POST requests from the built-in API test console. セットアップは必要ありません。リソース キーと JSON ドキュメントを要求に貼り付けるだけです。No setup is required, simply paste your resource key and JSON documents into the request:

前提条件Prerequisites

  • Python 3.xPython 3.x

  • Python の要求ライブラリThe Python requests library

    このコマンドでライブラリをインストールできます。You can install the library with this command:

    pip install --upgrade requests
    

Text Analytics リソースのキーとエンドポイント。A key and endpoint for a Text Analytics resource. Azure Cognitive Services は、ユーザーがサブスクライブする Azure リソースによって表されます。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:

新しい Python アプリケーションを作成するCreate a new Python application

お気に入りのエディターまたは IDE で、新しい Python アプリケーションを作成します。Create a new Python application in your favorite editor or IDE. 以下のインポートをご使用のファイルに追加します。Add the following imports to your file.

import requests
# pprint is used to format the JSON response
from pprint import pprint

リソースの Azure エンドポイントとサブスクリプション キー用の変数を作成します。Create variables for your resource's Azure endpoint and subscription key.

import os

subscription_key = "<paste-your-text-analytics-key-here>"
endpoint = "<paste-your-text-analytics-endpoint-here>"

以降のセクションでは、API の各機能を呼び出す方法について説明します。The following sections describe how to call each of the API's features.

言語を検出するDetect languages

Text Analytics ベース エンドポイントに /text/analytics/v2.1/languages を追加して、言語検出 URL を形成します。Append /text/analytics/v2.1/languages to the Text Analytics base endpoint to form the language detection URL. 例: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/languagesFor example: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/languages

language_api_url = endpoint + "/text/analytics/v2.1/languages"

API に対するペイロードは、id 属性と text 属性を含むタプルである documents の一覧で構成されます。The payload to the API consists of a list of documents, which are tuples containing an id and a text attribute. text 属性には、分析対象のテキストが格納され、id には任意の値を指定できます。The text attribute stores the text to be analyzed, and the id can be any value.

documents = {"documents": [
    {"id": "1", "text": "This is a document written in English."},
    {"id": "2", "text": "Este es un document escrito en Español."},
    {"id": "3", "text": "这是一个用中文写的文件"}
]}

要求ライブラリを使用して、ドキュメントを API に送信します。Use the Requests library to send the documents to the API. Ocp-Apim-Subscription-Key ヘッダーにサブスクリプション キーを追加し、requests.post() を使用して要求を送信します。Add your subscription key to the Ocp-Apim-Subscription-Key header, and send the request with requests.post().

headers = {"Ocp-Apim-Subscription-Key": subscription_key}
response = requests.post(language_api_url, headers=headers, json=documents)
languages = response.json()
pprint(languages)

OutputOutput

{
"documents":[
    {
        "detectedLanguages":[
        {
            "iso6391Name":"en",
            "name":"English",
            "score":1.0
        }
        ],
        "id":"1"
    },
    {
        "detectedLanguages":[
        {
            "iso6391Name":"es",
            "name":"Spanish",
            "score":1.0
        }
        ],
        "id":"2"
    },
    {
        "detectedLanguages":[
        {
            "iso6391Name":"zh_chs",
            "name":"Chinese_Simplified",
            "score":1.0
        }
        ],
        "id":"3"
    }
],
"errors":[]
}

感情を分析するAnalyze sentiment

一連のドキュメントのセンチメント (正または負の範囲) を検出するには、Text Analytics ベース エンドポイントに /text/analytics/v2.1/sentiment を追加して言語検出 URL を形成します。To detect the sentiment (which ranges between positive or negative) of a set of documents, append /text/analytics/v2.1/sentiment to the Text Analytics base endpoint to form the language detection URL. 例: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/sentimentFor example: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/sentiment

sentiment_url = endpoint + "/text/analytics/v2.1/sentiment"

言語検出の例に示すように、サービスには、ドキュメントの一覧で構成された documents キーを使用してディクショナリを作成します。As with the language detection example, create a dictionary with a documents key that consists of a list of documents. 各ドキュメントは、id、分析対象の text、およびテキストの language で構成されるタプルです。Each document is a tuple consisting of the id, the text to be analyzed and the language of the text.

documents = {"documents": [
    {"id": "1", "language": "en",
        "text": "I had a wonderful experience! The rooms were wonderful and the staff was helpful."},
    {"id": "2", "language": "en",
        "text": "I had a terrible time at the hotel. The staff was rude and the food was awful."},
    {"id": "3", "language": "es",
        "text": "Los caminos que llevan hasta Monte Rainier son espectaculares y hermosos."},
    {"id": "4", "language": "es",
     "text": "La carretera estaba atascada. Había mucho tráfico el día de ayer."}
]}

要求ライブラリを使用して、ドキュメントを API に送信します。Use the Requests library to send the documents to the API. Ocp-Apim-Subscription-Key ヘッダーにサブスクリプション キーを追加し、requests.post() を使用して要求を送信します。Add your subscription key to the Ocp-Apim-Subscription-Key header, and send the request with requests.post().

headers = {"Ocp-Apim-Subscription-Key": subscription_key}
response = requests.post(sentiment_url, headers=headers, json=documents)
sentiments = response.json()
pprint(sentiments)

OutputOutput

ドキュメントのセンチメント スコアは 0.0 と 1.0 の間であり、高いスコアは肯定的なセンチメントを示します。The sentiment score for a document is between 0.0 and 1.0, with a higher score indicating a more positive sentiment.

{
  "documents":[
    {
      "id":"1",
      "score":0.9708490371704102
    },
    {
      "id":"2",
      "score":0.0019068121910095215
    },
    {
      "id":"3",
      "score":0.7456425428390503
    },
    {
      "id":"4",
      "score":0.334433376789093
    }
  ],
  "errors":[]
}

キー フレーズを抽出するExtract key phrases

一連のドキュメントからキー フレーズを抽出するには、Text Analytics ベース エンドポイントに /text/analytics/v2.1/keyPhrases を追加して言語検出 URL を形成します。To extract the key phrases from a set of documents, append /text/analytics/v2.1/keyPhrases to the Text Analytics base endpoint to form the language detection URL. 例: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/keyPhrasesFor example: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/keyPhrases

keyphrase_url = endpoint + "/text/analytics/v2.1/keyphrases"

このドキュメントのコレクションは、感情分析の例で使用したものと同じです。This collection of documents is the same used for the sentiment analysis example.

documents = {"documents": [
    {"id": "1", "language": "en",
        "text": "I had a wonderful experience! The rooms were wonderful and the staff was helpful."},
    {"id": "2", "language": "en",
        "text": "I had a terrible time at the hotel. The staff was rude and the food was awful."},
    {"id": "3", "language": "es",
        "text": "Los caminos que llevan hasta Monte Rainier son espectaculares y hermosos."},
    {"id": "4", "language": "es",
     "text": "La carretera estaba atascada. Había mucho tráfico el día de ayer."}
]}

要求ライブラリを使用して、ドキュメントを API に送信します。Use the Requests library to send the documents to the API. Ocp-Apim-Subscription-Key ヘッダーにサブスクリプション キーを追加し、requests.post() を使用して要求を送信します。Add your subscription key to the Ocp-Apim-Subscription-Key header, and send the request with requests.post().

headers = {"Ocp-Apim-Subscription-Key": subscription_key}
response = requests.post(keyphrase_url, headers=headers, json=documents)
key_phrases = response.json()
pprint(key_phrases)

OutputOutput

{
  "documents":[
    {
      "keyPhrases":[
        "wonderful experience",
        "staff",
        "rooms"
      ],
      "id":"1"
    },
    {
      "keyPhrases":[
        "food",
        "terrible time",
        "hotel",
        "staff"
      ],
      "id":"2"
    },
    {
      "keyPhrases":[
        "Monte Rainier",
        "caminos"
      ],
      "id":"3"
    },
    {
      "keyPhrases":[
        "carretera",
        "tráfico",
        "día"
      ],
      "id":"4"
    }
  ],
  "errors":[]
}

エンティティの識別Identify Entities

テキスト ドキュメント内の既知のエンティティ (人、場所、物) を特定するには、Text Analytics ベース エンドポイントに /text/analytics/v2.1/entities を追加して言語検出 URL を形成します。To identify well-known entities (people, places, and things) in text documents, append /text/analytics/v2.1/entities to the Text Analytics base endpoint to form the language detection URL. 例: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/entitiesFor example: https://<your-custom-subdomain>.cognitiveservices.azure.com/text/analytics/v2.1/entities

entities_url = endpoint + "/text/analytics/v2.1/entities"

前の例と同様に、ドキュメントのコレクションを作成します。Create a collection of documents, like in the previous examples.

documents = {"documents": [
    {"id": "1", "text": "Microsoft was founded by Bill Gates and Paul Allen on April 4, 1975, to develop and sell BASIC interpreters for the Altair 8800."}
]}

要求ライブラリを使用して、ドキュメントを API に送信します。Use the Requests library to send the documents to the API. Ocp-Apim-Subscription-Key ヘッダーにサブスクリプション キーを追加し、requests.post() を使用して要求を送信します。Add your subscription key to the Ocp-Apim-Subscription-Key header, and send the request with requests.post().

headers = {"Ocp-Apim-Subscription-Key": subscription_key}
response = requests.post(entities_url, headers=headers, json=documents)
entities = response.json()
pprint(entities)

OutputOutput

{
   "documents" : [
      {
         "id" : "1",
         "entities" : [
            {
               "name" : "Microsoft",
               "matches" : [
                  {
                     "wikipediaScore" : 0.49897989655674446,
                     "entityTypeScore" : 1.0,
                     "text" : "Microsoft",
                     "offset" : 0,
                     "length" : 9
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "Microsoft",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/Microsoft",
               "bingId" : "a093e9b9-90f5-a3d5-c4b8-5855e1b01f85",
               "type" : "Organization"
            },
            {
               "name" : "Bill Gates",
               "matches" : [
                  {
                     "wikipediaScore" : 0.58357497243368983,
                     "entityTypeScore" : 0.999847412109375,
                     "text" : "Bill Gates",
                     "offset" : 25,
                     "length" : 10
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "Bill Gates",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/Bill_Gates",
               "bingId" : "0d47c987-0042-5576-15e8-97af601614fa",
               "type" : "Person"
            },
            {
               "name" : "Paul Allen",
               "matches" : [
                  {
                     "wikipediaScore" : 0.52977533244176866,
                     "entityTypeScore" : 0.99884098768234253,
                     "text" : "Paul Allen",
                     "offset" : 40,
                     "length" : 10
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "Paul Allen",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/Paul_Allen",
               "bingId" : "df2c4376-9923-6a54-893f-2ee5a5badbc7",
               "type" : "Person"
            },
            {
               "name" : "April 4",
               "matches" : [
                  {
                     "wikipediaScore" : 0.37220990924571939,
                     "entityTypeScore" : 0.8,
                     "text" : "April 4",
                     "offset" : 54,
                     "length" : 7
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "April 4",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/April_4",
               "bingId" : "52535f87-235e-b513-54fe-c03e4233ac6e",
               "type" : "Other"
            },
            {
               "name" : "April 4, 1975",
               "matches" : [
                  {
                     "entityTypeScore" : 0.8,
                     "text" : "April 4, 1975",
                     "offset" : 54,
                     "length" : 13
                  }
               ],
               "type" : "DateTime",
               "subType" : "Date"
            },
            {
               "name" : "BASIC",
               "matches" : [
                  {
                     "wikipediaScore" : 0.35686239324548041,
                     "entityTypeScore" : 0.8,
                     "text" : "BASIC",
                     "offset" : 89,
                     "length" : 5
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "BASIC",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/BASIC",
               "bingId" : "5b16443d-501c-58f3-352e-611bbe75aa6e",
               "type" : "Other"
            },
            {
               "name" : "Altair 8800",
               "matches" : [
                  {
                     "wikipediaScore" : 0.868324676465041,
                     "entityTypeScore" : 0.8,
                     "text" : "Altair 8800",
                     "offset" : 116,
                     "length" : 11
                  }
               ],
               "wikipediaLanguage" : "en",
               "wikipediaId" : "Altair 8800",
               "wikipediaUrl" : "https://en.wikipedia.org/wiki/Altair_8800",
               "bingId" : "7216c654-3779-68a2-c7b7-12ff3dad5606",
               "type" : "Other"
            },
            {
               "name" : "Altair",
               "matches" : [
                  {
                     "entityTypeScore" : 0.52505272626876831,
                     "text" : "Altair",
                     "offset" : 116,
                     "length" : 6
                  }
               ],
               "type" : "Organization"
            },
            {
               "name" : "8800",
               "matches" : [
                  {
                     "entityTypeScore" : 0.8,
                     "text" : "8800",
                     "offset" : 123,
                     "length" : 4
                  }
               ],
               "type" : "Quantity",
               "subType" : "Number"
            }
         ]
      }
   ],
   "errors" : []
}

次のステップNext steps

参照See also

Text Analytics の概要Text Analytics overview
よく寄せられる質問 (FAQ)Frequently asked questions (FAQ)