請求の課金項目消費累計を取得¶
GET /api/v1/billing/project/summary
概要¶
現在のワークスペースの請求センターにおける課金項目の累計消費サマリーを読み取ります。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。Key が属するワークスペースに対応する請求センターサイトのデータのみを読み取ることができ、追加の workspaceUUID/brandKey/サイトパラメータで切り替えることはできません。このインターフェースは、料金の引き落とし、チャージ、精算、プランの変更を行いません。請求センターのデータには生成または精算の遅延が発生する場合があり、空の結果は消費が発生していないことを意味しません。実際の請求期間と請求センターを照合してください。金額、通貨、精度、集計基準は、該当するワークスペースの請求センターに従います。Studio は換算や通貨フィールドの補完を行わず、例示された数値を価格として扱わないでください。
billing.billingRead または billing.workspaceUpgrade のいずれかの権限が必要です。このエントリには日付/ページネーション/課金項目のフィルタパラメータはありません。集計期間は請求センターのサマリーインターフェースによって決まり、指定した日付範囲の集計や当月の固定集計として扱うことはできません。content の課金項目名は上流の動的キーであり、例では 2 項目のみを示しています。項目の完全な集合をハードコードしたり、名前でプランの有効化を判断したりしないでください。空でない辞書にはワークスペースの declaration も含まれるため、金額を集計する際はこのメタデータキーを除外する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/billing/project/summary' \
-H 'DF-API-KEY: <DF-API-KEY>'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content | object | 請求センターの累計サマリーをそのまま返します。content が返されない場合、SDK は {} にフォールバックします。固定の課金項目リストではありません。 |
| content.<課金項目名> | JSON | 上流の動的項目および金額で、例では number です。キー名/値は上流が決定し、Studio はカテゴリの全集合、期間、単位を固定しません。 |
| content.declaration | object | 空でないサマリーの場合に付加されるワークスペース宣言であり、金額項目ではありません。空のオブジェクトにはこのフィールドはありません。 |
{
"code": 200,
"content": {
"Cumulative Consumption": 17211.88,
"Session Replay": 806.8,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
請求センター SDK はまず ft.CloudCareApiError にマッピングし、上流の HTTP/ビジネスコードで上書きします。この SDK にはパススルーフラグが設定されていないため、最終的なコードが 500 以上の場合、グローバルに HTTP 500、ft.InternalServerError、汎用テキストでラップされます。外部に対して 503 や元の 5xx メッセージが保持されると仮定することはできません。最終的なコードが 500 未満の場合は、CloudCareApiError と実際の message が保持されます。接続異常のデフォルトは 400 です。ここでは確認済みの Studio マッピングのみを記載し、請求センターの各ビジネスエラーやプロキシエラーを網羅するものではありません。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対応方法 |
|---|---|---|---|---|
| 404 | ft.ObjectNotExists | 現在の Key に対応するワークスペースレコードが見つからない | 指定されたオブジェクトが存在しません | 対象ワークスペースと Key の有効状態を確認してください。 |
| 406 | ft.InvalidBossNode | ワークスペースにバインドされた請求センターのブランド/ノードが未設定または利用不可 | 無効な Boss ノード | 管理者に連絡し、ワークスペースの請求センターのバインドとサイト設定を確認してください。日付を変更して回避しないでください。 |
| 400 | ft.CloudCareApiError | 請求センターへのリクエスト接続失敗(デフォルト 400)、またはマッピング後のコードが 500 未満の上流 HTTP/ビジネスエラー | 内部インターフェースの呼び出しに失敗しました | HTTP、message、traceId を保持し、請求センターの可用性と具体的なエラーを確認してください。最終的な 4xx は変動する可能性があり、コードが 500 以上の場合はグローバルに ft.InternalServerError でラップされます。 |
| 500 | ft.InternalServerError | 請求センターが想定外の型/欠落フィールド、無効な JSON、その他のストレージやフォーマットエラーを返す | 内部エラー | traceId を保持して管理者に連絡し、上流のレスポンスを確認してください。後で読み取りを再試行してください。 |