WatsonをPythonから使おう! -- Developer Cloud Python SDKの使い方

この記事は [IBM Cloud Advent Calendar 2020](https://qiita.com/advent-calendar/2020/ibmcloud) の 16 日目の記事です。

IBM CloudのAIサービス[Watson](https://www.ibm.com/jp-ja/watson)はRESTのAPIで呼び出し可能です。また[各種メジャーな言語でSDK](https://github.com/watson-developer-cloud)も利用できます。

当記事はPythonからSDKを利用してIBM Watsonのサービスを使う方法を説明します。なお当記事は以下のバージョンを元にテストしています：
v5.0.0

結構バージョンによって使い方が変わっているので、注意しましょう。

v5.0.0では以下のAPI呼び出しができます。

- assistant_v1
- assistant_v2
- compare_comply_v1
- discovery_v1
- discovery_v2
- language_translator_v3
- natural_language_classifier_v1
- natural_language_understanding_v1
- personality_insights_v3 (2020/12/1よりインスタンス作成不可, 2021/12/1サービス停止)
- speech_to_text_v1
- text_to_speech_v1
- tone_analyzer_v3
- visual_recognition_v3 (2021/1/7よりインスタンス作成不可, 2021/12/1サービス停止)
- visual_recognition_v4 (2021/1/7よりインスタンス作成不可, 2021/12/1サービス停止)


#0. 前提条件

- IBM Cloudアカウントを持っている
- サービスを作成済み(以下の例ではLanguage Translator)

  - やり方がよくわからない場合は[こちら](https://qiita.com/nishikyon/items/9b8f697db7ad0a693839)を参考にしてください


- python 3.5以上の実行環境がある

#1.前準備
作成したサービスのAPIKEYとURLを確認できるようにしておいてください。
やり方がよくわからない場合はこちらを参考にしてください:
[サービスの資格情報取得](https://qiita.com/nishikyon/items/9b8f697db7ad0a693839#2-%E3%82%B5%E3%83%BC%E3%83%93%E3%82%B9%E3%81%AE%E8%B3%87%E6%A0%BC%E6%83%85%E5%A0%B1%E5%8F%96%E5%BE%97)


#2. Watson SDKの使い方の基本
まずは言語に関係なく、一般的な使い方の調べ方をご紹介します。
各種メジャーな言語のSDKの使い方は、実はIBM Cloud上のAPIドキュメントにあります！

[API & SDK リファレンス・ライブラリー](https://cloud.ibm.com/docs?tab=api-docs)のカテゴリ[AI / Machine Learning](https://cloud.ibm.com/docs?tab=api-docs&category=ai)にあるものが、各サービスのAPI&SDKのドキュメントへのリンクです。

当記事では[Language Translator](https://cloud.ibm.com/catalog/services/language-translator)を例に説明しますので、[Language Translator](https://cloud.ibm.com/catalog/services/language-translator)のサービスを作成しておいてください。

##基本1: API & SDK リファレンス・ライブラリーから使用するサービスをクリック
今回は[Language Translator](https://cloud.ibm.com/catalog/services/language-translator)を使いますので、[API & SDK リファレンス・ライブラリーのカテゴリ　**AI / Machine Learning**](https://cloud.ibm.com/docs?tab=api-docs&category=ai) から　**Language Translator**をクリックします。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/a82b2e0b-d077-f65c-f843-55487d901568.png)

##基本2: 右側の「Curl Java Node Python Go」などと書いてあるタブから、自分の使いたい言語をクリック
今回はPythonですので、「Python」をクリックしてください。
ちなみに2020/12/15に確認したところ、Curl, Java, Node, Python, Go, .NET, Ruby, Swift, Unityがタブにありました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/87d56419-5b15-b952-95f0-dd362f89d6a4.png)

##基本3: 左側のメニューから使い方を知りたいSubjectをクリック。
例えば「Introduction」だったらpipでのインストール方法が載っています。コピペして実行すればよいですね。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/81bca3d5-8b9d-af61-b405-3a3afaaff877.png)

例えばMethod「Translate」だったら、選んだ言語の定義とサンプルコードが右側に表示されます。サンプルコードはコピペして、実行可能です。
ただし、`{apikey}`, `{url}`は自分のサービスのものに置き換える必要があるので注意しましょう。[1. 前準備](#1前準備)で準備したものに置き換えてください。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/f31e68a5-b344-5942-fb34-2fef0b1895f7.png)

#3. ではPythonから使おう!

「[2. Watson SDKの使い方の基本](#2-watson-sdkの使い方の基本)にのっているドキュメントって英語なんですけど、、、」と引いてしまった方のために、一通り使い方を説明します。
ただ細かいSDKの使用はやっぱりSDKリファレンスをみないとわからないので、感覚を掴んだら、ぜひSDKリファレンスで詳細を調べてみてください。Codeは共通語ですよね❤️

ここでは[Language Translator](https://cloud.ibm.com/catalog/services/language-translator)を例に説明します

#3.1 まずはライブラリのインストール
以下のpipコマンドでインストールできます。

```shell
pip install --upgrade ibm-watson
```

#3.2 インスタンスの作成
ほぼ[ここ](https://cloud.ibm.com/apidocs/language-translator?code=python#authentication)のサンプルコード（example code）のコピーです。

[ここ](https://cloud.ibm.com/apidocs/language-translator?code=python#authentication)のサンプルコードで例えば`'{apikey}'` と書かれていると、`'{xxxxxxxxx}'`(xxxxxxxxxは自分のapikey)とコードに書いてしまう方が、ハンズオンをやったりすると結構います。わかりにくいのですが、**{ }**は不要です。{apikey}ごと置き換えます。下記のコードは変数として最初に定義して**{ }**の記述は無くしました。


```py
APIKEY='自分のAPIKEYを入れる'
URL='自分のURLを入れる'
VERSION='2018-05-01' #使いたいVersionを入れてください

from ibm_watson import LanguageTranslatorV3
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator(APIKEY)
language_translator = LanguageTranslatorV3(
    version=VERSION,
    authenticator=authenticator
)

language_translator.set_service_url(URL)

```
上記のVERSIONは[APIドキュメント](https://cloud.ibm.com/apidocs/language-translator?code=python#versioning)の右側の「Versioning」をクリックすると、ドキュメントで想定しているVersionが記載されていますので、そちら値を使用するのがよいかと思います。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/9ddc802a-6700-aceb-93a2-d0a11aa19ce5.png)


#3.3 Methodの呼び出し

[Language Translator](https://cloud.ibm.com/catalog/services/language-translator)は翻訳サービスので、翻訳メソッド「Translate」を呼び出してみましょう。

呼び出し方法のMethod名、パラメータの内容などは[基本3: 左側のメニューから使い方を知りたいSubjectをクリック。](#基本3-左側のメニューから使い方を知りたいsubjectをクリック)に書いたように、[APIドキュメント](https://cloud.ibm.com/apidocs/language-translator?code=python#translate)の右側から知りたい内容をクリックすればサンプルコードと共に表示されます。

以下のコードを[3.2 インスタンスの作成](t#32-インスタンスの作成)のコードの次に書きましょう。
`model_id='en-es'`なので、英語(en)からスペイン語(es)への翻訳となります。

```py
translation = language_translator.translate(
    text='Hello, how are you today?',
    model_id='en-es').get_result()
```

language_translator.translate（）の戻り値にget_result()して何が戻ってくるかは[APIドキュメント](https://cloud.ibm.com/apidocs/language-translator?code=python#translate)の真ん中の列に書かれています。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/5660ee21-13dc-93bc-c9b7-9ed3beb1e760.png)

また戻り値全体の話は[APIドキュメント](https://cloud.ibm.com/apidocs/language-translator?code=python#response-details)の`Data Handling`→`Response details`に載っています。get_result()以外に、Header情報やHTTP　Status　Codeを取得することが可能です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/294516/5052e1bc-f66e-bf23-dbd0-39b5c0b13b93.png)

結果を表示してみましょう.インデントをつけて見やすく表示させています:

```py
import json

print(json.dumps(translation, indent=2, ensure_ascii=False))

```

表示されるもの:

```json
{
  "translations": [
    {
      "translation": "Hola, ¿cómo estás hoy?"
    }
  ],
  "word_count": 7,
  "character_count": 25
}
```

翻訳結果だけ欲しい場合は以下のように指定します(辞書型になります)：

```py
print (translation[ "translations"][0]["translation"])
```

表示されるもの:

```sh
Hola, ¿cómo estás hoy?
```

以上です。


#4. 最後に
使い方のポイントを抑えれば、APIドキュメントが英語でも簡単にCodeがかけると思いますので、ぜひ他のAPIでも試してみてください！