初心者がCOTOHAを使ってみました～②API動作～

#１．概要
前回[COTOHA APIの環境構築](https://qiita.com/momotar47279337/items/1b565e22af1fe6a190a9)を記載いたしました。今回は、各APIを動かしてどんな結果が返ってくるのかまとめたいと思います。（[COTOHA APIへのリンク](https://api.ce-cotoha.com/contents/index.html)）

また、今回例として以下の[JSTQB AL(テストマネージャー)のシラバス](http://jstqb.jp/dl/JSTQB-Syllabus.Advanced_TM_Version2012.J03.pdf)の一文を利用します。（シラバスのP.9に記載されている）

「たとえば、リスクベースドテスト戦略では、リスク分析を使用して、識別したプロダクトリスクの軽減とコンティンジェンシープランの支援を行うために必要な活動を軽減できるように、テスト計画作業プロセスをガイドすることができる。」

資格試験を勉強された方はわかると思いますが、テストマネージャーのシラバスは難しい文章が多いです…。
今回各APIを動作しながら、「わかりにくい文章をわかりやすくすることができるのか」、試してみたいと思います。
**※今回は上記目的に合わないAPIでも、まずは動かすところから始めたいと思います。**

■使用環境
OS：Windows10
プラウザ：Firefox（73.0.1）
アドオン：RESTClient（3.0.7）


#２．APIのリファレンス確認

APIのリファレンスを参照しながら各APIを動作させてみたいと思います。

まず、前回の内容からアクセストークンを発行します。その後、[以下ページ](https://api.ce-cotoha.com/contents/api-all.html)から利用するAPIの情報を確認します。（例では構文解析のAPIを参照しています）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/b7fde928-d3bb-0b4e-3561-c2acb4099085.png)

表示されたAPIの情報をもとに、送信するリクエストデータをRESTClientに入力します。
まず、以下「HTTPエンドポイント」から送信先となるAPIの情報を入力します。Mehtodは**「POST」**、URLにはアカウントホームに記載されている情報を参考に変換してください。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/c16926cc-ff93-283e-e482-a43181988c86.png)

　　　　　　　　　　　　　　↓↓↓↓↓↓↓↓↓↓↓↓↓↓

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/89d04a94-4d6e-7608-13b5-246cd15595e2.png)


　　　　　　　　　　　　　　↓↓↓↓↓↓↓↓↓↓↓↓↓↓

	[API Base URL]/nlp/v1/parse
	↓↓↓↓↓↓
	https://api.ce-cotoha.com/api/dev/nlp/v1/parse

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/ca00d996-e096-b087-95f7-0b4d61e23c2c.png)


次にheader情報を入力します。以下の「リクエストヘッダ」を参考に2つのデータを入力してください。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/ebf3f20d-6766-82e0-32df-b9127340ba09.png)

まず、画面上部のHeadersにある「Custom Header」を押下します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/65a1f3fe-bd4b-a286-a968-9da08f10afb4.png)

次に以下データを入力し、「Okay」ボタンを押下してください。
①Name：**「Content-Type」**、Attribute Value：**「application/json」**
（資料では「;charset=UTF-8」とありますが、こちらはつけてもつけなくてもどちらでもいいようです。）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/a171ce84-88d3-2120-81e0-8292957b912b.png)

入力後、以下のようにHeadersが追加され、「Content-Type:application/json」と表示されていれば成功です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/a97ccc26-7469-d944-6efe-5bf910282656.png)

続いて同じようにHeadersに以下データを入力してください。（アクセストークン）は、事前にアクセストークン取得APIを動作して、発行したデータを入力して下さい。その後「Okay」ボタンを押下します。
②Name：**「Authorization」**、Attribute Value：**「Bearer （アクセストークン）」**

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/ce313453-cc4f-6674-9470-43ddb336edf7.png)

成功すれば以下のように「Authorization: Bearer （アクセストークン）」と表示されます。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/4dd5f2d2-6f8a-9257-4745-7f2235218416.png)

次に以下「リクエストボディ」からBodyに記載するデータを作成します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/a2572eb4-37fc-5358-5ca0-05778e19b426.png)

上記情報から、必要な情報は「sentence」「type」「dic_type」の3つであることがわかります。また、そのうち「type」「dic_type」は任意（送っても送らなくてもいい）とありますので、一旦「sentence」のみ使用します。

こちらをBodyに記載すると、以下のようになります。

	{
	"sentence":"たとえば、リスクベースドテスト戦略では、リスク分析を使用して、識別したプロダクトリスクの軽減とコンティンジェンシープランの支援を行うために必要な活動を軽減できるように、テスト計画作業プロセスをガイドすることができる。"
	}


　　　　　　　　　　　　　　↓↓↓↓↓↓↓↓↓↓

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/51ecae61-2f38-f476-9194-790fc92f7d5c.png)


その後、画面右上の「SEND」ボタンを押下し、構文解析APIを動かします。
以下レスポンス結果となります（※長文のため、一部抜粋しています）

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/0009c7ee-8ade-3774-5c05-4a3fc1ee2cb4.png)

パット見た限り、この解析結果だけでは文章を簡単にできないと思います。ただ、この分析結果をそのほかのツール等に利用するとうまくいきそうな気がします。

#３．各APIの動作方法

リファレンスをまとめると、各APIを動作するのに必要な**最低限のデータ**は以下となっております。2章で作成したリクエストデータに対し、以下のBodyとURLに変更することで、各APIを動作することができます。

| API名 | Bodyに入力| URLに入力|
|:-:|:--|:--|
| 構文解析|{"sentence":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/parse|
|  固有表現抽出|{"sentence":"（解析したい文字）"}| https://api.ce-cotoha.com/api/dev/nlp/v1/ne|
|照応解析|{"document":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/coreference|
|キーワード抽出※1|{"document":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/keyword|
|類似度算出|{"s1":"（比較したい文章1）","s2":"（比較したい文章2）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/similarity|
|文タイプ判定|{"sentence":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/sentence_type|
|ユーザ属性推定(β)|{"document":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/beta/user_attribute|
|言い淀み除去(β)|{"text":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/beta/remove_filler|
|音声認識誤り検知(β)|{"sentence":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/beta/detect_misrecognition|
|感情分析|{"sentence":"（解析したい文字）"}|https://api.ce-cotoha.com/api/dev/nlp/v1/sentiment|
|要約(β)※2|{"document":"（解析したい文字）","sent_len":"（要約文数）"}|https://api.ce-cotoha.com/api/dev/nlp/beta/summary|

※1　キーワード抽出は解析するデータにキーワードが含まれていないと「500 Internal Server Error」が返却されます
※2　要約文数には1～100の数値を入力します

#４．実施結果のまとめ

「わかりにくい文章をわかりやすくすることができるのか」、という目的に対し各APIの実施結果をまとめると、以下のようになりました。
（詳細は5章を参照ください）

| API名 | 目的の達成度 | 理由 |
|:-:|:-:|:--|
|構文解析|  △|各構文解析した結果をそのほかのツール等でわかりやすくできるかも|
|固有表現抽出|〇|JSTQBの用語等を抽出しわかりやすく直せるかも|
|照応解析|△|指示詞や代名詞が文章内にあればわかりやすくできるかも|
|キーワード抽出|〇|JSTQBの用語等を抽出しわかりやすく直せるかも|
|類似度算出|✖|比較する文章がないので難しい|
|文タイプ判定|✖|目的に対してどう使えばいいかわからない…|
|ユーザ属性推定(β)|✖|目的に対してどう使えばいいかわからない…|
|言い淀み除去(β)|✖|文章の解析より音声解析向けのAPI|
|音声認識誤り検知(β)|✖|文章の解析より音声解析向けのAPI|
|感情分析|✖|文章の解析より音声解析向けのAPI|
|要約(β)|△|長い文章を入力してみて、どのくらいわかりやすくなるのか確認が必要|

以上の結果から、今後は以下2つの方法があると思っております。

**①「固有表現抽出」や「キーワード抽出」を使って、JSTQB独自の用語をわかりやすくする**
**②「構文解析」、「照応解析」、「要約(β)」を使って文章そのものをわかりやすくする**

次は、上記2つのどちらかを深堀してみようと思います。


#５．実施結果の詳細

各APIを動作した結果を以下に記載します。

<details><summary>固有表現抽出APIの動作結果</summary><div>

固有表現抽出APIは以下が実施できるとのこと。

>固有表現抽出APIは、入力として日本語で記述された文を受け取り、人名や地名、日付表現(時間、日付)、組織名、量的表現(金額、割合)、人工物の8種類の固有表現と、200種類以上のクラス数を持つ拡張固有表現を出力します。

以下実施結果になります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/f902e7c5-0b3e-a483-73fc-763cd561a48b.png)

リスクベースドテスト戦略とリスク分析の2つが抽出されました。JSTQBは独特の用語がありますので、その抽出＋変換に役立てるかもしれません。</div></details>

<details><summary>照応解析APIの動作結果</summary><div>

照応解析APIは以下が実施できるとのこと。
>照応解析APIは、入力として日本語で記述された複数の文からなるテキストを受け取り、テキスト中の「そこ」「それ」などの指示詞や「彼」「彼女」などの代名詞と対応する先行詞を抽出し、同一のものとしてまとめて出力します。

以下実施結果となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/379ac7c7-02be-f38d-5c18-427d50e89306.png)

今回の例文の中に「そこ」「それ」といった言葉がないため、文章が区切られただけで、特に解析されないままレスポンスとして帰ってきています。

別の長文を入れると、わかりやすくなるかもしれません。</div></details>



<details><summary>キーワード抽出APIの動作結果</summary><div>

キーワード抽出APIは以下が実施できるとのこと。
>キーワード抽出APIは、入力として日本語で記述された複数の文からなるテキストを受け取り、テキストに含まれる特徴的なフレーズ・単語をキーワードとして抽出します。
テキストから算出される特徴的スコアに基づいて、複数のフレーズ・単語が降順に出力されます。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/210df7e4-d38c-6d60-bb31-91b9a213aa60.png)

抽出されたキーワードは上から順に「軽減」「ガイド」「識別」「リスクベースドテスト戦略」「プロダクトリスク」となりました。もしかしたら、JSTQB独自の単語等を抽出でき、そのキーワードをわかりやすく変換する、といったことができるかもしれません。</div></details>


<details><summary>類似度算出抽出APIの動作結果</summary><div>

類似度算出抽出APIは以下が実施できるとのこと。
>類似度算出APIは、入力として日本語で記述されたテキストを2つ受け取り、テキスト間の意味的な類似度を算出・出力します。
類似度は0から1の定義域で出力され、1に近づくほどテキスト間の類似性が大きいことを示します。
テキストに含まれる単語の意味情報を用いて類似度を算出しているため、異なった単語を含むテキスト間の類似性も推定することができます。

一旦参照している文章の後に記載されている以下文章と比較させてみます。
「セキュリティに関して問題になりうる深刻な潜在的欠陥を多数識別した場合は、 セキュリティテストを開発して実行するために、膨大な工数を費やす」

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/afb4e453-07cd-170e-fa91-4c0c2b010075.png)

同じセキュリティに関する文章であるため、類似度が高く算出されています。別途わかりやすくした文章とシラバスの内容を比較することで、文章に誤りがないか比較できるかも…</div></details>

<details><summary>文タイプ判定APIの動作結果</summary><div>

文タイプ判定APIは以下が実施できるとのこと。
>文タイプ判定APIは、入力として日本語で記述された文を受け取り、文の法(叙述/疑問/命令)タイプと発話行為タイプを判定・出力します。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/eab38909-9d28-7ed5-5880-4196484df8fb.png)

declarative=叙述、information-providing=情報提供とのこと。どう使えばいいのかよくわかりません…</div></details>



<details><summary>ユーザ属性推定(β)APIの動作結果</summary><div>

ユーザ属性推定(β)APIは、以下が実施できるとのこと。
>ユーザ属性推定APIは、入力として日本語で記述された複数の文からなるテキストを受け取り、年代、性別、趣味、職業などの人物に関する属性を推定・出力します。
本APIはベータ版として提供させていただきます。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/80dd7878-a075-7847-43fe-602c48d7cf73.png)

年齢20～29歳、意外と若いです。こちらもどう使うべきよくわからないです…</div></details>



<details><summary>言い淀み除去(β)APIの動作結果</summary><div>

言い淀み除去(β)APIは、以下が実施できるとのこと。
>言い淀み除去APIは、音声認識処理後のテキストに対して、ユーザからの音声入力時に含まれる言い淀みを除去します。
本APIはベータ版として提供させていただきます。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/feed618c-3fc0-0fad-3e0e-4d8256d291cc.png)

音声データではないので、言い淀みがなく特に変化はありませんでした。</div></details>



<details><summary>音声認識誤り検知(β)APIの動作結果</summary><div>

音声認識誤り検知(β)APIは以下が実施できるとのこと。
>音声認識誤り検知APIは、音声認識処理後のテキストを受け取り、認識誤りが疑われる箇所をそのスコアと訂正例とともに出力します。入力文全体の誤り度合いについても数値化を行って出力します。
本APIはベータ版として提供させていただきます。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/11851e16-60e8-ac57-968b-95b61793bcf8.png)

音声ではなく文章をつかっているので「軽減」⇒「提言」などの誤訳が目立ちます。ここは、文章を変換するのにあまり向いていないと思います。</div></details>



<details><summary>感情分析APIの動作結果</summary><div>

感情分析APIは以下が実施できるとのこと。
>感情分析APIは、入力として日本語で記述されたテキストを受け取り、そのテキストの書き手の感情(ネガティブ・ポジティブ)を判定します。また、テキスト中に含まれる「喜ぶ」「驚く」「不安」「安心」といった15種類の感情を分類・認識して出力します。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/9040d834-d8de-da80-58f3-0b882a10cf2a.png)

「軽減できる」「必要な」という言葉から、ポジティブと評価されています。文章をわかりやすくするというより、会話を分析する際に使えそうです。</div></details>



<details><summary>要約(β)APIの動作結果</summary><div>

要約(β)APIは以下が実施できるとのこと。
>要約APIは、入力として日本語で記述された複数文で構成された文章を受け取り、これを文単位で重要度を算出し、スコアを付与します。そして、入力時に指定された要約文数に応じ、重要文を返します。
本APIはベータ版として提供させていただきます。

実施結果は以下となります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/547663/882e82da-13b1-a7fa-cebe-93b928437309.png)

どうやら一文だけでは、そのまま結果が返ってくるようです。今後、もう少し長文を含めて実験してみた方が良さそうです。</div></details>