【Vonage】最新CPaaSのユーザ認証APIをSDKを独自実装しながら理解する【Go】

この記事は最新CPaaSコミュニケーションAPIを比べる or 使ってみよう！【PR】Vonage Japanの3日目の記事です。

この記事の内容

Communication Platform as a ServiceのVonageさんのVerify APIを触ってみて得た開発知見を共有します。Verify APIは簡単にSMSやTELを使ったユーザ認証を実現できるAPIです。
ただAPIを触るだけじゃつまらない! & 私はGoで使いたいんや!という個人的な思いから、公式さんから正式提供されていないGo版のSDKを作るところまでやりました。その実装についての紹介です。

作成したSDKは下記で公開しています。様々なAPIが提供されているのですが、まずはユーザ認証用のVerify APIの基本操作を行う部分だけ完成しています…!

そしてこの記事を書いている最中に気が付きましたが、まだリリースしていないだけで、当然公式さんもGoのSDKを開発中でしたね！いいんです、フルスクラッチで実装することで私の理解が深まったことでしょう（白目今後は下記のrepoにcontributeしてみたいな、と思います

以下では公式のSDKの存在を意識の外に置いて進めていきます

Vonageの機能概要を見てみよう

何はともあれ、公式サイト・公式ドキュメントからスタートするべきですね。ということで早速お邪魔してみましょう。ディペロッパーセンターというページが用意されているので、そちらに進んでみます。ふむふむ、Video APIとそれ以外のVONAGE APIに大別されるようです。

今回は、私が個人的に運営しているサービスでも使えるかな？という期待を込めて、SMSへのPINコード送信とコード認証が行えるVerify APIを使ってみようと思います。(VONAGE APIの一部です)

Verify APIの仕様を確認しよう

詳細なAPIドキュメントが用意されています。ここまではユーザ登録などしなくても確認することが可能でした。

APIエンドポイントに対してリクエストを飛ばしてあげるだけで、PINコード送信(Verify)、コード認証(Check)、その他オペレーション(ワークフローの中止など)を行えることが分かります。curlなどでも使えますが、複数の言語向けにSDKも提供されています。そちらを使うことでより気軽に活用することが可能に思えます。対応している言語はこの記事の公開時点で以下の通りですね。

さて、せっかくなので認証を試してみたいと思います。VONAGE APIディペロッパーセンターからサインアップしアカウントを作成すると、次のようなダッシュボードを使うことができるようになりました。リクエストに必要なAPI_KEYやAPI_SECRETはこのダッシュボードから取得可能ですし、GUIを使って簡単にコード送信⇒認証を試すこともできます。親切ですね。

ためしに自分の携帯電話にコードを送信し認証ワークフローを実行してみると…、おお、SMSが送られてきました！ curlでもリクエストを送ってみて動作を確認できました。

認証ワークフローについては公式ドキュメントを読めば十分理解可能ではありますが、分かりやすい図をVonageの @ak7787 様が掲載されていたので引用させて頂きます。記事リンク

今回は上図で言うところのAppサーバーの処理を実装していく、ということですね。

余談ですが、PINコードを受け取ってしばらく放置しておいたら、突如アメリカから電話がかかってきました 後でドキュメントを確認して分かりましたが、いくつかのワークフローがあり、デフォルトのフローではSMS⇒電話⇒電話という形でリマインダーを送ってくれるんですね。びっくりしました笑

さて、一通りAPIの動作確認ができたので、いよいよ使いこなしに向けて活動してみましょう。

SDK開発スタート

上述したようにSDKが充実しているのですが、私はGoで書きたい！GoのSDKはリリースされていない！よし作ろう！となりました

基本的にやるべきことはAPIリファレンスを参照すれば分かりそうですが、実装に踏み込んで仕様を理解しておきたい気持ちもあるので、公開されている他言語のSDKも確認しておくことにします。私が経験があるのはPythonなのでそちらのSDKを参照するのが近道ですが、いかんせんソースコード中で型が明示されていないので解読が辛いですね…。ということで雰囲気は分かるJavaも並行して参照してみましょう。

ソースコードを確認しての所感

JavaとPythonで圧倒的にコード量が違うのは何なんだろうとなりました（小並感）
- Java
- Python
一つのメソッドに対しOptionalなパラメータが結構な数存在するため、それに対応するための処置を多く含んでいそうです。

設計要件・設計指針

まずは機能ミニマムで入っていきたいので、VerifyAPIの最小実装を確認してみます。こちらにサンプルがありましたので参照します。

上記の例を見つつ、各メソッドの実装を確認すると最小機能は次のようです

POSTリクエストを送る
リクエストボディはrequiredなAPI_KEY, API_SECRET、PINを送る相手のPHONE_NUMBER、SMSに記載するBRAND_NAMEをjsonで作る
- 電話番号はE.164形式にするのを忘れずに（例：日本国内の番号090123456だったら、国コード81をつけて8190123456）
リクエストヘッダにBASIC認証をつける（ここはAPIリファレンスからは読み取れず。SDKの実装から判断した）
verify, check, cancelの3通りのメソッドを持っておけば実用には耐えそう

次に実装に向けて設計指針を決めておきます。

パラメータの与え方が複数パターンあるメソッドは、拡張性を考えてfunctional option patternで実装する。
- functional option pattern はこちらを参照

…ひとまずこれだけでしょうかね

以上を加味して、目指すふるまいは次のようになります。(PINコードを送信するverifyメソッドのみ抜粋)

import "github.com/tenkoh/vonage-go-sdk"

func main(){
  client, _ := vonage.NewClient(
    vonage.ApiKey("YOUR_API_KEY"),
    vonage.ApiSecret("YOUR_API_SECRET"),
  )
  resp, _ := client.GenerateVerifyClient().Verify(
    vonage.VerifyNumber("PHONE_NUMBER"),
    vonage.VerifyBrand("YOUR_BRAND_NAME"),
  )
}

実装自体は上記ふるまいに合致するようにガリガリ書くだけなので、特に難しいことはありません。(API叩くだけですしね)

自分で作ったSDKで行うリクエストは格別ですね！

PINコードの送信⇨受信したコードを使った認証処理までを行うサンプルアプリケーションも自作repoに加えてありますので、そちらも含めて参照いただけると使用イメージが掴みやすいと思います。

おわりに

SDKを自作するつもりで各種ドキュメント・ソースコードを参照したので、なかなかにVONAGE APIのことを理解することができました。いわんやリリース済みのSDKを活用すれば、とんでもなく簡単にSMSを使ったユーザ認証を実現することができて良いですね！

本記事を作成するにあたりVonage公式さんに相談したところ、追加のトライアルクレジットを頂くことができました。手厚いサポートを受けることもできるんだなぁと実感できて、とても良い開発体験を積むことができました。ありがとうございます。

さて、冒頭で宣言したように公式repoへcontributeすべく、まずは仕様理解に取り組みますか…！おあとがよろしいようで。