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.

Usage Triggers をセットすれば、日・月・年をはじめとした様々な時間軸で、特定のカテゴリの利用が、予め設定した閾値を超えた際に、通知をだすことができます。トリガーは、エンドユーザーがその使用上限に達した場合や、アプリケーションのリクエストが制御不能に陥った場合を判断するのに役立てることができます。

UsageRecord properties

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

Names in REST API format
`account_sid`	sid<AC> Not PII The SID of the Account that accrued the usage.
`api_version`	文字列 Not PII The API version used to create the resource.
`as_of`	文字列 Not PII Usage records up to date as of this timestamp, formatted as YYYY-MM-DDTHH:MM:SS+00:00. All timestamps are in GMT
`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.
`count_unit`	文字列 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.
`end_date`	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.
`price_unit`	currency Not PII The currency in which `price` is measured, in ISO 4127 format, such as `usd`, `eur`, and `jpy`.
`start_date`	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`.
`subresource_uris`	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`.
`usage_unit`	文字列 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	Inbound and outbound voice calls. Does not include SIP or client calls. `Count` is the number of calls and `Usage` is the number of minutes.
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` はテキスト化された音声の分数です。
pv	All Programmable Video usage including TURN. `Price` accounts for expenses in all Programmable Video products. `Count` and `Usage` should be ignored.
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 REST API format
`account_sid` Path	GET sid<AC> Not PII The SID of the Account that created the UsageRecord resources to read.
`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.

たとえば、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	Inbound and outbound voice calls. Count is the number of calls and Usage is the number of minutes. Does not include client or SIP calls.
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で作成されたすべてのタスクです。

Programmable Video

Category	概要
pv	All Programmable Video usage including TURN. `Price` accounts for expenses in all Programmable Video products. `Count` and `Usage` should be ignored.
group-rooms	Accounts for all Group Rooms usage. `Count` is the number of rooms. `Usage` should be ignored.
group-rooms-participant-minutes	All participant usage in Group Rooms. `Count` and `Usage` measure the number of participant minutes.
group-rooms-data-track	All Group Room Data Tracks activity. `Count` and `Usage` measure thousands of messages sent.
small-group-rooms	Accounts for all Small Group Rooms usage. `Count` is the number of rooms. `Usage` should be ignored.
small-group-rooms-participant-minutes	All participant usage in Small Group Rooms. `Count` and `Usage` measure the number of participant minutes.
small-group-rooms-data-track	All Small Group Room Data Tracks activity. `Count` and `Usage` measure thousands of messages sent.
pv-rooms	Accounts for all Peer-to-Peer Rooms usage. `Count` is the number of rooms. `Usage` is the number of participant minutes.
peer-to-peer-rooms-participant-minutes	All participant usage in P2P Rooms. `Count` and `Usage` measure the number of participant minutes.
video-recordings	All usage regarding video Recordings and Compositions. `Count` and `Usage` should be ignored.
group-rooms-recorded-minutes	All Recordings generated out of Group Rooms (including Small Group Rooms). `Count` and `Usage` measure the number of recorded participant minutes.
pv-composition-minutes	All Video Recording Compositions. `Count` and `Usage` measure the number of composition minutes.
group-rooms-encrypted-media-recorded	All encrypted media including Group Room Recordings and Compositions. `Count` and `Usage` measure the number of encrypted participant minutes and composition minutes.
group-rooms-media-stored	All media stored in Twilio by Programmable Video Services including Recordings and Compositions. `Count` and `Usage` measure the number of stored GB/day (Gigabytes per day).
group-rooms-media-downloaded	All media downloaded from Twilio regarding Programmable Video Services. This includes Recordings and Compositions. `Count` and `Usage` measure the number of downloaded GB (Gigabytes).
turnmegabytes	All TURN data relayed by Twilio. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-australia	TURN data relayed by Twilio in the Australia AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-brasil	TURN data relayed by Twilio in the Brazil AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-india	TURN data relayed by Twilio in the India AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-ireland	TURN data relayed by Twilio in the Ireland AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-japan	TURN data relayed by Twilio in the Japan AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-singapore	TURN data relayed by Twilio in the Singapore AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-useast	TURN data relayed by Twilio in the US (East) AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-uswest	TURN data relayed by Twilio in the US (West) AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)
turnmegabytes-germany	TURN data relayed by Twilio in the Germany AWS region. `Count` and `Usage` measure the relayed traffic in MB (Megabytes)

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 リストリソースまたはサブリソースのいずれかに、リクエストを発行してください。

ヘルプが必要ですか？

誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。

Thanks for rating this page!

パラメーター

例 1

例 2

例 3

例 4

例 5

ヘルプが必要ですか？