Usage Query API

Object Storage Usage Query API는 상세한 사용량 및 청구 데이터를 프로그래밍 방식으로 조회할 수 있는 기능을 제공합니다. 파트너 및 리셀러가 하위 계정 또는 개별 버킷 단위로 소비 모니터링을 자동화하는 데 도움을 주기 위해 설계되었습니다.

개요

API는 다양한 사용 메트릭을 조회할 수 있습니다. 주요 항목은 다음과 같습니다:

• 스토리지 사용량: Standard, Infrequent Access, 및 Archive 스토리지 클래스.
• 요청 수: 읽기 및 쓰기 요청.
• 데이터 조회: Infrequent Access 및 Archive 티어의 Traffic.
• Traffic 및 Bandwidth: CDN Origin Traffic, Egress Traffic, 및 Cross-Region Replication Traffic.
• 파일 작업: 파일 작업의 총 횟수.

엔드포인트 세부정보

모든 요청은 POST 메서드를 사용하여 프로덕션 엔드포인트로 전송해야 합니다.

• 메서드: POST
• 프로덕션 URL: https://wos.cdnetworks.com/api/usage/statistics

참고: 프로덕션 환경에서는 HTTPS가 필요합니다. HTTP를 통한 요청은 리디렉션될 수 있으며, 실패할 수 있습니다.

API 요청 흐름

1. 사전 조건: 비밀 apikey를 생성하고, 백엔드 구성을 위해 지원팀에 제공해 주세요.
2. 인증: 요청에 필요한 Date 및 Authorization 헤더 값을 구성하세요.
3. 요청: 원하는 쿼리 파라미터로 JSON 요청 본문을 생성하세요.
4. 실행: 실제 환경 Endpoint로 POST 요청을 전송하세요.
5. 응답: JSON 응답을 파싱하여 사용량 데이터를 확인하세요.

인증

API는 커스텀 HMAC-SHA256 인증 방식을 사용합니다. 모든 API 요청에는 Date 및 Authorization 헤더가 포함되어야 합니다.

API를 사용하려면 username과 apikey가 필요합니다. apikey는 사용자가 직접 생성하는 비밀 키입니다. API 접근을 활성화하려면 해당 키를 지원팀에 제공하여 백엔드 설정을 완료해야 합니다.

인증 절차

1. 현재 시간 확인: 현재 시간을 RFC1123 규격에 맞게 포맷합니다(예: Thu, 21 Jul 2025 07:54:00 GMT). 이 문자열은 Date 헤더에 사용됩니다.
2. 서명 계산: apikey를 키로, Date 문자열을 메시지로 하여 HMAC-SHA256 서명을 생성합니다. 결과는 Base64로 인코딩해야 합니다.
   • 공식: password = Base64(HMAC-SHA256(UTF-8(apikey), UTF-8(Date)))
3. Authorization 문자열 생성:
   • username:password 형식의 문자열을 생성합니다.
   • 전체 username:password 문자열을 Base64로 인코딩합니다.
4. Authorization 헤더 설정: 최종 헤더 값은 Basic 문자열 다음에 이전 단계에서 Base64로 인코딩된 문자열을 붙인 값입니다.
   • 형식: Authorization: Basic <Base64(username:password)>

데이터 단위

API는 메트릭 유형에 따라 특정 단위의 사용량 데이터를 반환합니다:

• 스토리지 지표(storageSize): 메가바이트(MB) 단위로 반환되며, **2진법(base-1024)**으로 계산됩니다. 1MB = 1024KB입니다.
• 트래픽 및 대역폭 지표 (outTraffic, innerBandwidth 등): 메가바이트(MB) 및 메가비트/초(Mbps) 단위로 각각 반환되며, **10진법(base-1000)**으로 계산됩니다.
• 요청 및 작업 횟수: 정수로 반환됩니다.

헤더

요청 본문 파라미터

통계 유형(statisticsType)

사용 예시

예시 1: 저장소 사용량 요약 조회

이 요청은 미국(US) 및 싱가포르(SG) 지역의 표준 스토리지에 대한 일일 총 peak value 용량을 조회합니다.

요청:

curl -X POST \
  https://wos.cdnetworks.com/api/usage/statistics \
  -H 'Authorization: Basic YOUR_AUTH_STRING' \
  -H 'Date: Thu, 21 Jul 2025 07:54:00 GMT' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2025-07-10",
    "endDate": "2025-07-11",
    "storageRegion": "US,SG",
    "storageType": "Standard",
    "statisticsType": "storageSize"
}'

응답:

{
    "code": "200",
    "message": "OK",
    "statisticsType": "storageSize",
    "data": [
        {
            "dataTime": "2025-07-10",
            "storage": "5120"
        },
        {
            "dataTime": "2025-07-11",
            "storage": "5180"
        }
    ]
}

참고: storage 값은 일일 peak value(MB 기준)를 나타냅니다.

예시 2: 버킷별 요청 수 조회

이 요청은 버킷별로 구분된 일일 읽기 및 쓰기 요청 수를 조회합니다.

요청:

curl -X POST \
  https://wos.cdnetworks.com/api/usage/statistics \
  -H 'Authorization: Basic YOUR_AUTH_STRING' \
  -H 'Date: Thu, 21 Jul 2025 07:54:00 GMT' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2025-07-10",
    "endDate": "2025-07-11",
    "statisticsType": "numberOfRequests",
    "isGroupByBucket": "1"
}'

응답:

{
    "code": "200",
    "message": "OK",
    "statisticsType": "numberOfRequests",
    "data": [
        {
            "dataTime": "2025-07-10",
            "readRequests": {
                "bucket1": "15000",
                "bucket2": "25000"
            },
            "writeRequests": {
                "bucket1": "3000",
                "bucket2": "5000"
            }
        },
        {
            "dataTime": "2025-07-11",
            "readRequests": {
                "bucket1": "16500",
                "bucket2": "27500"
            },
            "writeRequests": {
                "bucket1": "3200",
                "bucket2": "5300"
            }
        }
    ]
}

오류 코드

Python 코드 예제

import datetime
import hmac
import base64
import requests
import json
from hashlib import sha256


class UsageApiDemo:
    def get_gmt_date(self):
        """현재 시간을 RFC1123 형식으로 생성합니다."""
        gmt_format = '%a, %d %b %Y %H:%M:%S GMT'
        return datetime.datetime.utcnow().strftime(gmt_format)


    def get_auth_string(self, username, apikey, date_str):
        """전체 'Authorization' 헤더 값을 생성합니다."""
        # 1단계: HMAC-SHA256 서명을 생성합니다.
        signature = hmac.new(apikey.encode('utf-8'), date_str.encode('utf-8'), sha256).digest()


        # 2단계: 서명을 Base64 인코딩하여 'password'를 생성합니다.
        password = base64.b64encode(signature).decode('utf-8')


        # 3단계: 'username:password' 문자열을 생성하고 Base64로 인코딩합니다.
        combined_str = f"{username}:{password}"
        encoded_auth_str = base64.b64encode(combined_str.encode('utf-8')).decode('utf-8')


        # 4단계: 최종 헤더 값을 생성하기 위해 'Basic '을 앞에 추가합니다.
        return f"Basic {encoded_auth_str}"


    def send_request(self, url, headers, body_params):
        """API에 POST 요청을 전송하고 응답을 출력합니다."""
        try:
            response = requests.post(url, data=json.dumps(body_params), headers=headers)
            response.raise_for_status()  # 잘못된 상태 코드에 대한 예외를 발생시킵니다


            print(f"상태 코드: {response.status_code}")
            print("응답 본문:")
            print(json.dumps(response.json(), indent=4))


        except requests.exceptions.RequestException as e:
            print(f"오류가 발생하였습니다: {e}")


if __name__ == '__main__':
    # --- 사용자 환경설정 ---
    USERNAME = 'your_username'
    APIKEY = 'your_apikey'
    API_HOST = 'https://wos.cdnetworks.com'
    API_URI = '/api/usage/statistics'


    # --- 요청 구성 ---
    api_demo = UsageApiDemo()


    # 1. 날짜 가져오기
    date_header = api_demo.get_gmt_date()


    # 2. 인증 정보 가져오기
    auth_header = api_demo.get_auth_string(USERNAME, APIKEY, date_header)


    # 3. 헤더 정의
    request_headers = {
        'Date': date_header,
        'Authorization': auth_header,
        'Content-Type': 'application/json'
    }


    # 4. 본문 정의
    request_body = {
        "startDate": "2025-04-01",
        "endDate": "2025-04-02",
        "statisticsType": "storageSize",
        "storageType": "Standard"
    }


    # 5. 요청 보내기
    full_url = API_HOST + API_URI
    api_demo.send_request(full_url, request_headers, request_body)