REST API: 使用状況記録 (Usage Records)

UsageRecords RESTリソースは、任意の期間中、および任意の利用カテゴリーにおけるお手持ちのTwilioアカウントの使用状況を取得するシンプルなAPIを提供します。これにより、アプリケーション用のレポートや分析ツールの作成が簡単になります。

UsageRecords used in combination with Subaccounts created for each of your end-users make it possible to build recurring usage-based billing systems on top of Twilio's API with just a few simple API calls. If rectifying UsageRecords with billing, see our dedicated article.

You can also set up usage triggers to notify your application when a particular category of usage reaches a threshold on a daily, monthly, yearly, or all-time basis. Triggers can help determine if your users have reached a cap on usage or if your application has runaway requests.

UsageRecord properties

このリソースとサブリソースは、利用記録のリストを返します。 UsageRecord リソースには、次のプロパティがあります。

Names in PHP format
`accountSid`	sid<AC> Not PII The SID of the Account that accrued the usage.
`apiVersion`	文字列 Not PII The API version used to create the resource.
`category`	enum:category Not PII The category of usage. For more information, see Usage Categories.
`count`	文字列 Not PII The number of usage events, such as the number of calls.
`countUnit`	文字列 Not PII The units in which `count` is measured, such as `calls` for calls or `messages` for SMS.
`description`	文字列 Not PII A plain-language description of the usage category.
`endDate`	date<iso8601> Not PII The last date for which usage is included in the UsageRecord. The date is specified in GMT and formatted as `YYYY-MM-DD`.
`price`	decimal Not PII The total price of the usage in the currency specified in `price_unit` and associated with the account.
`priceUnit`	currency Not PII The currency in which `price` is measured, in ISO 4127 format, such as `usd`, `eur`, and `jpy`.
`startDate`	date<iso8601> Not PII The first date for which usage is included in this UsageRecord. The date is specified in GMT and formatted as `YYYY-MM-DD`.
`subresourceUris`	uri_map Not PII A list of related resources identified by their URIs. For more information, see List Subresources.
`uri`	uri Not PII The URI of the resource, relative to `https://api.twilio.com`.
`usage`	文字列 Not PII The amount used to bill usage and measured in units described in `usage_unit`.
`usageUnit`	文字列 Not PII The units in which `usage` is measured, such as `minutes` for calls or `messages` for SMS.

Usage、Count、Price プロパティ

それぞれの利用記録では、3つの単位があります。Usage、Count、Priceです。Usageはそのカテゴリーで使われる主要単位で表示されます。音声通話時間ではminutes、SMSではmessages、イベント数ではCount、音声通話数ではcallsとなります。Priceは利用料の合計金額を表します。

それぞれの利用記録には、利用量の記録に用いる単位を示すフィールドがあります。たとえば、Usage の単位は UsageUnit です。これらのフィールドを使って、利用一覧を表示するダッシュボードを簡単に作成することができます。たとえばこれらのパラメーターを次のように変数に代入して組み合わせると、人間が読みやすい形式の文字列で利用状況を表すことができます。「$Usage $UsageUnits (1分、3時間、など) 」、「$Count $CountUnits (25個、など) 」、「$Price $PriceUnits (500JPY、2USD、など) 」

利用カテゴリー

利用記録の Category で、その利用記録が表す利用種別を定義します。完全なリストはここにありますが、通常よく使われるのは、次のカテゴリーです。

Category	概要
calls	すべての音声通話です。`Count` は通話の件数、`Usage` は分数です。
sms	すべての SMS メッセージです。`Count` と `Usage` は、いずれも送信したメッセージの件数です。
pfax-minutes	Programmable Fax minutes. `Count` is the number of faxes and `Usage` is the number of minutes.
pfax-pages	Programmable Fax pages. `Count` is the number of faxes and `Usage` is the number of pages.
phonenumbers	このアカウントが所有するすべての電話番号です。
recordings	音声通話の録音です。`Count` は録音件数、`Usage` は録音分数です。
transcriptions	音声通話のトランスクリプションです。`Count` はトランスクリプションの件数、`Usage` はテキスト化された音声の分数です。
totalprice	すべての利用の合計金額です。`Usage` は `Price` と同じになります。`Count` は空になります。 Twilio の利用料金にはどの利用カテゴリーにも当てはまらないものがあり、すべての利用記録の `Price` の合計が `TotalPrice` の `Price` と一致しない場合がありますので、注意してください。

Read multiple UsageRecord resources

GET

https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Records.json

デフォルトでは、UsageRecord リソースは、Category ごとに 1 つの利用記録を返します。この利用記録は、アカウントに課金されたすべての利用を対象とし、期間の指定はありません。利用を Category でフィルターするか、またはオプションの GET クエリパラメーターを使用して、利用をカウントする日付の範囲を変更できます。クエリパラメーターの大文字と小文字は区別されますので、注意してください。

パラメーター

Names in None format
`category` オプション	GET enum:category Not PII The usage category of the UsageRecord resources to read. Only UsageRecord resources in the specified category are retrieved.
`start_date` オプション	GET date<iso8601> Not PII Only include usage that has occurred on or after this date. Specify the date in GMT and format as `YYYY-MM-DD`. You can also specify offsets from the current date, such as: `-30days`, which will set the start date to be 30 days before the current date.
`end_date` オプション	GET date<iso8601> Not PII Only include usage that occurred on or before this date. Specify the date in GMT and format as `YYYY-MM-DD`. You can also specify offsets from the current date, such as: `+30days`, which will set the end date to 30 days from the current date.
`include_subaccounts` オプション	GET boolean Not PII Whether to include usage from the master account and all its subaccounts. Can be: `true` (the default) to include usage from the master account and all subaccounts or `false` to retrieve usage from only the specified account.
`account_sid` 必須	GET sid<AC> Not PII The SID of the Account that created the UsageRecord resources to read.

たとえば、2012 年 4 月のすべての利用記録をリクエストするとします。ここではクエリ文字列は StartDate=2012-04-01&EndDate=2012-04-30 です。 4 月中の利用について、利用種別につき 1 つの利用記録が返ります。このリストはページ情報を含みます。後述の例 2 を参照してください。

後述のサブリソースを使って、利用を日、月、年ごとにグループ化することもできます。

リストサブリソース

メインの UsageRecords リストリソースは、さまざまなサブリソースをサポートしており、便利に使えます。原則として、次の形式を取ります。

/2010-04-01/Accounts/{AccountSid}/Usage/Records/{Subresource}

サポートするサブリソースは、次の通りです。

サブリソース	概要
Daily	利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 日の利用を表現します。
Monthly	利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 か月の利用を表現します。
Yearly	利用カテゴリーごとに、複数の利用記録を返します。各項目は 1 年の利用を表現します。
AllTime	利用カテゴリーごとに、1 つの利用記録を返します。各項目は指定された日付範囲の利用を表現します。 root /Usage/Records と同じです。
Today	今日の利用分のみの、利用カテゴリーにつき 1 つの利用記録を返します。
Yesterday	昨日の利用分のみの、利用カテゴリーにつき 1 つの利用記録を返します。
ThisMonth	今月の利用分のみの、利用カテゴリーにつき 1 つの利用記録を返します。
LastMonth	先月の利用分のみの、利用カテゴリーにつき 1 つの利用記録を返します。

これらの便利なサブリソースを使って、日ごとの通話のグラフを作成したり、すべての利用カテゴリーの月間利用をダッシュボードに表示したり、先月の利用合計を元に利用料金の請求システムを構築できます。

すべてのサブリソースは、ルートの UsageCounter リソースと同じリストフィルターをサポートします。

すべての利用カテゴリーの完全なリスト

Voice

Category	概要
calls	すべての音声通話です。インバウンドとアウトバウンドがあります。Count は通話件数、Usage は分数です。
calls-inbound	携帯電話番号、無料電話番号、およびローカル番号へのすべてのインバウンド音声通話です。
calls-inbound-local	国内番号への、すべての着信音声通話です。
calls-inbound-mobile	携帯電話番号へのすべてのインバウンド音声通話です。
calls-inbound-tollfree	無料電話番号への、すべての着信音声通話です。
calls-outbound	すべての発信音声通話です。
calls-sip	すべてのSIPコール
calls-sip-inbound	すべてのインバウンド SIP 通話です。
calls-sip-outbound	すべてのアウトバウンド SIP 通話です。
calls-client	すべてのTiwlio クライアント音声通話です。
calls-globalconference	すべてのグローバルカンファレンス通話
call-progess-events	すべてのコールプログレスイベントです。
recordings	音声通話とトランク通話の録音です。Count は録音件数、Usage は録音分数です。
calls-recordings	音声通話の録音です。Count は録音件数、Usage は録音分数です。
recordingstorage	このアカウントで保存された通話の録音が使用する保存容量です。Count は保存された録音の件数、Usage は保存された録音の分数、Price は録音の保存料金です。
transcriptions	音声通話のトランスクリプションです。Count はトランスクリプションの件数、Usage はテキスト化された音声の分数です。

SMS & MMS

Category	概要
sms	着信と発信の両方のすべての SMS メッセージです。Count と Usage は、どちらも送信されたメッセージの件数です。
sms-inbound	ショートコードとロングコードの両方への、すべての着信 SMS メッセージです。
sms-inbound-longcode	ロングコード宛の、すべての着信 SMS メッセージです。
sms-inbound-shortcode	ショートコード宛の、すべての着信 SMS メッセージです。
sms-outbound	ショートコードとロングコードの両方からの、すべての発信 SMS メッセージです。
sms-outbound-longcode	ロングコードからの、すべての発信 SMS メッセージです。
sms-outbound-shortcode	ショートコードからの、すべての発信 SMS メッセージです。
sms-messages-carrierfees	All carrier fees for SMS messages.
MMS	着信と発信の、すべての MMS メッセージです。Count と Usage は、どちらも送信されたメッセージの件数です。
mms-inbound	ショートコードとロングコードの両方への、すべての着信 MMS メッセージです。
mms-inbound-longcode	ロングコード宛の、すべての着信 MMS メッセージです。
mms-inbound-shortcode	ショートコード宛の、すべての着信 MMS メッセージです。
mms-outbound	ショートコードとロングコードの両方からの、すべての発信 MMS メッセージです。
mms-outbound-longcode	ロングコードからの、すべての発信 MMS メッセージです。
mms-outbound-shortcode	ショートコードからの、すべての発信 MMS メッセージです。
mms-messages-carrierfees	All carrier fees for MMS messages.
mediastorage	このアカウントで保存されたメディアが使用する保存容量です。Count は保存されたメディアファイルの件数、Usage はメガバイト数、Price はメディアの保存料金です。

電話番号

Category	概要
phonenumbers	このアカウントが所有するすべての電話番号です。携帯電話番号、無料電話番号、および国内電話番号があります。
phonenumbers-local	このアカウントが所有するすべての国内電話番号です。
phonenumbers-mobile	このアカウントが所有するすべての携帯電話番号です。
phonenumbers-tollfree	このアカウントが所有するすべての無料電話番号です。
phonenumbers-cps	すべての電話番号秒間通話回数（CPS）増加分です。
phonenumbers-setups	すべての電話番号設定料金です。
shortcodes	このアカウントが所有する、すべての種別のショートコードです。
shortcodes-customerowned	このアカウントが所有する、すべての他のプロバイダーから貸与されたショートコードです。
shortcodes-mms-enablement	すべてのショートコード MMS 有効化料金です。
shortcodes-mps	すべてのショートコード秒間メッセージ数（MPS）増加分です。
shortcodes-random	このアカウントが所有する、すべてのランダムに割り当てられたショートコードです。
shortcodes-uk	このアカウントが所有する、すべての英国ショートコードです。
shortcodes-vanity	このアカウントが所有する、すべてのカスタムショートコードです。

ルックアップ

Category	概要
lookups	すべてのルックアップです。キャリア、発信者 ID、および番号形式のルックアップが含まれます。
carrier-lookups	すべてのキャリアルックアップです。
calleridlookups	すべての callerID （CallerName）ルックアップです。
number-format-lookups	すべての番号形式ルックアップです。

Elastic SIP Trunking

Category	概要
trunking-origination	携帯電話番号、無料電話番号、および国内電話番号へのすべてのトランキングオリジネーション（着信）通話です。
trunking-origination-local	国内電話番号へのすべてのトランキングオリジネーション（着信）通話です。
trunking-origination-mobile	携帯電話番号へのすべてのトランキングオリジネーション（着信）通話です。
trunking-origination-tollfree	無料電話番号へのすべてのトランキングオリジネーション（着信）通話です。
trunking-termination	すべてのトランキングターミネーション（発信）通話です。
trunking-recordings	トランク通話の録音です。Count は録音件数、Usage は録音分数です。
trunking-cps	すべてのトランキング秒間通話回数（CPS）増加分です。
trunking-secure	すべての保護されたトランク通話です。

TaskRouter

Category	概要
taskrouter-tasks	TaskRouterで作成されたすべてのタスクです。

ネットワークトラバーサル

Category	概要
turnmegabytes	ネットワークトラバーサルで使用されたすべての TURN メガバイト数です。

authy

Category	概要
authy-authentications	すべての Authy 認証です。
authy-calls-outbound	すべての Authy 発信通話です。この利用状況は音声カテゴリーにも含まれます。
authy-monthly-fees	すべての Authy 月額料金です。
authy-phone-intelligence	すべての Authy 電話インテリジェンスリクエストです。
authy-phone-verifications	すべての Authy 電話認証です。
authy-sms-outbound	すべての Authy 発信 SMS メッセージです。この利用状況は SMS カテゴリーにも含まれるので、注意してください。

Studio

Category	概要
studio-engagements	すべてのStudio Engagementです

モニター

Category	概要
monitor-reads	すべてのモニターイベント API 読み込みです。
monitor-writes	すべてのモニターイベント書き込みです。
monitor-storage	すべてのモニターイベント保存料金です。

その他

Category	概要
premiumsupport	すべてのプレミアムサポート料金です。
totalprice	すべての利用の合計料金です。Usage は Price と同じになります。Count は空になります。 Twilio の利用料金にはどの利用カテゴリーにも当てはまらないものがあり、すべての UsageRecord の Price の合計が TotalPrice の Price と一致する場合としない場合がありますので、注意してください。

UsageRecord インスタンスリソース

UsageRecord リソースに直接リクエストを発行することはできません。 UsageRecords リストリソースまたはサブリソースのいずれかに、リクエストを発行してください。

ヘルプが必要ですか？

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

Thanks for rating this page!

ヘルプが必要ですか？