Twilioが提供する利用トリガー : Usage Trigger (要ログイン)は、あらかじめ定義された使用・利用条件を満たすと指定のコールバックURLにWebhookを送る機能です。 利用トリガーにはさまざまな使用法がありますが、このFAQでは、不正とコーディングエラーの防止に非常に効果的なユースケースを取り上げます。
サブアカウント「サーキットブレーカー」スクリプト
このスクリプトは、設定したUsage TriggerによるWebhookの発動に対し、サブアカウント自体を一時停止させるように設計されています。なぜこのようにするのでしょうか?通信量が予想以上に多い状況では、サブアカウントの一時停止は適切な対処法となり得ます。手作業では、このような状況に常に迅速に対応できるとは限りません。そこで、望ましくない使用状況の継続を許すよりも、プロジェクトをオフラインにするのが良策です。一時停止しているサブアカウントは、その一時停止を解除できます。
サブアカウントのセットアップ
- このスクリプトを機能させるために、サブアカウント(要ログイン)を設定する必要があります。
- サブアカウントのアカウントSIDと認証トークンをコピーして使用してください。
スクリプトのセットアップ
スクリプトを設定するには、次のコードをサーバーに展開します。展開先サーバーは、PHPを実行し、Twilioから送信するWebhookからアクセスできるサーバーです。最初に次の変更を行うようにしてください。
- サブアカウントのアカウントSIDと認証アカウントをそれぞれ必要な場所に貼り付けて使用します。
- $urlをファイルの展開後の場所に変更します。
次のことも確認ください。
- 公式のTwilio PHPヘルパーライブラリが組み込まれていること。
- このスクリプトがトリガーされたことを何らかの方法で分かるようにすること。この例では説明を簡単にするために、メールによるアラート送信はしませんが、サブアカウントが一時停止したことを知らせる自分宛のメール(英語)を設定しようと思われるでしょう。REST APIによりサブアカウントが一時停止されても、Twilioからはアラートを出しません。
<?php
/** * Be sure to include the official Twilio PHP Helper Library, which can be found at:
* https://github.com/twilio/twilio-php
*/
require_once('Services/Twilio.php');
/* The Account SID for the Subaccount */ $SUBACCOUNT_SID = 'ACXXXXXXX';
$SUBACCOUNT_AUTH_TOKEN = 'YYYYYYYYY'; // The Auth Token for the Subaccount
/**
* The callback URL. Basically, the public address of this file. This is used for the Request Validation further down.
* You can also set this value dynamically with information from your environment.
* It's important to use 'https' because Twilio's Request Validation requires SSL.
*/
$url = 'https://example.com/circuit-breaker.php';
/**
* Suspending a subaccount is a scary thing, so we're going to use Twilio's Request Validation to make sure the webhook is actually coming from Twilio.
* You can learn more about Twilio's Request Validation here:
* http://www.twilio.com/docs/security#validating-requests
*/
$validator = new Services_Twilio_RequestValidator($SUBACCOUNT_AUTH_TOKEN);
$signature = $_SERVER["HTTP_X_TWILIO_SIGNATURE"];
if ($validator->validate($signature, $url, $_POST)) {
error_log("Confirmed to have come from Twilio. {$_POST['IdempotencyToken']}");
$client = new Services_Twilio($SUBACCOUNT_SID, $SUBACCOUNT_AUTH_TOKEN);
/**
* This is the code to suspend the account.
* Please note, you SHOULD NOT edit this code to make 'suspended' into 'closed'.
* Account suspension is reversible, closing an account is NOT reversible.
*/
/* Again, NOT 'closed' */
$client->account->update(array('Status' => 'suspended'));
/**
* You'll probably want to put some code here that alerts you when your subaccount has been suspended. Twilio won't alert you when you suspend an account via the API.
*/
}
利用トリガーのセットアップ
これで、Webhookを受信するスクリプトが設定できました。次に、Webhookをトリガーする利用トリガー(Usage Trigger)を作成する必要があります。以下は、cURLを使用してUsage Triggerを設定する例です。
$ curl POST -i https://api.twilio.com/2010-04-01/Accounts/{SubaccountAccountSID}/Usage/Triggers.json \ -d "FriendlyName=Suspend if subaccount uses more than $30 per-day" \ -d "Recurring=daily" \ -d "UsageCategory=totalprice" \ -d "TriggerBy=price" \ -d "TriggerValue=+30" \ -d "CallbackUrl=https://example.com/circuit-breaker.php" \ -u "{SubaccountAccountSID}:{SubaccountAuthToken}"
サブアカウントの再有効化
このスクリプトを実行することにより重大な影響が生じるため、スクリプトをテストしてどのように機能するかを確認することをお勧めします。テストの際は、サブアカウントを再有効化する必要があります。
ヘルプについては、こちらの API ドキュメントとサンプル コードをご覧ください - Re-activate a suspended subaccount。
注意事項
多数の電話番号を一度に購入された場合は、以降それらの番号への課金は同時に行われます。総額に応じてトリガーを設定する場合は、電話番号の通常の更新によりプロジェクトが一時停止とならないよう、十分な限度額を設定してください。