##この記事を読むと
・順番通り進めていくと、GoogleCloudAPI NaturalLanguageの「エンティティ分析」「感情分析」「公文・品詞解析」が実行できます。
・GoogleCloudAPI NaturalLanguage公式チュートリアルへの抵抗感が減ります
##この記事を書いた理由
「Google Cloud APIを使って感情分析したい」と思い立ったものの、APIを使うだけなので簡単そうに見えて意外と詰まりました。GoogleCloudPlatform公式日本語ドキュメントで、詳細な入門やチュートリアルが用意されているものの、独自の用語が多すぎて何を言っているのかさっぱりでした。
また、ストレスだったのが環境構築。後述しますが、別にローカルに環境構築をしなくてもブラウザから実行できるので、まずはそちらで試してみると良いかと思います。
さて、苦戦した折りに素晴らしい入門資料と出会いました。
本記事は基本的にこちらの資料の通りに書いています。実はこれもGoogle公式資料なんですよね。
（Google様・・・尊い・・・）
Codelab/Next17-Tokyo/「Natural Language API でエンティティと感情を分析する」
ただ、こちらの資料が2017年のものなので古い部分は適宜修正したり、省略されている部分を補ったりしています。
マークダウンで引用になっている箇所はそのままコピペです（手抜き）。そのうち自分の言葉で噛み砕いて置き換えます。
##環境
・Google Chrome
・Google Cloud Shell
（要はブラウザが開けるPCがあればOKです）
##準備
####Google Cloud Platform Consoleアカウントを作成(orログイン）
Google Cloud Platform Consoleを開き、自身のGoogleアカウントでログインします。
####プロジェクトを作成
Create projectもしくは新しいプロジェクトを作成をクリックしてプロジェクトを作成します。project-nameは任意の名前を入力してください。
ここでプロジェクトIDが発行されるので、メモしておいてください（後から確認することも可能です）。
プロジェクトができたら、Strat Cloud ShellでGoogleCloudConsoleを開いておきましょう。
####APIを有効化
画面右のメニュー⇨APIとサービスと開き、画面中央上の+ APIとサービスを有効化 をクリック。
languageなりnlpなりで検索して、Google Cloud Natural Language APIをenableにしてください。
ここで、Billing(支払い情報）の追加を求められることがありますが、画面の指示通りクレジットカードやデビットカードを追加してください。Cloud APIを使用するために必要なアカウント情報ですが、基本的に料金請求はされないので安心してください。
####APIキーを作成
APIとサービス ⇨ 認証情報と開き、認証情報を作成をクリック。
すると現れるメニューからAPIキーを選択します。生成されたAPIキーをコピー。
リクエストするたびにAPIキーの値を挿入しなくてすむように、生成したAPIキーを環境変数に保存しましょう。キーの保存はCloud Shellで行えます。
先ほどコピーしたAPIキーをAPI_KEY=?????に入れて、下記のコードを実行してください。
export 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コマンドを使って作成しましょう。
touch request.json
一応、ファイルが作成されているか確認しましょう。おなじみのlsコマンドを使ってディレクトリやファイルを表示してみます。
ls
request.json が作成されていますね。他に色々あるのはデフォルトなのでスルーでOKです。
次に、作成したファイルをコマンドラインエディターで開きます。vimでも何でも良いですが、下記が一番簡単かと思います。
edit request.json
自分の request.jsonファイルに以下を追加して、変更を保存します。
Macならcommand+Sですね。あるいはブラウザから操作するなら画面右上のFile⇨Saveとクリック。
{
"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 からファイルを送信する場合は、content を gcsContentUri に置き換えて、Google Cloud Storage 内のテキスト ファイルの uri の値を設定します。
####Natural Language API を呼び出す
ここからは、以下の curl コマンドを使用して、前の手順で保存しておいた API キー環境変数と一緒に、リクエスト本文を Natural Language API に渡します（すべてを 1 つのコマンドラインにします）。
curlはAPIを呼び出すときによく使われますね。
key=???? に自分のAPIキーを入れて、下記コードを実行します。
curl "https://language.googleapis.com/v1beta1/documents:analyzeEntities?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 で感情を分析する
エンティティの抽出以外にも、Natural Language API を使うとテキスト ブロックの感情分析を行えます。JSON リクエストには前述のリクエストと同じパラメーターが含まれますが、今回はテキストを変更して、より強い感情を持った内容にしてみましょう。ご自分の request.json ファイルを以下のものに置き換えてください。そして content をお好きなテキストに自由に置き換えてみてください。
{
"document":{
"type":"PLAIN_TEXT",
"content":"I love everything about Harry Potter. It's the greatest book ever written."
}
}
次に、リクエストを API の analyzeSentiment エンドポイントに送信します。command lineで下記を実行します。key=????にはAPIキーを入れてください。
curl "https://language.googleapis.com/v1beta1/documents:analyzeSentiment?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 を以下の内容に置き換えてください。
{
"document":{
"type":"PLAIN_TEXT",
"content":"Joanne Rowling is a British novelist, screenwriter and film producer."
},
"features":{
"extractSyntax":true
}
}
次に、API の annotateText メソッドを呼び出します。command lineで下記を実行します。key=????にはAPIキーを入れてください。
curl "https://language.googleapis.com/v1beta1/documents:annotateText?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 には、テキストの依存構文木の作成に使用できるデータが含まれています。本来この構文木は、文章中の単語が互いにどのような関係なのかを示す図です。上記の文章の依存構文木は以下のようになります。
注記：以下の Natural Language デモを使用すると、ブラウザでご自分の依存構文木を作成できます。https://cloud.google.com/natural-language/
上記のレスポンスの headTokenIndex は、「Joanne」を指す弧を持つトークンのインデックスです。この場合、文章内の各トークンを配列内の 1 単語と捉えることができ、「Joanne」に対する headTokenIndex の値 1 は、構文木でつながっている「Rowling」という単語を参照しています。NN（修飾語句 noun compound（名詞複合語）の略式表記）のラベルは、文章内でのその単語の役割を表しています。「Joanne」は、この文章の主語である「Rowling」を修飾しています。lemma（見出語）はこの単語の正規化形式です。たとえば、run、runs、ran、running という単語の lemma はすべて run になります。lemma の値は、ある単語が大きなテキスト全体をとおしてどれだけ出現するかを調べるのに役立ちます。
####終わりに
お疲れ様です！これで貴方もエンティティ分析や感情分析を使えるようになりました（実はかなりすごいことです）。
参考
人工知能特化型プログラミング学習サービスAidemy Premium Plan【Aidemy】
[自走できるAI人材になるための6ヶ月長期コース]https://px.a8.net/svt/ejp?a8mat=3NL3I3+2MNXYQ+4J9I+BWVTE)【キカガク】
現役シリコンバレーエンジニアが教えるPython 3 入門 + 応用 +アメリカのシリコンバレー流コードスタイル【Udemy】
Pythonによるビジネスに役立つWebスクレイピング（BeautifulSoup、Selenium、Requests）
【Udemy】
【世界で18万人が受講】実践 Python データサイエンス【Udemy】
【画像判定AIアプリ開発・パート1】TensorFlow・Python・Flaskで作る画像判定AIアプリ開発入門【Udemy】
【キカガク流】プログラミング力向上のためのPythonで学ぶアルゴリズム論（前編）
【Udemy】
Python 1年生 体験してわかる！会話でまなべる！プログラミングのしくみ
Python2年生 スクレイピングのしくみ 体験してわかる！会話でまなべる！
入門 Python 3
独学プログラマー Python言語の基本から仕事のやり方まで
人工知能プログラミングのための数学がわかる本
[第2版]Python 機械学習プログラミング 達人データサイエンティストによる理論と実践
Kaggleで勝つデータ分析の技術
スクレイピング・ハッキング・ラボ Pythonで自動化する未来型生活
