課金詳細情報CSV

はじめに

SORACOMの各サービスの利用料金は、月初から月末(UTC)までの間を１区間として計算され、課金が行われます。 コンソール上ではこの課金額の合算値を確認できますが、コンソールもしくはAPIを利用すると、 この利用料金の詳細な内訳をCSV形式で取得できます。 このドキュメントでは、課金の詳細情報CSVについて説明します。

コンソールでの課金詳細情報CSVの取得

課金情報の画面へは、ユーザーコンソール右上のプルダウンメニューから [ご利用料金] を選択して遷移できます。 直近月の課金詳細は、[CSV 形式でダウンロード] で取得できます。

このCSVは直近月の情報で、時間により随時更新されていきます。

また過去月のCSVについては、「過去のご利用料金」の各月の行をクリック後、画面最下部にあるボタンで取得可能です。

APIでの課金詳細情報CSVの取得

直近月の課金情報については、APIリファレンスのexportLatestBillingAPIで取得ができます。 また過去月の課金情報については、exportBillingAPIを使用してください。

現在の仕様では、月初が来た時点で、exportLatestBillingから取得できるCSVが当該月のものとなります。 また月初の締め処理（前月の課金再計算処理）が行われ課金金額が確定するまでの間は、exportBilling APIでは前月分を取得できません。 なお、月初の締め処理は通常月初から1-3営業日以内に完了します。

CSVのエンコード

CSVファイルは、UTF-8(BOMあり）のエンコードとなります。

CSVファイルの構造

CSVファイルは、次のような構造となっています。

以下が各項目の説明となります。

1行目 ヘッダー行

ヘッダー行には、項目名が並びます。 項目名は、大きく分けて「金額項目」と「タグ/グループ項目」に分かれ、金額項目のあとにタグ/グループ項目が出力されます。 「金額項目」「タグ/グループ項目」はいずれも可変のため、プログラムで取り込む場合は「CSVパース時の注意」を参考にしてください。

「金額項目」に表示される項目名は以下のとおりです。

• imsi
  • SIMのIMSI。SIM以外の課金項目(VPGや無料枠等)の場合、項目行が空となります。
• vpgId
  • SORACOM Canal/Directで使用するVirtual Private Gateway(VPG)のID。
  • VPG以外の課金項目(SIMや無料枠等)の場合は項目行が空となります。
  • SORACOM Canal/Directを使用していない場合は、この項目はCSVに出力されません。
• date
  • 課金項目については、対象日がyyyyMMdd形式で設定されます。
  • 無料利用枠については、対象月がyyyyMM形式で設定されます。

• billItemName

  • 課金/割引の項目名。現在以下の項目があります。

  課金レコード	内容
  basicCharge-ready	基本料金（SIM利用料金:ready時）
  basicCharge-active	基本料金（SIM利用料金:Active時）
  basicCharge-inactive	基本料金（SIM利用料金:Inactive時）
  basicCharge-suspended	基本料金（SIM利用料金:Suspended時）
  basicMonthlyChargeForPlanKM1	基本料金（plan-KM1 基本料）
  subscriberSuspensionCharge	Suspendedへの変更料金
  subscriberActivationCharge	Standbyからのアクティブ化料金
  subscriberContractRenewalCharge	SIMの契約更新料金
  dataTrafficChargeForPlanKM1	データ通信料（plan-KM1）
  subscriberActivationChargeForPlanKM1	plan-KM1 ready/suspendedからのActivate料金
  contractRenewalChargeForPlanKM1	plan-KM1 「準備完了」、「利用開始待ち」の状態で1年を経過した場合の契約更新料
  uploadDataCharge-xxxx-xxxx	日本向け上り（デバイスからSORACOM）へのデータ通信量。速度クラス(s1.fast等)と時間帯(daytime,nighttime)がハイフン区切りで付与されます。 例）uploadDataCharge-s1.fast-daytime
  downloadDataCharge-xxxx-xxxx	日本向け下り（SORACOMからデバイス）へのデータ通信量。速度クラス(s1.fast等)と時間帯(daytime,nighttime)がハイフン区切りで付与されます。 例）downloadDataCharge-s1.fast-nighttime
  dataTrafficCharge-xxx-xxxx	グローバル向け通信量の利用料金。/地域とサブスクリプションがハイフン区切りで付与されます。
  dataTrafficRoundedUpCharge-xxx-xxxx	グローバル向け通信量の切り上げ利用料金。国/地域とサブスクリプションがハイフン区切りで付与されます。
  chapAuthenticationCharge	CHAP認証のSIMごとの料金
  customDNSCharge	CustomDNSのSIMごとの料金
  ussdRequestCharge	USSD リクエスト利用料金
  planKM1LocationOptionCharge	plan-KM1 位置情報 利用料金
  planKM1LocationOptionRequestCharge	plan-KM1 位置情報 利用料金 リクエスト利用料金
  virtualPrivateGatewaySetupCharge	Virtual Private Gatewayのセットアップ料金(2016年4月までの分)
  virtualPrivateGatewayCanalSetupCharge	SORACOM Canal用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayDirectSetupCharge	SORACOM Direct用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayDoorSetupCharge	SORACOM Door用のVirtual Private Gatewayセットアップ料金
  virtualPrivateGatewayCharge	Virtual Private GatewayのSIMごとの利用料金
  soracomCanalVirtualPrivateGatewayCharge	SORACOM Canal用Virtual Private Gatewayの利用料金
  soracomCanalVPCPeeringCharge	SORACOM CanalのVPCPeeringごとの料金
  soracomDirectVirtualPrivateGatewayCharge	SORACOM Direct用Virtual Private Gatewayの料金
  soracomDirectVirtualInterfaceCharge	SORACOM DirectのVirtual Interfaseごとの料金
  soracomDoorVirtualPrivateGatewayCharge	SORACOM Door用Virtual Private Gatewayの料金
  soracomDoorVPNConnectionCharge	SORACOM DoorのVPN接続ごとの料金
  virtualPrivateGatewayFixedGlobalIpAddressOptionCharge	VPG 固定IPアドレスオプション 時間課金
  soracomBeamRequestCharge-xxx	Soracom Beam リクエスト利用料金。プロトコル名がハイフン区切りで付与されます。
  soracomEndorseCharge	Soracom Endorse 利用料金
  soracomFunnelRequestCharge-xxx	Soracom Funnel リクエスト利用料金。プロトコル名がハイフン区切りで付与されます。
  soracomFunkRequestCharge-xxx	Soracom Funk リクエスト利用料金。呼び出し先のFunctions名がハイフン区切りで付与されます。
  soracomHarvestCharge	Soracom Harvest利用料金
  soracomHarvestFilesStoreCharge	Soracom Harvest Files データ保存料金
  soracomHarvestRequestCharge	Soracom Harvest利用料金（2000リクエスト超過分)
  soracomHarvestTermExtensionCharge	Soracom Harvest 期間延長オプション料金
  soracomHarvestDataExportCharge	Soracom Harvest データエクスポート料金
  soracomHarvestFilesExportCharge	Soracom Harvest Files データエクスポート費用
  soracomInventoryDeviceRegistrationCharge	Soracom Inventory デバイス登録料金
  soracomInventoryMonthlyCharge	Soracom Inventory 月額利用料金
  soracomJunctionCharge	Soracom Junctionの料金
  soracomJunctionInspectionCharge	Soracom Junctionインスペクションの料金
  soracomKryptonInitialProvisioningCharge	Soracom Krypton 初回プロビジョニング利用料金
  soracomKryptonMonthlyProvisioningCharge	Soracom Krypton 月額セットアップ利用料金
  soracomLagoonMonthlyCharge-xxx	Soracom Lagoon月額費用。プラン名がハイフン区切りで入ります
  soracomLagoonLicensePackCharge-xxx	Soracom Lagoonライセンスパック料金。パック名がハイフン区切りで付与されます。
  soracomNapterCharge	Soracom Napter 利用料金
  soracomLTEMButtonPoweredByAWSRenewalCharge	SORACOM LTE-M Button powered by AWSの契約更新料金
  loRaGatewayOwnedModelFirstUnitMonthlyCharge	LoRaゲートウェイ専有モデル月額費用(1台目)
  loRaGatewayOwnedModelAdditionalUnitMonthlyCharge	LoRaゲートウェイ専有モデル月額費用(2台目以降)
  loRaGatewaySharedServiceModelMonthlyCharge	LoRaゲートウェイ共有モデル月額費用(1台目)
  sigfoxMessageCharge	Sigfoxメッセージ利用料金。契約内容や利用国などがハイフン区切りで付与されます。
  sigfoxDeviceRegistrationCharge	Sigfoxデバイス登録料金
  sigfoxAnnualConnectivityCharge	Sigfoxデバイス年間接続料金
  docomoSMSCharge	SMS料金(DOCOMO回線)
  docomoInternatinalSMSCharge	国際SMS料金(DOCOMO回線)
  kddiSMSCharge-yyyyMM	SMS料金(KDDI回線) yyyyMMに利用月が入ります。
  kddiInternatinalSMSCharge-yyyyMM	国際SMS料金(KDDI回線) yyyyMMに利用月が入ります。
  soracomSmsDeliveryCharge	Soracom SMS 配信利用料金
  soracomSmsSubmitCharge	Soracom SMS 送信利用料金

  割引レコード	内容
  dataTrafficFreeTier	データ通信無料利用枠
  soracomBeamRequestFreeTier	Soracom Beam リクエスト無料利用枠
  soracomEndorseFreeTier	Soracom Endorse 無料利用枠
  soracomFunnelRequestFreeTier	Soracom Funnel リクエスト無料利用枠
  soracomFunkRequestFreeTier	Soracom Funk リクエスト無料利用枠
  soracomHarvestFreeTier	Soracom Hearvest 無料利用枠
  soracomInventoryFreeTier	Soracom Inventory リクエスト無料利用枠
  soracomNapterFreeTier	Soracom Napter 無料利用枠
  dataTrafficCoupon	データ通信へのクーポン充当枠
  soracomBeamRequestCoupon	Soracom Beam リクエスト利用料へのクーポン充当枠
  soracomEndorseCoupon	Soracom Endorse利用料へのクーポン充当枠
  soracomFunnelRequestCoupon	Soracom Funnel利用料へのクーポン充当枠
  chargeCoupon	SORACOM利用料全体へのクーポン充当枠
  soracomAirBasicChargeVolumeDiscount	基本料金のボリュームディスカウント

• unitPrice

  • 料金の単価
  • 例えばデータ通信料の場合、1byteあたりの費用が出力されます。

• quantity

  • 課金/割引対象の数量
  • 例えばデータ通信量の場合、通信したbyte数が出力されます。

• amount

  • 項目の金額。unitPriceにquantityをかけた値が出力されます。

「タグ/グループ項目」には、各SIMに設定したタグ名と、グループ名が項目名として出力されます。 例えば次のようにタグ名/グループ名を付与すると、項目名とレコード行は次のようになります。 - SIM - 名前 : MySIM - タグ名: tag1 - タグ値: foo - グループ - グループID : d674d68e-da8a-44f6-8868-51d1f069bc06 - グループ名 : グループ 1

name,tag1,group:groupId,group:name
MySIM,foo,d674d68e-da8a-44f6-8868-51d1f069bc06,グループ 1

あるSIMにタグが付与されていたり、グループに所属したりしている場合は、そのSIMのレコード行にタグ値/グループIDおよび名前が 出力されるため、この値を使用することで、任意のタグ値やグループ名で集計をできます。

2行目以降 レコード行

２行目以降は、レコード行となります。 レコード行は「課金レコード」と「割引レコード」に分かれており、課金レコードの次に割引レコードが出力されます。

課金レコードは、IMSI/VPGIDごと、日ごと、課金項目ごとにレコードが作成され、quantity(数量）や金額(amount)は日(UTC)ごとに合算されます。 またIMSIやVPGにタグがついている場合は、タグ/グループ項目部分にその値が出力されます。

割引レコードは、無料利用枠やクーポン利用で利用金額から割引される項目が出力されます。日付(date)項目に対象の月が入ります。また金額(amount)の値として、割引額がマイナスで入ります。

なお、このCSVには消費税および合計金額に該当する項目はないため、請求金額と合わせる場合は、すべての金額(amount)を合算後、消費税率をかけ 小数点以下を切り上げしてください。

CSVパース時の注意点

CSVは、BOMつきのUTF-8でエンコードされていますので、UTF-8で読み込みを行ってください。

タグ/グループの値にカンマ(,)が入っている場合は、値がダブルコーテーションで括られます。 またダブルコーテーション(“)が入っている場合は、ダブルコーテーションでエスケープされます。 これらの文字を利用する場合は、エスケープを考慮できるCSVパーサを利用してください。

項目は可変のため、また今後ICCIDなど新規項目が追加になる可能性があるため、ヘッダー行とレコード行を合わせて読みこむようにしてください。 例えばCSVの1項目目がimsi、2項目がdateという形で固定で読み込むプログラムの実装した場合、SORACOM Canal/Directを使用してvpgIdが CSVに出力されたり、将来的にICCIDなどが追加されると正しくデータを取得できなくなるため、 CSVを一度オブジェクトやHash、連想配列など、レコード行をキー/値であつかえる形に変換した後、データを取り扱ってください。

Excelへのインポート

Office2013などの古いExcelの場合、文字コードの問題で、日本語などがCSVを開いただけでは正しく値が表示されないケースがあります。 この場合は、以下の手順でExcelにインポートすることが出来ます。

ダウンロードフォルダなどに入っている、ダウンロードしたCSVファイルをUTF-8に対応したテキストエディタで開く。

テキストエディタのデータを全選択して、コピーする

Excelを起動して、新規ワークシートを開く。

ワークシートの先頭セル(A1)を選択して、貼り付けを行う。

テキストウィザードを使用する。

区切り記号付きを選択して次へ

区切り文字にコンマを選択し、連続した区切り文字は１文字として扱うを未選択にして次へ

データ形式を標準にして完了

以上の手順で、Excelにデータがインポートされます。なお、IMSIが数字として表示されない場合は、IMSI列を選択して 形式を数値に変更してください。