청구 과금 항목 소비 누적 조회¶
GET /api/v1/billing/project/summary
개요¶
현재 워크스페이스 청구 센터의 과금 항목 누적 소비 요약을 조회합니다.
호출 전 및 사용 단계¶
대상 워크스페이스의 API Key를 사용합니다. Key가 속한 워크스페이스에 대응하는 청구 센터 사이트의 데이터만 조회할 수 있으며, 추가 workspaceUUID/brandKey/사이트 매개변수로 전환할 수 없습니다. 이 인터페이스는 과금, 충전, 정산 또는 요금제 변경을 수행하지 않습니다. 청구 센터 데이터에는 생성 또는 정산 지연이 있을 수 있으므로 빈 결과가 소비가 발생하지 않았음을 의미하지 않습니다. 실제 청구 기간과 청구 센터를 함께 확인하세요. 금액, 통화, 정밀도 및 통계 기준은 해당 워크스페이스의 청구 센터를 따르며, Studio는 환산하거나 통화 필드를 보완하지 않으므로 예시 값을 가격으로 간주해서는 안 됩니다.
billing.billingRead 또는 billing.workspaceUpgrade 권한 중 하나가 필요합니다. 이 진입점에는 날짜/페이지네이션/과금 항목 필터 매개변수가 없습니다. 통계 주기는 청구 센터 요약 인터페이스에서 결정되므로 지정된 날짜 범위 집계 또는 이번 달 고정 집계로 간주할 수 없습니다. content의 과금 항목 이름은 업스트림 동적 키이며, 예시에는 두 항목만 표시됩니다. 전체 항목 집합을 하드코딩하거나 이름으로 요금제 개통 여부를 판단하지 마세요. 비어 있지 않은 딕셔너리에는 워크스페이스 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/비즈니스 code로 덮어씁니다. 이 SDK에는 패스스루 플래그가 설정되어 있지 않으므로 최종 code가 500 이상이면 전역에서 HTTP 500, ft.InternalServerError 및 일반 텍스트로 래핑되며, 외부에 503 또는 원본 5xx 메시지가 유지된다고 가정할 수 없습니다. 최종 code가 500 미만이면 CloudCareApiError와 실제 message가 유지됩니다. 연결 예외는 기본적으로 400입니다. 여기서는 확인된 Studio 매핑만 나열하며, 청구 센터의 각 비즈니스 오류나 프록시 오류를 모두 열거하지는 않습니다.
| HTTP 상태 | errorCode | 트리거 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 404 | ft.ObjectNotExists | 현재 Key에 해당하는 워크스페이스 레코드를 찾을 수 없음 | 지정한 객체가 존재하지 않습니다 | 대상 워크스페이스와 Key의 유효 상태를 확인합니다. |
| 406 | ft.InvalidBossNode | 워크스페이스에 바인딩된 청구 센터 브랜드/노드가 구성되지 않았거나 사용할 수 없음 | 유효하지 않은 Boss 노드 | 관리자에게 문의하여 워크스페이스 청구 센터 바인딩 및 사이트 구성을 확인하고, 날짜를 변경하여 우회하지 마세요. |
| 400 | ft.CloudCareApiError | 청구 센터 요청 연결 실패(기본 400) 또는 매핑 후 code가 500 미만인 업스트림 HTTP/비즈니스 오류 | 내부 인터페이스 호출 실패 | HTTP, message, traceId를 유지하고 청구 센터 가용성 및 구체적인 오류를 확인합니다. 최종 4xx는 달라질 수 있으며, code가 500 이상이면 전역에서 ft.InternalServerError로 래핑됩니다. |
| 500 | ft.InternalServerError | 청구 센터가 예상하지 못한 유형/필드 누락, 유효하지 않은 JSON 또는 기타 저장 및 형식 지정 오류를 반환함 | 내부 오류 | traceId를 유지하여 관리자에게 문의하고 업스트림 응답을 확인한 후, 잠시 후 다시 조회하여 재시도합니다. |