SAKURA internet

さくらのクラウドの最新情報、技術情報

さくらのクラウドニュース

さくらのクラウドの最新情報や、開発に役立つ技術情報をお届けします。

請求関連API

[更新日:2016年6月17日]

1.概要

さくらのクラウドで提供している「さくらのクラウドAPI」では、リソース操作以外に、請求金額や作成したリソースごとの利用明細など請求関連の情報も取得することが可能です。このAPIを利用することより、

・さくらのクラウド使用料を元に、エンドユーザ向けに手数料を加算した請求を自動作成する
・過去の請求履歴よりサーバ・ディスク利用数・利用時間などリソース使用量を詳細に分析する
・単純な料金しきい値のみ設定可能な料金アラート機能を使用せず、トラフィック量との割合を元にした独自の料金アラート機能を作成する

など、料金部分においても自動化・省力化できる範囲を拡大することが可能となります。

※さくらのクラウドAPIの利用方法など、一般的な情報についてはAPIドキュメントを参照ください。
 請求関連の機能についてもエンドポイントやサンプルといった情報もこちらのページで紹介しています。

API URL

請求関連APIを利用する際のベースURLは以下より任意のものを使用します。

https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1a/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/is1b/api/system/1.0/
https://secure.sakura.ad.jp/cloud/zone/tk1v/api/system/1.0/

※リソースの制御に使用するAPIとはベースURLのバージョン部分が異なりますのでご注意ください。
※請求情報はゾーンによらずアカウント単位での合算となるため、どのURLに対してリクエストを行っても同じ結果を返します。

注意事項

・請求データは、当月分は翌日、毎月の確定分は月が明けた翌月1日作成されます
・請求データが更新されていない場合は時間をおいて再度取得してください
・請求関連APIを実行するためには、APIキーに「請求情報」の権限が付与され、「リソース閲覧」以上のアクセスレベルが必要になります。詳細は、アクセスレベルのページをご覧ください。

2.使用例

新たに請求情報の取得を専用に行うAPIキーを発行し、API経由で請求明細を取得するまでの使用例を解説します。

手順内で使用するパラメータは以下の通りです。

パラメータ 説明
会員ID さくらインターネットの会員IDです。
例:nnn00000
請求書ID 毎月の請求書に採番される請求書をユニークに特定可能なIDとなります。請求書IDはアカウントごとに発番されます。
例:000000000
アクセストークン APIキーのアクセストークンです。
例:ACCESS_TOKEN と表示しています。
アクセストークンシークレット APIキーのアクセストークンシークレットです。
例:ACCESS_TOKEN_SECRET と表示しています

APIキーの作成

コントロールパネル上部にある[設定]をクリックします。
請求関連API コンパネ1

設定サブメニュー内の[APIキー]をクリックします。API管理画面が表示され、作成済みのAPIキーがある場合は一覧表示されます。
請求関連API APIキーをクリック

今回は請求情報取得用のAPIキーを新たに作成するので、右上の[追加]をクリックします。
請求関連API 作成をクリック

請求情報取得専用APIキーとして必要最低限の権限とするため、アクセスレベルは「リソース閲覧」、他サービスへのアクセス権の「請求情報」にチェックを入れたのみの状態を選択し、[作成]ボタンをクリックします(名前や説明欄には今回作成したAPIキーであることが分かりやすい名称を入力しておきます)。
請求関連API APIキー作成画面

一覧画面に今回作成したAPIキーが表示されるので、このAPIキーをダブルクリックします。
請求関連API APIキー一覧

詳細画面が表示され、実際のAPIアクセス時に必要となる「ACCESS_TOKEN」と「ACCESS TOKEN SECRET」が表示されます。
請求関連API キー確認画面

※アカウントが複数ある場合は、アカウントごとにAPIキーを作成する必要があります。

アカウントのリソースIDの取得

請求情報をAPIで確認するには、自身のアカウントIDが必要です。アカウントIDは以下の操作で事前に確認しておきます。以下のコマンド例ではcurlコマンドでAPIサーバに問い合わせを行い、応答結果をjqコマンドで見やすく整形します。

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq .

APIサーバからのレスポンスは以下のようになります。

{
	"is_ok": true,
	"Member": {
		"Errors": null,
		"Code": "xxx000001",
		"Class": "sakura"
	},
	"User": null,
	"AuthMethod": "apikey",
	"AuthClass": "account",
	"Permission": "create",
	"ExternalPermission": "bill",
	"RESTFilter": null,
	"IsAPIKey": true,
	"OperationPenalty": "none",
	"Account": {
		"Code": "billTest",
		"Name": "APIテスト用",
		"Class": "account",
		"ID": "000000526782"
	}
}

こちらのレスポンス末尾にある

"ID": "000000526782"

の数字部分がアカウントIDとなります。

※jqコマンドでは以下のようにキーの絞り込みを行うことが可能です。この機能によりアカウントIDのみ出力し、容易に確認することができます。

$ curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/cloud/1.1/auth-status | jq -c " .Account "

APIサーバからのレスポンスは以下のようになります。

{"Code":"billTest","Name":"APIテスト用","Class":"account","ID":"000000526782"}

過去の請求履歴を確認する

過去の請求履歴を表示します。APIのエンドポイントには/bill/by-contract/:accountidを使用します。

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/bill/by-contract/112700526782 | jq .

APIサーバからのレスポンスは以下のようになります。

{
	"is_ok": true,
	"ResponsedAt": "2016-06-01T13:33:13+09:00",
	"Count": 12,
	"Bills": [{
			"PaymentClassID": 200,
			"PayLimit": "2016-06-30T00:00:00+09:00",
			"Paid": false,
			"MemberID": "xxx000001",
			"Date": "2016-06-10T00:00:00+09:00",
			"BillID": 13481639,
			"Amount": 4330
		}, {
			"PaymentClassID": 200,
			"PayLimit": "2016-05-31T00:00:00+09:00",
			"Paid": true,
			"MemberID": "xxx000001",
			"Date": "2016-05-10T00:00:00+09:00",
			"BillID": 13327977,
			"Amount": 4330
		},
		.....
	}
}

レスポンスに含まれる主なキーの内容は以下の通りです。

キー名 説明
Date ISO 8601形式の請求年月
例:2016-05-10T00:00:00+09:00
Amount 請求金額(税込の日本円)
例:4330
BillID 請求書ID。さらに詳細を見る場合に使用します。
例:13327977

請求書IDから請求明細を取得する

請求書IDから請求明細を取得する場合は、APIのエンドポイントに/billdetail/:membercd/:billnoを使用します。

問い合わせ時に使用するパラメータは以下の通りです。

URLパラメータ 説明
membercd 取得したい請求書の会員ID
billno 処理対象となる請求書NO

パラメータを、会員IDと、先ほど調べた請求書NOに置換して実行します。

$ curl --user "ACCESS_TOKEN":"ACCESS_TOKEN_SECRET" https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000 | jq .

APIサーバからのレスポンスは以下のようになります。

{
	"is_ok": true,
	"ResponsedAt": "2016-06-01T13:39:54+09:00",
	"Count": 3,
	"BillDetails": [{
		"Usage": 2592000,
		"ServiceClassID": 50000,
		"Index": 1,
		"ContractID": "112700526782",
		"Amount": 0
	}, {
		"Usage": 2592000,
		"ServiceClassID": 50118,
		"Index": 2,
		"ContractID": "112700654736",
		"Amount": 108
	}, {
		"Usage": 2474113,
		"ServiceClassID": 50295,
		"Index": 3,
		"ContractID": "112700675125",
		"Amount": 540
	}]
}

レスポンスに含まれる主なキーの内容は以下の通りです。

請求明細項目 説明
Usage 詳細ごとの利用時間(秒)または利用量
ServiceClassID 明細に対応する契約ID
Index 同じ明細情報内における並び順
ContractID 詳細に対応する契約ID
Amount 詳細ごとの請求金額

請求明細をCSVで取得する

請求明細をCSV形式で取得する手順です。なお、CSV形式の請求明細はコントロールパネル右上の「請求情報」をクリックして表示される請求情報表示画面から取得することも可能です。

$ printf "`curl --user 'ACCESS_TOKEN':'ACCESS_TOKEN_SECRET' https://secure.sakura.ad.jp/cloud/zone/tk1a/api/system/1.0/billdetail/xxx000001/000000000/csv | jq .Body`"

APIサーバからのレスポンスは以下のようになります。

""連番","請求書番号","利用年月","支払いステータス","会員ID","アカウントコード","リソースID","商品ID","商品名","ゾーンID","ゾーン名","日数","時間","商品金額(税別)","税金","リソース名"
"1","000000000","2015/09","入金済み","xxx000001","payTest","112700526782","50000","さくらのクラウド",,,"30","0","0","0",
"2","000000000","2015/09","入金済み","xxx000001","payTest","112700654736","50118","ISOイメージアップロード/5GB","is1b","石狩第2ゾーン","30","0","100","8","名称未設定 ISOイメージ 14ef10fedac"
"3","000000000","2015/09","入金済み","xxx000001","payTest","112700675125","50295","GSLB",,,"28","16","500","40","テスト"
"

各フィールドの内容は以下の通りです。

連番 同一の請求書番号内での連番
請求書番号 請求書は会員ID内のアカウントコードごとに発行されます。すべてのゾーンが含まれます。
利用年月 請求対象の利用年月
支払いステータス 未入金、支払済み、ペンディングの3種類があります。未請求の月はペンディング状態となります。
会員ID 会員ID
アカウントコード アカウントコード
リソースID 使用されるリソースに割り振られるユニークな値です。請求書番号と組みあわせるとユニークなキーとなります。
商品ID 商品に割り当てられるIDとなります。同じ商品でも商品IDはゾーンごとに異なります。商品名は料金表から取得ください。
商品名 商品名が記載されます。ゾーンが異なる場合など、同一の商品名でも商品IDが異なる場合があります。ご注意ください。
ゾーンID ゾーンに割り振られたIDになります。グローバルなリソースの場合は空欄となります。
ゾーン名 ゾーンに割り振られたゾーン名称が記載されます。グローバルなリソースの場合は空欄となります。
日数 何日利用したかが表示されます。日割りのある商品の場合、20日以上利用すると月額となります。当月の請求はダウンロード当日の0時を基準に計算されています。
時間 利用した時間を24時間で割ったあまりの時間が表示されます。当月の請求はダウンロード当日の0時を基準に計算されています。
商品金額(税別) 税別の商品料金
税金 消費税の金額
リソース名 サーバの場合はサーバ名など、リソースにお客様が設定した名前が記載されます。
お電話でのお問い合わせ

0120-380-397

カスタマーセンター 受付時間:平日10:00〜18:00

※さくらのクラウドについてのお問い合わせは、音声ガイダンスにて[6]番をご選択下さい。