Cloud Natural Language API を使うと、テキスト ブロックからエンティティを抽出して、感情分析や構文解析を行えます。

このコードラボでは、Natural Language API の 3 つのメソッドであるanalyzeEntitiesanalyzeSentiment、および annotateText を使用する方法について学びます。

学習すること

必要になるもの

チュートリアルの使用目的を教えてください

通読のみ 通読して、演習を行う

Google Cloud Platform の使用経験を教えてください

初心者 中級者 上級者

会議でのコードラボのセットアップ

全てのパソコンは Codelab のみの使用となります!

ログイン後https://kiosk.gcplab.me/next17-tokへアクセスしてください。

退出なさる時はログアウトを忘れずにお願いいたします。

講師は、セットアップ済みの既存のプロジェクトで一時アカウントをあなたと共有するので、課金の有効化や本コードラボの実行に伴うコストについては心配いりません。それらのアカウントはすべて、コードラボ終了直後に無効化されます。

ログインに使用する一時ユーザー名/パスワードを講師から受け取った後、Google Cloud Console にログインします。https://console.cloud.google.com/.

割り当てられたプロジェクト ID をメモしてください (上のスクリーンショットでは「next17-tok-xxxx」)。以降、本コードラボでは PROJECT_ID と呼びます。

Google Cloud Shell を起動する

Google Cloud はラップトップからリモートで操作できるため、本コードラボでは、Cloud で動作するコマンドライン環境である Google Cloud Shell を使用します。この Debian ベース仮想マシンには、必要なすべての開発ツール (docker、gcloud、kubectl など) がロードされています。それは、永続的な 5GB ホームディレクトリを提供し、Google Cloud で動作し、ネットワーク性能と認証を大幅に改善します。そのため、本コードラボに必要なものは、ブラウザのみです (本コードラボは Chromebook でも動作します)

Google Cloud Shell をアクティブにするには、開発者コンソールで右上のボタンをクリックするだけです (プロビジョニングと環境への接続には数分しかかかりません)。

クラウド シェルに接続すると、すでに認証済みであり、プロジェクトがすでに PROJECT_ID に設定されていることが分かります。

$ gcloud auth list
認定済みアカウント:
 - <myaccount>@<mydomain>.com (アクティブ)
$ gcloud config list project
[core]
project = <PROJECT_ID>

何かしらの理由でプロジェクトが設定されていない場合、次のコマンドを発行してください。

$ gcloud config set project <PROJECT_ID>

PROJECT_ID が分かりませんか?セットアップステップでどの ID を使用したかを確認するか、コンソール ダッシュボードで検索してください。

自分のペースで進める環境のセットアップ

まだ Google Account(Gmail または Google Apps)をお持ちでない場合は、アカウントを作成する必要があります。Google Cloud Platform Console(console.cloud.google.com)にサインインして、新規プロジェクトを作成します。

プロジェクト ID を覚えておいてください。この ID は、すべての Google Cloud プロジェクトに使用する一意の名前です(上記の名前は既に使用されているので、実際には使用できません)。

Google Cloud Platform の新規ユーザーには$300 相当の無料トライアルが付与されます。

画面の左上にあるメニューアイコンをクリックします。

ドロップダウンで [API Manager] を選択します。

[API を有効にする] をクリックします。

次に、検索ボックスで「language」を検索します。[Google Cloud Natural Language API] をクリックします。

[有効にする] をクリックして、Cloud Natural Language API を有効にします。

有効になるまで数秒待ちます。有効になると、以下のように表示されます。

Natural Language API には curl を使用してリクエストを送信します。そこで、リクエスト URL 内で渡すための API キーを生成する必要がでてきます。API キーを作成するために、プロジェクト ダッシュボードの [API Manager] セクションに移動します。

次に、[認証情報] タブを選択して、[認証情報を作成] をクリックします。

ドロップダウン メニューで [API キー] を選択します。

次に、生成されたキーをコピーします。このキーは、このコードラボの後半で必要になります。

これで API キーが手に入りました。リクエストするたびに API キーの値を挿入しなくてすむように、生成した API キーを環境変数に保存します。キーの保存は Cloud Shell で行えます。以下の <your_api_key> を、先ほどコピーしたキーに置き換えてください。

export API_KEY=<YOUR_API_KEY>

1 つ目の Natural Language API メソッドは 、analyzeEntities です。API はこのメソッドを使ってテキストからエンティティ(人物、場所、イベントなど)を抽出します。API のエンティティ分析を試すために、最近のニュース記事にあった以下のような文章を使用してみましょう。

LONDON — J. K. Rowling always said that the seventh Harry Potter book, "Harry Potter and the Deathly Hallows," would be the last in the series, and so far she has kept to her word.

Natural Language API へのリクエストは request.json ファイル内で作れます。最初に、このファイルを Cloud Shell で作成します。

touch request.json

次に、作成したファイルを任意のコマンドライン エディター(nanovimemacs)で開きます。ご自分の request.json ファイルに以下を追加します。

request.json

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"LONDON — J. K. Rowling always said that the seventh Harry Potter book, ‘Harry Potter and the Deathly Hallows,' would be the last in the series, and so far she has kept to her word."
  }
}

このリクエストの中で、これから送信しようとしているテキストを Natural Language API に伝えます。サポートされている type の値は PLAIN_TEXT または HTML です。コンテンツ内で、分析するために Natural Language API へ送信するテキストを渡します。Natural Language API は、テキスト処理用として Goolge Cloud Storage に保存されているファイルの送信もサポートしています。Google Cloud Storage からファイルを送信する場合は、contentgcsContentUri に置き換えて、Google Cloud Storage 内のテキスト ファイルの uri の値を設定します。

ここからは、以下の curl コマンドを使用して、前の手順で保存しておいた API キー環境変数と一緒に、リクエスト本文を Natural Language API に渡します(すべてを 1 つのコマンドラインにします)。

curl "https://language.googleapis.com/v1beta1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

レスポンスの開始は、以下のようになります。

{
  "entities": [
    {
      "name": "Rowling",
      "type": "PERSON",
      "metadata": {
        "wikipedia_url": "http://en.wikipedia.org/wiki/J._K._Rowling"
      },
      "salience": 0.56932539,
      "mentions": [
        {
          "text": {
            "content": "J. K.",
            "beginOffset": -1
          }
        },
        {
          "text": {
            "content": "Rowling",
            "beginOffset": -1
          }
        }
      ]
    },
    ...
  ]
}

レスポンスの中で、API が文章から 4 つのエンティティを検出したことがわかります。各エンティティについて、エンティティの type(タイプ)、関連する Wikipedia の URL(存在する場合)、salience(セイリエンス)、およびテキスト内でそのエンティティが出現した場所のインデックスが得られます。セイリエンスとは 0~1 の数値で、テキスト全体に対するそのエンティティの突出性を指しています。前述の文章では、「Rowling」が最も高い値を返しています。これは、彼女がこの文章の主語だからです。Natural Language API は別の方法で、言及された同じエンティティを認識することもできます。たとえば、「Rowling」と「J.K.Rowling」、そして「Joanne Kathleen Rowling」さえも、すべて Wikipedia の同じエントリーを指しています。

エンティティの抽出以外にも、Natural Language API を使うとテキスト ブロックの感情分析を行えます。JSON リクエストには前述のリクエストと同じパラメーターが含まれますが、今回はテキストを変更して、より強い感情を持った内容にしてみましょう。ご自分の request.json ファイルを以下のものに置き換えてください。そして content をお好きなテキストに自由に置き換えてみてください。

request.json

 {
  "document":{
    "type":"PLAIN_TEXT",
    "content":"I love everything about Harry Potter. It's the greatest book ever written."
  }
}

次に、リクエストを API の analyzeSentiment エンドポイントに送信します。

curl "https://language.googleapis.com/v1beta1/documents:analyzeSentiment?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

以下のようなレスポンスが返されます。

{
  "documentSentiment": {
    "polarity": 1,
    "magnitude": 1.8
  },
  "language": "en"
}

感情のメソッドは、polarity(極性)と magnitude(強度)という 2 つの値を返します。polarity は -1.0~1.0 の数値で、文がどれだけポジティブまたはネガティブかを示します。magnitude は 0~∞ の数値で、polarity とは無関係に、文中で表現されている感情の重みを表します。文の重みが大きいテキスト ブロックの長さが増せば、それだけ magnitude の値も高くなります。上記の文の polarity は 100 % ポジティブで、「love」や「greatest」、「ever」という単語が magnitude の値に関係しています。

ここからは、Natural Language API の 3 つ目のメソッドであるテキスト アノテーションを見てみましょう。テキストの言語的な詳細について踏み込んで調べます。annotateText は、テキストの感情的要素と構文的要素について、完全な詳細がわかる高度なメソッドです。API を使えば、テキストに含まれる各単語について、その単語の品詞(名詞、動詞、形容詞など)と、その単語が文内の他の単語とどのように関係しているのか(動詞の原形なのか、修飾語句なのか)がわかります。

シンプルな文章を使って試してみましょう。JSON リクエストは前述のものと似ていますが、ここでは features キーを加えます。このキーで、構文アノテーションを実行したいことを API に伝えます。ご自分の request.json を以下の内容に置き換えてください。

request.json

 {
  "document":{
    "type":"PLAIN_TEXT",
    "content":"Joanne Rowling is a British novelist, screenwriter and film producer."
  },
  "features":{
    "extractSyntax":true
  }
}

次に、API の annotateText メソッドを呼び出します。

curl "https://language.googleapis.com/v1beta1/documents:annotateText?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

レスポンスには、文章内の各トークンについて、以下のようなオブジェクトが返されます。

{
      "text": {
        "content": "Joanne",
        "beginOffset": -1
      },
      "partOfSpeech": {
        "tag": "NOUN"
      },
      "dependencyEdge": {
        "headTokenIndex": 1,
        "label": "NN"
      },
      "lemma": "Joanne"
}

レスポンスを詳しく見てみましょう。partOfSpeech からは、「Joanne」が名詞であることがわかります。dependencyEdge には、テキストの依存構文木の作成に使用できるデータが含まれています。本来この構文木は、文章中の単語が互いにどのような関係なのかを示す図です。上記の文章の依存構文木は以下のようになります。

上記のレスポンスの headTokenIndex は、「Joanne」を指す弧を持つトークンのインデックスです。この場合、文章内の各トークンを配列内の 1 単語と捉えることができ、「Joanne」に対する headTokenIndex の値 1 は、構文木でつながっている「Rowling」という単語を参照しています。NN(修飾語句 noun compound(名詞複合語)の略式表記)のラベルは、文章内でのその単語の役割を表しています。「Joanne」は、この文章の主語である「Rowling」を修飾しています。lemma(見出語)はこの単語の正規化形式です。たとえば、runrunsranrunning という単語の lemma はすべて run になります。lemma の値は、ある単語が大きなテキスト全体をとおしてどれだけ出現するかを調べるのに役立ちます。

Natural Language API は、スペイン語と日本語でのエンティティ分析および構文アノテーションもサポートしています。ここからは、日本語の文章を使って以下のエンティティ リクエストを試してみましょう。

request.json

{
  "document":{
    "type":"PLAIN_TEXT",
    "content":"日本のグーグルのオフィスは、東京の六本木ヒルズにあります"
  }
}

ここで、このテキストが何語であるか API に伝えないことに注意してください。API は自動的に言語を検出できます。次に、リクエストを analyzeEntities エンドポイントに送信します。

curl "https://language.googleapis.com/v1beta1/documents:analyzeEntities?key=${API_KEY}" \
  -s -X POST -H "Content-Type: application/json" --data-binary @request.json

以下のようなレスポンスが返ってきます。

{
  "entities": [
    {
      "name": "日本",
      "type": "LOCATION",
      "metadata": {
        "wikipedia_url": "http://ja.wikipedia.org/wiki/%E6%97%A5%E6%9C%AC"
      },
      "salience": 0,
      "mentions": [
        {
          "text": {
            "content": "日本",
            "beginOffset": -1
          }
        }
      ]
    },
    {
      "name": "東京",
      "type": "LOCATION",
      "metadata": {
        "wikipedia_url": "http://ja.wikipedia.org/wiki/%E6%9D%B1%E4%BA%AC"
      },
      "salience": 0,
      "mentions": [
        {
          "text": {
            "content": "東京",
            "beginOffset": -1
          }
        }
      ]
    },
    {
      "name": "六本木ヒルズ",
      "type": "LOCATION",
      "metadata": {
        "wikipedia_url": "http://ja.wikipedia.org/wiki/%E5%85%AD%E6%9C%AC%E6%9C%A8%E3%83%92%E3%83%AB%E3%82%BA"
      },
      "salience": 0,
      "mentions": [
        {
          "text": {
            "content": "六本木ヒルズ",
            "beginOffset": -1
          }
        }
      ]
    }
  ],
  "language": "ja"
}

驚くことに、wikipedia_url は Wikipedia の日本語のページを指しています。

このコードラボでは、エンティティの抽出、感情の分析、および構文アノテーションの実行によって、Cloud Natural Language API でテキスト分析をする方法を学びました。

学習したこと

次のステップ