課金詳細情報 CSV リファレンス
課金詳細情報 CSV の取得方法については、利用料金を確認する / 課金詳細情報 CSV をダウンロードする を参照してください。
構造
CSV ファイルは、大きく分けて「金額項目」と「補足情報項目」、「課金レコード」と「割引レコード」に分かれています。
各項目の意味は以下のとおりです。
ヘッダー行 (1 行目)
ヘッダー行には、項目名が並びます。 項目名は、大きく分けて「金額項目」と「補足情報項目」に分かれ、金額項目のあとに補足情報項目が出力されます。 「金額項目」「補足情報項目」はいずれも可変のため、プログラムで取り込む場合は、CSV ファイル読み込み時の注意点 を参考にしてください。
金額項目
「金額項目」に出力される項目名は以下のとおりです。
| 項目 | 説明 |
|---|---|
imsi (*1) | IoT SIM の IMSI。IoT SIM に無関係の課金項目 (VPG や無料枠など) の場合は、値が出力されません。 |
vpgId (*1) | SORACOM Canal/Direct で使用する Virtual Private Gateway (VPG) の ID。VPG に無関係の課金項目 (IoT SIM や無料枠など) の場合は、値が出力されません。 |
loraGatewayId (*1) | LoRaWAN ゲートウェイの ID |
loraDeviceId (*1) | LoRaWAN デバイスの ID |
sigfoxDeviceId (*1) | Sigfox デバイス の ID |
deviceId (*1) | SORACOM Inventory のデバイス ID |
gadgetId (*1) | Gadget API 対応デバイス の ID |
soraCamDeviceId (*1) | ソラカメ対応カメラのデバイス ID |
vpgId (*1) | SORACOM Canal/Direct で使用する Virtual Private Gateway (VPG) の ID。VPG に無関係の課金項目 (IoT SIM や無料枠など) の場合は、値が出力されません。 |
date | 対象日/対象月
|
billItemName | 課金レコード および 割引レコード を参照してください。 |
unitPrice | 料金の単価。たとえばデータ通信料金の場合、1 バイトあたりの費用が出力されます。 |
quantity | 課金/割引対象の数量。たとえば、データ通信料金の場合 (billItemName が、uploadDataCharge または downloadDataCharge で始まる場合) は、通信したバイト数が出力されます。 |
amount | 項目の金額。unitPrice × quantity の値が出力されます。 |
- (*1) 利用状況によっては出力されません。
補足情報項目
「補足情報項目」に出力される項目名は以下のとおりです。
| 項目 | 説明 |
|---|---|
name (*2) | IoT SIM の名前。IoT SIM に無関係の課金項目 (VPG や無料枠など) の場合は、値が出力されません。 |
simId (*2) | IoT SIM の SIM ID。IoT SIM に無関係の課金項目 (VPG や無料枠など) の場合は、値が出力されません。 |
| IoT SIM に設定したタグ の名前 | IoT SIM に設定したタグ の値。出力例については、IoT SIM / グループの設定例 を参照してください。 |
group:groupId (*2) | グループ ID。グループに無関係の課金項目 (VPG や無料枠など) の場合は、値が出力されません。 |
group:name (*2) | グループ名。グループにに無関係の課金項目 (VPG や無料枠など) の場合は、値が出力されません。 |
| グループ に設定したタグの名前 | グループ に設定したタグの値。出力例については、IoT SIM / グループの設定例 を参照してください。 |
- (*2) 利用状況によっては出力されません。
補足情報項目に出力される情報は、CSV を出力した時点の情報です。
料金が発生したタイミングの情報ではありません。
IoT SIM / グループの設定例
- IoT SIM (1)
- 名前 : MySIM 1
- SIM ID: 89423xxxxxxxxxxxxx1
- タグ名: tag1, 値: foo
- グループ
- グループ ID : xxxxxxxx-xxxx-xxxx-xxxx-51d1f069bc06
- グループ名 : グループ 1
- タグ名: g_tag2, 値: bar
- IoT SIM (2)
- 名前 : MySIM 2
- SIM ID: 89423xxxxxxxxxxxxx2
- タグ名: tag1, 値: foofoo
- グループ
- グループ ID : xxxxxxxx-xxxx-xxxx-xxxx-51d1f069bc06
- グループ名 : グループ 1
- タグ名: g_tag2, 値: bar
- IoT SIM (3)
- 名前 : MySIM 3
- SIM ID: 89423xxxxxxxxxxxxx3
- タグ名: tag2, 値: foofoofoo
- グループ
- グループ ID : xxxxxxxx-xxxx-xxxx-xxxx-20dd1f380e95
- グループ名 : グループ 2
- タグ名: g_tag2, 値: barbar
CSV ファイルの出力例:
...,name,simId,tag1,tag2,group:groupId,group:name,group:g_tag2
...,MySIM 1,89423xxxxxxxxxxxxx1,foo,,xxxxxxxx-xxxx-xxxx-xxxx-51d1f069bc06,グループ 1,bar
...,MySIM 2,89423xxxxxxxxxxxxx2,foofoo,,xxxxxxxx-xxxx-xxxx-xxxx-51d1f069bc06,グループ 1,bar
...,MySIM 3,89423xxxxxxxxxxxxx3,,foofoofoo,xxxxxxxx-xxxx-xxxx-xxxx-20dd1f380e95,グループ 2,barbar
レコード行 (2 行目以降)
2 行目以降は、レコード行となります。 レコード行は「課金レコード」と「割引レコード」に分かれており、課金レコードの次に割引レコードが出力されます。
課金レコードは、IMSI/VPG ID ごと、日ごと、課金項目ごとにレコードが作成され、quantity (数量) や金額 (amount) は日 (UTC) ごとに合算されます。 また IMSI や VPG に関する補足情報が存在する場合は、補足情報項目部分にその値が出力されます。
割引レコードは、無料利用枠やクーポン利用で利用金額から割引される項目が出力されます。日付 (date) 項目に対象の月が入ります。また金額 (amount) の値として、割引額がマイナスで入ります。
なお、この CSV には消費税および合計金額に該当する項目はないため、請求金額と合わせる場合は、すべての金額 (amount) を合算後、消費税率をかけ 小数点以下を切り上げしてください。
billItemName 項目一覧
課金レコード
割引レコード
CSV ファイル読み込み時の注意点
ファイルのエンコード
BOM つきの UTF-8 でエンコードされています。
エスケープおよび改行
補足情報項目の値に使用する文字によっては、以下のように処理されます。CSV ファイルを読み込むときは、このルールに従って処理してください。
- 補足情報項目の値にカンマ (
,) や改行コードが入っている場合は、値がダブルクォーテーション (") で括られます。 - 補足情報項目の値にダブルクォーテーション (
") が入っている場合は、ダブルクォーテーション ("") でエスケープされます。
データ項目
データ項目は出力するデータにあわせて増減します。また、SORACOM プラットフォームの仕様変更により増減することがあります。
そのため、ヘッダー行とレコード行を正しく組み合わせて読み込んでください。
NG 例: CSV ファイル の 1 項目目が IMSI、2 項目目が date という前提でデータを取り扱う。SORACOM Canal/Direct を使用すると date の前に vpgId が出力されて項目の順番が変わるため、将来、正しくデータを取り扱えなくなる可能性があります。
OK 例: CSV ファイルのすべてのデータを、キーと値の組み合わせで扱えるオブジェクト (ハッシュ、連想配列など) に正しく記録してから取り扱う。