Cognitive Servicesの各種APIをコールする際、認証が必要となります。認証に必要なAPIのキーの取得からC#による認証処理のお話です。
認証方法はAPIによって異なります。
今回は、https://api.cognitive.microsoft.com/sts/v1.0/issueTokenから認証のためのトークンを取得する方法です。
現時点で利用しているAPIは以下などがあります。
その他の使いたAPIの認証方法は、事前にCognitive Services | Microsoft Azureの API Reference をみて確認しましょう。
Overview
今回まとめたのは以下です。
実装はC#でしています。RESTでOAuthの認証するだけなので、概要が理解できればHTTPが使えるプログラミング言語ならどれでも実装ができると思っています。
（開発環境について、今回は、Visual Studio 2015 Update3、.NET Framework4.6.1で実装しています。）
1. Azure PortalでAPIのリソースを作成
https://portal.azure.com/ にアクセスします。
余談ですが、Azureを新たに使う人向けの情報となりますが、
Azureでは「リソースグループ」という概念があり、複数のリソースをグループ化することができます。検証とかでAppServicesとかSQL Databaseの複数のリソースを使う場合、一括で管理でき、削除もリソースグループごと削除できて便利です。必須ではないですが利用することをお勧めします♪
リソースグループの作成
ポータルの左側でリソースグループのアイコンをクリックし、追加をクリックしてリソースグループを作ります。
（API作成時にリソースグループを新規作成することもできますが、あえてリソースグループを先に作る流れをとります♪）
適当にリソースグループ名を適当につけ（今回は「CogbotDemo」とつけました）作成します。 個人的にですが、リージョンは東日本が混んでいるのでいつも西日本で作っています。
リソースグループの作成は数秒でできます。リソースグループの一覧から作成したリソースグループ「CogbotDemo」を選択し、追加をクリックします。
作成するリソースの選択画面になります。
Cognitive ServicesのAPIリソースの作成
検索バーに「cognitive」と入力して検索しましょう。「Cognitive Services APIs (プレビュー)」が今回作るものになります。
（ここら辺の名前はちょいちょい変わりそうな気もしますね....）
作成ボタンをクリックします。
リソースを作成していきましょう。リソースはAPIごとに作成する必要があります。今回は、テキストの機械翻訳API「Text Translator API」のリソースを作成してみます。
Account name
リソースの名前を適当に決めます。今回は「TextTranslatortApiDemo」としました。API type
利用するCognitve ServicesのAPIを選択します。今回は、「Translator Text API」（テキストの機械翻訳のAPI）を選択しています。価格レベル
価格レベルの選択です。今回は開発用に無料のプランを選んでいます。「価格の詳細を表示」をクリックすると価格プランの一覧が表示され、選択することができます。Resource group 自動で先ほど作成したのが選択されていると思います。ここで改めて新規作成したり、既存のリソースグループを選択することができます。
画面下部の作成をクリックすると、リソースが作成されます。
キーの取得
最初に作ったリソースグループ「CogbotDemo」で「TextTranslatorDemo」を探してみましょう。
全てのリソースから探してもいいんですが、個人的にはいつもリソースグループ単位でみるようにしてます。
（指定のリソースグループにリソースが作成されていて、リソースグループを削除すればキレイに削除されるってのを確認をするためです....）
作成した「TextTranslatorDemo」をクリックします。
（ない場合は、画面上部の更新をクリックすると表示されます。）
Keysをクリックすると、キーが表示されます。コピーのボタンをクリックするとキーをクリップボードにコピーすることができます。
このキーを使ってこのあとOAuthのトークンを取得します。
2. Cognitive ServicesのサイトでAPIを試してみる
Cognitive ServicesのAPIのドキュメントでAPIをコールして試すことができます。アプリの実装より、まずAPIを叩いて試してみたい方にはうってつけですね。
そこでもやはり認証は必要となります。その方法を紹介します。
API References でトークンの取得
まず、API Referencesのトークンを取得する用サイトに行きます。
Cognitive Services - OAuth Token
画面を下にスクロールすると、APIを叩けるところが表示されます。Ocp-Apim-Subscription-Keyに先ほど作成したキーを入力し、Try it outボタンをクリックしましょう。
キーに問題がなければ、Response Codeの値が「200」で返ってきます。400番代であれば、キーがおかしいです。
Response Bodyにトークンが入っています。このトークンをコピーしましょう。
Text Translation API を試す
Text Translation の API References で試してみましょう。
Cognitive Services - Microsoft Translator Text API
API Referencesで画面を下にスクロールし、「Translate」というAPIをクリックしてみましょう。
以下のように必要なパラメーターを入力します。
appid（必須）
先ほど取得したトークンの先頭に「Bearer 」（Bearerの後に半角スペースが入ります）と付け加え、値を入力します。text（必須）
翻訳するテキストを入力します。今回は、「Translator API is usefull.」と入力しました。from
翻訳するテキストの言語を入力します。入力しない場合は、自動で検出されます。to（必須）
翻訳する言語を入力します。今回は日本語「ja」を入力します。
言語と言語コードが取得できるAPI（こちら）の「GET /languages」というAPIの「Try it out」ボタンをクリックすると、言語コードの一覧を確認することができます。category
今回は「generalnn」と入力します。これは、ディープラーニングバージョンの機械翻訳をするときのパラメーターです。
Try it outボタンをクリックすると、結果が返ってきます。
Response Codeで「200」が返ってきていることと、Response Bodyに翻訳結果が返ってきていることが確認できます。
このような流れでほかの各種APIも試すことができます。便利ですね♪
3. 認証処理の実装（C#）
上記の流れをC#で実装するだけの話となります。
APIをコールするまでの実装イメージは、先ほど試したことを実装するだけなので、
流れです。
C#でトークンの取得
コードをざっくりと。
外部から、21行目のメソッドを読んであげるだけでベアラートークンが取得できる、外部のクラスはそれ以外知らなくていい！という作りにしています。
Azure Portalから取得したキーは、APIごとに変わるので引数でもらいます。
30行目の部分ですが、RequestHeaderに、Ocp-Apim-Subscription-Keyの値にAzure Portalから取得したキーをセットして、POSTするとトークンが取得できます。
21行目のメソッドで、メソッド名の通り"Bearer "を先頭につけて返しています。
トークンが取れれば、実際にコールするAPIに対して、リクエストヘッダーにトークンをセットしてあげればよいですね。 ざっくりなサンプルだと、以前の記事の「3. Bing Speech APIと連携」の部分でコードを紹介しています。ご参考にしていただければと。
コードに関する余談
コード内でTODOに残しているところについては、このクラスの使い方次第だと思っているので書いてません。
以前に書いたコードでなんとなく実装してたりしますが、まぁどうにでもできそうなので省略。
あと、Azure Portalから取得したキーごと（APIごと）にトークンの有効期限が変わると思うので、自動でトークンを更新するなら、結局認証のクラスのインスタンスを複数を持つか、または、内部で有効期限を複数持つかすればいいかなーとか妄想します。
その他気になる点として、以前実装したときの古いURLではトークンの有効期限が取得できましたが、今回実装している新しいURLでは有効期限が取得できないため、AzureのAPI側がどうしていくんだろ？と気にしています。
おわりに
認証の方法（URLとか）は今後も変わる可能性がありますが、Cognitvie Services内のAPIは統一されてきそうなので、1つクラスを作っておけば有効に活用できそうですね。
