2023年5月1日を持ちまして、株式会社KDDIウェブコミュニケーションズのTwilioリセール事業が終了したため、本記事に記載されている内容は正確ではないことを予めご了承ください。
はじめに
みなさん、こんにちは。
KDDIウェブコミュニケーションズのTwilio事業部エバンジェリストの高橋です。
前回の記事では、Studio API V2を使って、APIでフローを作成したり、更新する方法をご紹介しました。
Twilio CLI（Studio操作編①）
今回はさらに実践的な使い方として、ステージングテストやバージョン管理などについてご紹介したいと思います。ご自分でも試してみたい方は、ぜひ上記の記事を読んで準備をしておいてください。
フローのステータスについて
すでに管理コンソールでTwilio Studioをお使いの方であれば、作成したフローがPublishされないと反映しないことはご存知かと思います。
フローには２種類のステータスがあり、一つがDraftで、もう一つがPublishedです。
Published状態は、Publishされた状態のことで、フローは常に実行できる状態になっています。通常はこの状態で運用します。
一方、Draft状態のフローとはいわゆる下書き状態のことで、ある条件に合致したときだけ実行することができます。
その条件とは、「TriggerウィジェットのTEST USERSに指定された電話番号に一致する」ことです。
通常、TEST USERSは空欄になっていますが、ここに電話番号やClientIDを指定することで、指定した番号からの着信時だけはDraft状態のフローが実行されます。すなわち、TEST USERSフィールドを使うことで、Draft状態でのテストが可能になります。
テストユーザの管理
今回のStudio API V2で、TEST USERSを更新するためのAPIも用意されたので、早速試してみましょう。
まずは、ご自分の電話番号を登録してみます。以下のコマンドを利用します。
% twilio api:studio:v2:flows:test-users:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--test-users +818012345678
--sid にはテストユーザを登録したいフローのSIDを指定します。
--test-users にはテストユーザの電話番号（もしくはClientID）を指定します。複数指定したい場合は、スペースで区切ります。
登録が成功すると以下のように表示されます。
Test Users
["+818012345678"]
すでに登録されているテストユーザの一覧を表示されるには以下のコマンドを利用します。
% twilio api:studio:v2:flows:test-users:fetch \
--sid FWabe889fbe1650134e76508f2315877a4 \
--sid にはテストユーザを確認したいフローのSIDを指定します。
続けて、Draft状態でのテストについて確認してみましょう。
まずは前回の記事で作成したhello-world.json（Hello Worldという名前でフローがパブリッシュされているはずです）を利用します。
このフローをTwilioですでに購入済みの050番号に割り当てて、着信すると指定した通りのメッセージが流れることを確認しておきます。
つぎにhello-world.jsonを編集し、メッセージを適当に変更してから保存します。
編集したJSONファイルをアップデートしましょう。今回はDraft状態としてアップロードします。
% twilio api:studio:v2:flows:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--commit-message "Draft test" \
--status draft \
--definition "`cat hello-world.json`"
--status draft と指定することで、Draft状態でフローがアップロードされます。
先程テストユーザ端末として登録しておいた電話機から電話をかけてみて、Draft状態のメッセージが聞けることを確認します。
次に別の電話機から電話をするか、以下のコマンドを使ってテストユーザをクリアしてから電話をかけて、Draft状態にする直前の（Publishedな）状態のメッセージが流れることを確認します。
% twilio api:studio:v2:flows:test-users:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--test-users " "
では、Draft状態からPublished状態に移行させてみましょう。
以下のコマンドを使って、現在Draft状態にあるフローをパブリッシュしてみます。
% twilio api:studio:v2:flows:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--commit-message "Publish" \
--status published
成功すると以下のように表示されます。
SID Friendly Name Status Revision
FWabe889fbe1650134e76508f2315877a4 Hello World published 8
再度電話をかけて、先程Draft状態だったメッセージが流れることを確認します。
バージョン管理
Twilio Studioにはバージョン管理（リビジョン）機能があり、管理コンソール経由でリビジョンを確認したり、特定のリビジョンにロールバックさせることができました。
Studio API V2にもこの機能が実装されています。
ではまず、すべての履歴をリストアップするコマンドからみてみましょう。
% twilio api:studio:v2:flows:revisions:list \
--sid FWabe889fbe1650134e76508f2315877a4
--sid には、履歴を確認したいフローのSIDを指定します。
以下のようなリストが表示されます。
SID Friendly Name Status Revision
FWabe889fbe1650134e76508f2315877a4 Hello World published 8
FWabe889fbe1650134e76508f2315877a4 Hello World draft 7
FWabe889fbe1650134e76508f2315877a4 Hello World draft 6
FWabe889fbe1650134e76508f2315877a4 Hello World draft 5
FWabe889fbe1650134e76508f2315877a4 Hello World published 4
FWabe889fbe1650134e76508f2315877a4 Hello World draft 3
FWabe889fbe1650134e76508f2315877a4 Hello World draft 2
FWabe889fbe1650134e76508f2315877a4 Hello World published 1
これをみるとわかるように、現在の最新バージョンは8で、状態はpublishedです。
特定のバージョンにロールバックさせるには、そのリビジョンデータをダウンロードして、その内容で該当フローを更新します。
特定のリビジョンのフローをJSONとしてダウンロードしたい場合は、以下のように--revisionオプションを指定します。この例では、最新よりも一つ前にパブリッシュしたリビジョンデータ（Revision:4）をダウンロードしています。
% twilio api:studio:v2:flows:revisions:fetch \
--sid FWabe889fbe1650134e76508f2315877a4 \
--revision 4 \
-o json | jq '.[0].definition' > hello-world_4.json
あとは、このダウンロードしたフローデータを使って更新すればロールバックが完了します。
% twilio api:studio:v2:flows:update \
--sid FWabe889fbe1650134e76508f2315877a4 \
--commit-message "Rolling back test" \
--status published \
--definition "`cat hello-world_4.json`"
新しいバージョンで更新されたことがわかります。
正しくは、ロールバックというよりは過去のリビジョンのフローを上書きしたことになります。
SID Friendly Name Status Revision
FWabe889fbe1650134e76508f2315877a4 Hello World published 9
整合性チェック
JSONファイルを直接修正してフローを変更することが可能になりましたが、間違ってフローを壊してしまうこともあります。
そこで、フローの整合性のチェックするAPIを最後のご紹介します。
まずは、壊れていないJSONファイルでテストしてみましょう。
% twilio api:studio:v2:flows:validate:create --friendly-name "Hello World" --status draft --definition "`cat hello-world.json`"
整合性チェックが成功すると、以下のようにValidがtrueで戻ります。
Valid
true
では次に、JSONファイルを修正してエラーを出してみましょう。Say/Playウィジェットのタイプを、say-playからhogeに変更して、もう一度整合性チェックをしてみます。
» Error code 81022 from Twilio: Flow definition validation failed, check `details` for more information. See https://www.twilio.com/docs/errors/81022 for more info.
detailsをチェックしてくださいと書かれていますが、現時点ではdetailsは戻らないので、メッセージに書かれているhttps://www.twilio.com/docs/errors/81022を確認してみます。
詳細については現時点ではわからないので、こまめに整合性チェックをしながらテストするしかなさそうですね。
まとめ
Draft状態でのテストであったり、リビジョン管理であったりと、実際の開発ではかなり役立つ機能がAPIからも使えることがわかったかと思います。
とはいえ、Studioの特長はドラッグアンドドロップによる開発だと思うので、新規でのフロー作成は管理コンソールを用いて保守はAPIでやっていくとか、すでに作成済みのフローを一括で変更したいときにAPIを使うなどが実際の使いみちになりそうです。
Twilio（トゥイリオ）とは
https://cloudapi.kddi-web.com
Twilioは音声通話、メッセージング（SMS/チャット）、ビデオなどの 様々なコミュニケーション手段をアプリケーションやビジネスへ容易に組み込むことのできるクラウドAPIサービスです。初期費用不要な従量課金制で、各種開発言語に対応しているため、多くのハッカソンイベントやスタートアップなどにも、ご利用いただいております。