Natural Language API の基本

api Cloud Natural Language API

このドキュメントでは、Cloud Natural Language API の基本的な使用方法について説明します。取り上げる内容は、Natural Language API に対するリクエストの種類、リクエストの作成方法、リクエストに対するレスポンスの処理方法です。Natural Language API を使用するすべてのユーザーに、実際に API を使用する前にこのガイドと関連チュートリアルを 1 つ読むことをおすすめします。

Natural Language の特長

Natural Language API には、テキストを分析したりアノテーションを付けたりするためのメソッドがいくつか用意されています。各レベルの分析から、言語理解のための貴重な情報が得られます。使用できるメソッドは次のとおりです。

  • 感情分析: 指定されたテキストを調べて、そのテキストの背景にある感情的な考え方を分析します。具体的には、執筆者の考え方がポジティブか、ネガティブか、ニュートラルかを判断します。感情分析を実行するには analyzeSentiment メソッドを使用します。

  • エンティティ分析: 指定されたテキストに既知のエンティティ(著名人、ランドマークなどの固有名詞、レストラン、競技場などの普通名詞)が含まれているかどうかを調べて、そのエンティティに関する情報を返します。エンティティ分析を行うには、analyzeEntities メソッドを使用します。

  • エンティティ感情分析: 指定されたテキストに既知のエンティティ(固有名詞や普通名詞)が含まれているかどうかを調べて、そのエンティティに関する情報を返し、そのテキスト内でのそのエンティティの感情的な考え方を分析します。具体的には、そのエンティティに対する執筆者の考え方がポジティブか、ネガティブか、ニュートラルかを判断します。エンティティ分析を行うには、analyzeEntitySentiment メソッドを使用します。

  • 構文解析: 言語情報を抽出し、指定されたテキストを一連の文とトークン(通常は単語の境界)に分解して、それらのトークンをさらに分析できるようにします。構文解析を行うには、analyzeSyntax メソッドを使用します。

  • コンテンツ分類: テキスト コンテンツを分析し、そのコンテンツのコンテンツ カテゴリを返します。コンテンツ分類を行うには、classifyText メソッドを使用します。

各 API 呼び出しでは、言語も検出されて返されます(最初のリクエストで呼び出し元によって指定されていない場合)。

さらに、指定したテキストに対して 1 回の API 呼び出しで複数の自然言語オペレーションを実行することもできます。annotateText リクエストを使用すると、感情分析とエンティティ分析を実行できます。

Natural Language の基本的なリクエスト

Natural Language API は REST API であり、JSON のリクエストとレスポンスで構成されます。Natural Language API の単純なエンティティ分析の JSON リクエストの例を以下に示します。

    {
      "document":{
        "type":"PLAIN_TEXT",
        "language": "EN",
        "content":"'Lawrence of Arabia' is a highly rated film biography about
                    British Lieutenant T. E. Lawrence. Peter O'Toole plays
                    Lawrence in the film."
      },
      "encodingType":"UTF8"
    }
    

各フィールドの内容は次のとおりです。

  • document には、このリクエストのデータが格納されます。これは、次のサブフィールドで構成されます。
    • type - ドキュメントの種類(HTML または PLAIN_TEXT
    • language - (省略可)リクエストに含まれているテキストの言語。指定しない場合、言語が自動的に検出されます。Natural Language API でサポートされる言語については、言語のサポートをご覧ください。サポートされていない言語を指定すると、JSON レスポンスでエラーが返されます。
    • content または gcsContentUri: 評価するテキストが含まれています。content を渡すと、そのテキストが直接 JSON リクエストに含まれます(上の例を参照)。gcsContentUri を渡す場合は、そのフィールドに Google Cloud Storage 内のテキスト コンテンツを表す URI が含まれている必要があります。
  • encodingType: (必須)返されるテキスト内の文字オフセットの計算に使用するエンコード スキーム。リクエストで渡すテキストのエンコードと一致している必要があります。このパラメータを設定しないと、リクエスト自体はエラーになりませんが、それらのオフセットがすべて -1 に設定されます。

テキスト コンテンツの指定

Natural Language API のリクエストを渡す際には、処理するテキストを次のいずれかの方法で指定します。

  • テキストを直接 content フィールドに含めて渡します。
  • Google Cloud Storage URI を gcsContentUri フィールドに含めて渡します。

いずれの場合も、コンテンツの制限を超えないようにする必要があります。コンテンツの制限は、文字単位ではなくバイト単位であることに注意してください。テキストのエンコードによって文字数が異なります。

以下のリクエストは、ゲティスバーグの演説が含まれている Google Cloud Storage ファイルを参照しています。

    {
      "document":{
        "type":"PLAIN_TEXT",
        "language": "EN",
        "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
      },
    }
    

感情分析

感情分析は、テキスト内で表現されている全体的な態度(ポジティブかネガティブか)を特定します。感情は、scoremagnitude の数値によって表されます。

感情分析のレスポンス フィールド

ゲティスバーグの演説に対する analyzeSentiment レスポンスの例を以下に示します。

    {
      "documentSentiment": {
        "score": 0.2,
        "magnitude": 3.6
      },
      "language": "en",
       "sentences": [
        {
          "text": {
            "content": "Four score and seven years ago our fathers brought forth
            on this continent a new nation, conceived in liberty and dedicated to
            the proposition that all men are created equal.",
            "beginOffset": 0
          },
          "sentiment": {
            "magnitude": 0.8,
            "score": 0.8
          }
        },
       ...
    }
    

各フィールドの値は次のとおりです。

  • documentSentiment には、次のフィールドで構成されるドキュメントの全体的な感情が含まれます。
    • score: -1.0(ネガティブ)~1.0(ポジティブ)のスコアで感情が表されます。これは、テキストの全体的な感情の傾向に相当します。
    • magnitude: 指定したテキストの全体的な感情の強度(ポジティブとネガティブの両方)が 0.0+inf の値で示されます。score と違って、magnitude は正規化されていないため、テキスト内で感情(ポジティブとネガティブの両方)が表現されるたびにテキストの magnitude の値が増加します。そのため、長いテキスト ブロックで値が高くなる傾向があります。
  • language にはドキュメントの言語が含まれています。最初のリクエストで言語を渡した場合はその言語が含まれ、渡さなかった場合は自動的に検出された言語が含まれます。
  • sentences には、元のドキュメントから抽出された文のリストが含まれています。リストには次のものが含まれます。
    • sentiment: 各文に関連付けられた文レベルの感情の値が格納されています。これには、上で説明した scoremagnitude の値が含まれます。

ゲティスバーグの演説に対するレスポンスでは、score の値が 0.2 になっています。これは、このドキュメントが感情的にややポジティブであることを示しています。一方、3.6 の値は、このドキュメントの短さ(1 段落ほど)を考えると、かなり感情的な値であるといえます。ゲティスバーグの演説の最初の文に、非常にポジティブな score0.8)が含まれていることに注目してください。

感情分析の値の解釈

ドキュメントの感情分析の score は、ドキュメントの全体的な感情を示します。ドキュメントの感情分析の magnitude は、そのドキュメントに感情的な内容がどのくらい含まれているかを示します。この値は、ドキュメントの長さに比例する傾向があります。

Natural Language API は、ドキュメント内のポジティブな感情とネガティブな感情の違いを示しますが、具体的なポジティブな感情とネガティブな感情を特定するものではありません。たとえば、「怒っている(angry)」と「悲しい(sad)」は両方ともネガティブな感情とみなされます。ただし、Natural Language API が「怒っている」とみなされるテキストまたは「悲しい」とみなされるテキストを分析する場合、レスポンスではテキストの感情が「悲しい」または「怒り」ではなくネガティブであることだけが示されます。

score の値がニュートラル(ほぼ 0.0)なドキュメントは、感情的でない場合もあれば、ポジティブとネガティブの両方の値が高いために互いに相殺されている混合的なドキュメントである場合もあります。通常、これらの場合に曖昧さを取り除くために、magnitude の値が使用できます。本当にニュートラルなドキュメントの magnitude の値は低くなりますが、混在的なドキュメントの magnitude の値は大きくなります。

ドキュメントを互いに比較する場合(特にドキュメントの長さが違う場合)は、magnitude の値を使用してスコアを調整する必要があります。この値は、感情的なコンテンツに関連する数量を測定する際に役立ちます。

次の表は、いくつかのサンプル値とその解釈の例を示しています。

感情 サンプル値
明らかにポジティブ* "score": 0.8, "magnitude": 3.0
明らかにネガティブ* "score": -0.6, "magnitude": 4.0
ニュートラル "score": 0.1, "magnitude": 0.0
混合 "score": 0.0, "magnitude": 4.0

* 「明らかにポジティブ」と「明らかにネガティブ」という感情は、ユースケースと顧客ごとに異なります。実際に使用するときは、上記のものとは異なる結果となることもあります。実際の例に適したしきい値を定義し、テストと結果の検証の後でそのしきい値を調整することをおすすめします。たとえば、スコアが 0.25 を超えたら「明らかにポジティブ」というようにしきい値を定義してから、データと結果を確認します。0.15~0.25 のスコアもポジティブと見なせることがわかった場合は、それに基づいてスコアしきい値を 0.15 に変更します。

エンティティ分析

エンティティ分析は、テキスト内のエンティティ(著名人、ランドマーク、日常的な物など、名前が付けられている「モノ」)に関する情報を提供します。

エンティティは、大きく 2 つに分類されます。固有のエンティティ(特定の人、場所など)に対応する固有名詞と、自然言語処理では「名詞類」とも呼ばれる普通名詞です。通常は、名詞が「エンティティ」になると考えて構いません。エンティティは、元のテキストに対するインデックス オフセットとして返されます。

エンティティ分析のリクエストでは、返されたオフセットを正しく解釈できるように、encodingType 引数を渡す必要があります。

エンティティ分析のレスポンス フィールド

エンティティ分析では、検出された一連のエンティティと、それらのエンティティに関連付けられたパラメータ(エンティティのタイプ、テキスト全体に対する関連性、テキスト内の位置など)が返されます。エンティティは、テキスト全体に対する関連性を表す salience スコアの高い順に返されます。

エンティティ リクエストに対する analyzeEntities レスポンスを以下に示します。

    {
      "entities": [
        {
          "name": "Lawrence of Arabia",
          "type": "WORK_OF_ART",
          "metadata": {
            "mid": "/m/0bx0l",
            "wikipedia_url": "http://en.wikipedia.org/wiki/Lawrence_ofArabia(film)"
          },
          "salience": 0.75222147,
          "mentions": [
            {
              "text": {
                "content": "Lawrence of Arabia",
                "beginOffset": 1
              },
              "type": "PROPER"
            },
            {
              "text": {
                "content": "film biography",
                "beginOffset": 39
              },
              "type": "COMMON"
            }
          ]
        },
        {
          "name": "T.E. Lawrence",
          "type": "PERSON",
          "metadata": {
            "mid": "/m/0bx5v",
            "wikipedia_url": "http://en.wikipedia.org/wiki/T._E._Lawrence"
          },
          "salience": 0.12430617,
          "mentions": [
            {
              "text": {
                "content": "T. E. Lawrence",
                "beginOffset": 94
              },
              "type": "PROPER"
            },
            {
              "text": {
                "content": "Lieutenant",
                "beginOffset": 83
              },
              "type": "COMMON"
            },
            {
              "text": {
                "content": "Lawrence",
                "beginOffset": 145
              },
              "type": "PROPER"
            }
          ]
        },
        {
          "name": "British",
          "type": "LOCATION",
          "metadata": {
            "mid": "/m/07ssc",
            "wikipedia_url": "http://en.wikipedia.org/wiki/United_Kingdom"
          },
          "salience": 0.078094982,
          "mentions": [
            {
              "text": {
                "content": "British",
                "beginOffset": 75
              },
              "type": "PROPER"
            }
          ]
        },
        {
          "name": "film",
          "type": "WORK_OF_ART",
          "metadata": {},
          "salience": 0.033808723,
          "mentions": [
            {
              "text": {
                "content": "film",
                "beginOffset": 161
              },
              "type": "COMMON"
            }
          ]
        },
        {
          "name": "Peter O'Toole",
          "type": "PERSON",
          "metadata": {
            "mid": "/m/0h0jz",
            "wikipedia_url": "http://en.wikipedia.org/wiki/Peter_O'Toole"
          },
          "salience": 0.011568651,
          "mentions": [
            {
              "text": {
                "content": "Peter O'Toole",
                "beginOffset": 110
              },
              "type": "PROPER"
            }
          ]
        }
      ],
      "language": "en"
    }
    

「Lawrence of Arabia」(映画)と「T.E. Lawrence」(人物)のエンティティが返されています。エンティティ分析は、この例の「Lawrence」のように類似したエンティティの曖昧さを取り除くのに便利です。

エンティティのパラメータを格納するために使用されるフィールドは次のとおりです。

  • type はエンティティのタイプを示します(たとえばエンティティが人物、場所、消費財など)。この情報は、エンティティを区別したり、曖昧さを取り除いたりするのに役立ちます。パターンを作成したり、情報を抽出したりするために使用することもできます。たとえば、type の値を使用すると、「Lawrence of Arabia」と「T.E. Lawrence」など、類似した名前を持つエンティティを区別できます。「Lawrence of Arabia」には WORK_OF_ART(映画)というタグが付けられ、「T.E. Lawrence」には PERSON(人物)というタグが付けられます(詳細については、エンティティ タイプをご覧ください。)

  • metadata にはエンティティのナレッジ リポジトリに関する参照元情報が格納されています。将来、追加のリポジトリが公開される可能性があります。このフィールドには次のサブフィールドが含まれる場合があります。

    • wikipedia_url: 存在する場合は、このエンティティに関連する Wikipedia の URL が格納されます。
    • mid: 存在する場合は、このエンティティの Google Knowledge Graph エントリに対応する MID(Machine-generated Identifier)が格納されます。mid の値は異なる言語間でも一意であるため、異なる言語のエンティティをまとめるために使用することもできます。これらの MID 値の調べ方については、Google Knowledge Graph Search API のドキュメントをご覧ください。

      返された mid 値のすべてを Google Knowledge Graph API での検査に使用できるわけではありません。mid はエンティティの一意識別子として使用できますが、エンティティに関する追加情報を参照するときは、この値に依存しないでください。

  • salience: ドキュメントのテキスト全体に対するこのエンティティの重要性または関連性を示します。情報の取得や要約の際にエンティティを優先するのに役立ちます。スコアが 0.0 に近いほど重要性が低くなり、1.0 に近いほど重要性が高くなります。

  • mentions: エンティティが記述されているテキスト内のオフセット位置を示します。テキスト内で映画のタイトルではなく人物の「Lawrence」に言及されている箇所をすべて見つける場合などに便利です。同じエンティティ「TE Lawrence」を参照する「Lawrence」などのエンティティ エイリアスのリストを収集するためにも mention を使用できます。エンティティの mention には PROPERCOMMONのどちらかになる可能性があります。たとえば、「Lawrence of Arabia」という固有名詞エンティティは、映画タイトルそのものとしての言及である場合と、普通名詞(T.E. Lawrence の「伝記映画」)としての言及である場合があります。

エンティティ感情分析

エンティティ感情分析とは、エンティティ分析と感情分析の両方を組み合わせたものであり、テキスト内でエンティティについて表現された感情(ポジティブかネガティブか)の特定を試みることです。エンティティ感情を表すには、数値のスコアと強度の値が使用され、そのエンティティについて言及されるたびに感情が特定されます。このスコアを集計して、そのエンティティの全体的な感情スコアと強度が計算されます。

エンティティ感情分析のリクエスト

エンティティ感情分析リクエストを Natural Language API に送信するには、analyzeEntitySentiment メソッドを次の形式で使用します。

    {
      "document":{
        "type":"PLAIN_TEXT",
        "content":"I love R&B music. Marvin Gaye is the best.
                   'What's Going On' is one of my favorite songs.
                   It was so sad when Marvin Gaye died."
      },
      "encodingType":"UTF8"
    }
    

リクエストでは、テキストの言語コードを content パラメータで特定しますが、オプションで language パラメータを指定できます。language パラメータを指定しない場合、Natural Language API によりリクエスト コンテンツの言語が自動的に検出されます。Natural Language API でサポートされる言語については、言語のサポートをご覧ください。

エンティティ感情分析のレスポンス

Natural Language API は、指定されたテキストを処理してエンティティを抽出し、感情を特定します。エンティティ感情分析リクエストに対して返されるレスポンスの内容は、ドキュメント コンテンツ内で見つかった entities、エンティティが言及されるたびの mentions エントリ、各言及の scoremagnitude の数値です。これらの値については、感情分析の値の解釈で説明しています。エンティティの全体的な scoremagnitude の値は、そのエンティティの言及ごとの scoremagnitude の値を集計したものです。エンティティの scoremagnitude の値は、0 になることもあります。テキスト内での感情が弱かった場合は magnitude が 0 になり、感情がどちらともいえなかった場合は score が 0 なります。

    {
      "entities": [
        {
          "name": "R&B music",
          "type": "WORK_OF_ART",
          "metadata": {},
          "salience": 0.5306305,
          "mentions": [
            {
              "text": {
                "content": "R&B music",
                "beginOffset": 7
              },
              "type": "COMMON",
              "sentiment": {
                "magnitude": 0.9,
                "score": 0.9
              }
            }
          ],
          "sentiment": {
            "magnitude": 0.9,
            "score": 0.9
          }
        },
        {
          "name": "Marvin Gaye",
          "type": "PERSON",
          "metadata": {
            "mid": "/m/012z8_",
            "wikipedia_url": "http://en.wikipedia.org/wiki/Marvin_Gaye"
          },
          "salience": 0.21584158,
          "mentions": [
            {
              "text": {
                "content": "Marvin Gaye",
                "beginOffset": 18
              },
              "type": "PROPER",
              "sentiment": {
                "magnitude": 0.4,
                "score": 0.4
              }
            },
            {
              "text": {
                "content": "Marvin Gaye",
                "beginOffset": 138
              },
              "type": "PROPER",
              "sentiment": {
                "magnitude": 0.2,
                "score": -0.2
              }
            }
          ],
          "sentiment": {
            "magnitude": 0.6,
            "score": 0.1
          }
        },
        ...
      ],
      "language": "en"
    }

    

例については、エンティティ感情分析をご覧ください。

構文解析

Natural Language API には、構文解析によってテキストを分析および解析するための強力なツールセットが用意されています。構文解析を実行するには analyzeSyntax メソッドを使用します。

構文解析は次のオペレーションで構成されています。

  • 文の抽出により、テキストのストリームが一連の文に分解されます。
  • トークン化により、テキストのストリームが一連のトークン(各トークンは通常 1 つの単語に対応)に分解されます。
  • トークンが処理され、文中の位置に基づいて構文情報が追加されます。

構文トークンセットの詳細については、形態論と依存関係ツリーガイドをご覧ください。

構文解析のリクエスト

Syntactic Analysis リクエストを Natural Language API に送信するには、analyzeSyntax メソッドを次の形式で使用します。

    {
      "document":{
        "type":"PLAIN_TEXT",
        "content":"Ask not what your country can do for you,
                   ask what you can do for your country."
      },
      "encodingType":"UTF8"
    }
    

構文解析のレスポンス

構文解析のリクエストを送信すると、指定したテキストが処理されて、文とトークンが抽出されます。Syntactic Analysis リクエストは、これらの sentencestokens を含むレスポンスを次の形式で返します。

    {
      "sentences": [
        ... Array of sentences with sentence information
      ],
      "tokens": [
        ... Array of tokens with token information
      ]
    }
    

文の抽出

Syntax Analysis を実行すると、Natural Language API は、指定されたテキストから抽出された文の配列を返します。各文は、text ペアレント内で次のフィールドを含みます。

  • beginOffset: 指定したテキスト内の文の開始位置を表す(0 から始まる)文字オフセットを示します。このオフセットは、リクエストで渡した encodingType を使用して計算されます。
  • content: 抽出された文の全文が含まれています。

たとえば、次の sentences 要素は、ゲティスバーグの演説の構文解析リクエストに対して返されたものです。

    {
      "sentences": [
        {
          "text": {
            "content": "Four score and seven years ago our fathers brought forth on
                        this continent a new nation, conceived in liberty and
                        dedicated to the proposition that all men are created
                        equal.",
            "beginOffset": 0
          }
        },
        {
          "text": {
            "content": "Now we are engaged in a great civil war, testing whether
                        that nation or any nation so conceived and so dedicated can
                        long endure.",
            "beginOffset": 175
          }
        },
    ...
    ...
        {
          "text": {
            "content": "It is rather for us to be here dedicated to the great task
                        remaining before us--that from these honored dead we take
                        increased devotion to that cause for which they gave the
                        last full measure of devotion--that we here highly resolve
                        that these dead shall not have died in vain, that this
                        nation under God shall have a new birth of freedom, and that
                        government of the people, by the people, for the people
                        shall not perish from the earth.",
            "beginOffset": 1002
          }
        }
      ],
      "language": "en"
    }
    

その他に、一連のトークンも返されます。各トークンに関連付けられた情報を使用して、返された文をさらに分析することができます。これらのトークンの詳細については、形態論と依存関係ツリーガイドをご覧ください。

トークン化

analyzeSyntax メソッドでは、テキストが一連のトークンに変換されます。これらのトークンは、リクエストで渡したコンテンツのさまざまなテキスト要素(単語の境界)に対応しています。Natural Language API がこの一連のトークンを生成するプロセスは、トークン化と呼ばれます。

トークンが抽出されると、それらのトークンが Natural Language API によって処理されて、品詞(形態論的情報を含む)と基本形の関連する部分が特定されます。さらに、トークンが評価されて依存関係ツリーに配置されます。依存関係ツリーによって、トークンの構文上の意味を特定できます。このツリーは、トークンどうしの関係や、トークンを含む文との関係も表します。これらのトークンに関連付けられている構文および形態論的情報は、Natural Language API 内の構文構造を理解するうえで役立ちます。

構文解析の JSON レスポンスで返されるトークン フィールドを以下に示します。

  • text: このトークンに関連付けられたテキストデータと、次の子フィールドが含まれています。

    • beginOffset: 指定したテキスト内の(0 から始まる)文字オフセットが含まれています。依存関係(後述)が存在するのは文中のみですが、トークンのオフセットはテキスト全体で位置付けられます。このオフセットは、渡された encodingType を使用して計算されます。
    • content: 元のテキストの実際の内容が含まれています。
  • partOfSpeech: トークンの文法情報を表します。これには、形態学的情報も含まれます。たとえば、トークンの時制、人称、数、性別などです(これらのフィールドの詳細については、形態と依存関係ツリーガイドをご覧ください)。

  • lemma: 単語が基づいている「root」単語が含まれているため、テキスト内で単語の使用を正規化できます。たとえば、「write」、「writing」、「wrote」、「written」はすべて同じ基本形(「write」)に基づいています。同様に、単語の単数形と複数形も同じ基本形に基づいています(「house」と「houses」など)。(詳細については、基本形(形態論)をご覧ください。)

  • dependencyEdge: トークンを含む文中の単語間の関係を有向木の辺によって識別します。この情報は、翻訳、情報の抽出、要約に役立ちます(形態論と依存関係ツリーガイドには、依存関係の解析に関する詳しい説明があります)。各 dependencyEdge フィールドには次の子フィールドが含まれています。

    • headTokenIndex: このトークンを含む文中の「親トークン」の(0 から始まる)インデックス値を提供します。親を持たないトークンでは自身のインデックスになります。
    • label: このトークンのヘッドトークンに対する依存関係のタイプを提供します。

フランクリン ルーズベルトの大統領就任演説の引用から生成されるトークンを以下に示します。

注: 値が *_UNKNOWNpartOfSpeech タグは、見やすくするためにすべて削除してあります。

     "tokens": [
        {
          "text": {
            "content": "The",
            "beginOffset": 4
          },
          "partOfSpeech": {
            "tag": "DET",
          },
          "dependencyEdge": {
            "headTokenIndex": 2,
            "label": "DET"
          },
          "lemma": "The"
        },
        {
          "text": {
            "content": "only",
            "beginOffset": 8
          },
          "partOfSpeech": {
            "tag": "ADJ",
          },
          "dependencyEdge": {
            "headTokenIndex": 2,
            "label": "AMOD"
          },
          "lemma": "only"
        },
        {
          "text": {
            "content": "thing",
            "beginOffset": 13
          },
          "partOfSpeech": {
            "tag": "NOUN",
            "number": "SINGULAR",
          },
          "dependencyEdge": {
            "headTokenIndex": 7,
            "label": "NSUBJ"
          },
          "lemma": "thing"
        },
        {
          "text": {
            "content": "we",
            "beginOffset": 19
          },
          "partOfSpeech": {
            "tag": "PRON",
            "case": "NOMINATIVE",
            "number": "PLURAL",
            "person": "FIRST",
          },
          "dependencyEdge": {
            "headTokenIndex": 4,
            "label": "NSUBJ"
          },
          "lemma": "we"
        },
        {
          "text": {
            "content": "have",
            "beginOffset": 22
          },
          "partOfSpeech": {
            "tag": "VERB",
            "mood": "INDICATIVE",
            "tense": "PRESENT",
          },
          "dependencyEdge": {
            "headTokenIndex": 2,
            "label": "RCMOD"
          },
          "lemma": "have"
        },
        {
          "text": {
            "content": "to",
            "beginOffset": 27
          },
          "partOfSpeech": {
            "tag": "PRT",
          },
          "dependencyEdge": {
            "headTokenIndex": 6,
            "label": "AUX"
          },
          "lemma": "to"
        },
        {
          "text": {
            "content": "fear",
            "beginOffset": 30
          },
          "partOfSpeech": {
            "tag": "VERB",
          },
          "dependencyEdge": {
            "headTokenIndex": 4,
            "label": "XCOMP"
          },
          "lemma": "fear"
        },
        {
          "text": {
            "content": "is",
            "beginOffset": 35
          },
          "partOfSpeech": {
            "tag": "VERB",
            "mood": "INDICATIVE",
            "number": "SINGULAR",
            "person": "THIRD",
            "tense": "PRESENT",
          },
          "dependencyEdge": {
            "headTokenIndex": 7,
            "label": "ROOT"
          },
          "lemma": "be"
        },
        {
          "text": {
            "content": "fear",
            "beginOffset": 38
          },
          "partOfSpeech": {
            "tag": "NOUN",
            "number": "SINGULAR",
          },
          "dependencyEdge": {
            "headTokenIndex": 7,
            "label": "ATTR"
          },
          "lemma": "fear"
        },
        {
          "text": {
            "content": "itself",
            "beginOffset": 43
          },
          "partOfSpeech": {
            "tag": "PRON",
            "case": "ACCUSATIVE",
            "gender": "NEUTER",
            "number": "SINGULAR",
            "person": "THIRD",
          },
          "dependencyEdge": {
            "headTokenIndex": 8,
            "label": "NN"
          },
          "lemma": "itself"
        },
        {
          "text": {
            "content": ".",
            "beginOffset": 49
          },
          "partOfSpeech": {
            "tag": "PRON",
            "case": "ACCUSATIVE",
            "gender": "NEUTER",
            "number": "SINGULAR",
            "person": "THIRD",
          },
          "dependencyEdge": {
            "headTokenIndex": 8,
            "label": "NN"
          },
          "lemma": "itself"
        },
        {
          "text": {
            "content": ".",
            "beginOffset": 49
          },
          "partOfSpeech": {
            "tag": "PUNCT",
          },
          "dependencyEdge": {
            "headTokenIndex": 7,
            "label": "P"
          },
          "lemma": "."
        }
      ],

    

コンテンツの分類

Natural Language API でドキュメントを分析し、ドキュメント内で見つかったテキストに適用されるコンテンツ カテゴリのリストを取得できます。ドキュメント内のコンテンツを分類するには、classifyText メソッドを呼び出します。

classifyText メソッドに対して返されるコンテンツ カテゴリの完全なリストについては、こちらをご覧ください。

Natural Language API は、classifyText メソッドによって返されたカテゴリをフィルタリングして、リクエストに最も関連性のあるカテゴリのみを残すようにします。たとえば、/Science/Science/Astronomy の両方がドキュメントに適用された場合は、より具体的な結果が得られるように /Science/Astronomy カテゴリのみが返されます。

Natural Language API によるコンテンツ分類の例については、コンテンツの分類をご覧ください。

単一のリクエストによる複数のオペレーションの実行

複数の Natural Language API オペレーションを単一のメソッド呼び出しで実行するには、annotateText を汎用の Natural Language API リクエストとして使用します。テキスト アノテーション JSON リクエストは、標準エンティティ分析リクエストに似ていますが、テキストに対して実行するオペレーションを示す一連の機能を追加で渡す必要があります。機能は以下のとおりです。

  • extractDocumentSentiment: 感情分析を実施します。詳細については、感情分析セクションをご覧ください。
  • extractEntities: エンティティ分析を実施します。詳細については、エンティティ分析セクションをご覧ください。
  • extractSyntax: 指定したテキストを処理して構文解析を実施するように指定します。詳細については、構文解析セクションをご覧ください。

次のリクエストは、短い文に features でアノテーションを付けて API を呼び出しています。

    {
      "document":{
        "type":"PLAIN_TEXT",
        "content":"The windy, cold weather was unbearable this winter."
      },
      "features":{
        "extractSyntax":true,
        "extractEntities":true,
        "extractDocumentSentiment":true
      },
      "encodingType":"UTF8"
    }