メニュー

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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 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.

asOf
文字列 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.

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つの単位があります。UsageCountPriceです。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 メッセージです。CountUsage は、いずれも送信したメッセージの件数です。
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 すべての利用の合計金額です。UsagePrice と同じになります。Count は空になります。 Twilio の利用料金にはどの利用カテゴリーにも当てはまらないものがあり、すべての利用記録の Price の合計が TotalPricePrice と一致しない場合がありますので、注意してください。

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.

例 1
        
        
        
        
        例 2
              
              
              
              
              例 3
                    
                    
                    
                    
                    例 4
                          
                          
                          
                          
                          例 5
                                
                                
                                
                                

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

                                Rate this page:

                                ヘルプが必要ですか?

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