Usage Query API

Object Storage Usage Query APIは、詳細な利用状況および請求データへのプログラムによるアクセスを提供します。パートナーやリセラーがサブアカウントまたは個別バケット単位で消費監視を自動化できるように設計されています。

概要

本APIは、以下を含む幅広い使用状況メトリクスを取得できます：

• ストレージ利用量：標準、低頻度アクセス、アーカイブストレージクラス。
• リクエスト数：読み取りおよび書き込みリクエスト。
• データ取得：低頻度アクセスおよびアーカイブ階層のトラフィック。
• トラフィックおよび帯域幅：CDNオリジントラフィック、エグレストラフィック、リージョン間レプリケーショントラフィック。
• ファイル操作: ファイル操作の総数。

エンドポイント詳細

すべてのリクエストはPOSTメソッドを使用して本番エンドポイントに送信してください。

• メソッド: POST
• 本番URL: https://wos.cdnetworks.com/api/usage/statistics

注意: 本番環境ではHTTPSが必要です。HTTP経由のリクエストはリダイレクトされ、失敗する場合があります。

APIリクエストのワークフロー

1. 前提条件：シークレットなapikeyを生成し、サポートチームに提供してバックエンド側で設定してください。
2. 認証：リクエストに必要なDateおよびAuthorizationヘッダーを作成します。
3. リクエスト：希望するクエリパラメーターでJSON形式のリクエストボディを作成します。
4. 実行：本番エンドポイントに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. 認可文字列を構築する:
   • ユーザー名:パスワードという形式の文字列を作成します。
   • ユーザー名:パスワード全体の文字列をBase64エンコードします。
4. 認可ヘッダーを設定する: 最終的なヘッダー値は、Basic の後ろに前のステップでBase64エンコードされた文字列を連結したものです。
   • フォーマット: Authorization: Basic <Base64(ユーザー名:パスワード)>

データ単位

APIは、メトリックタイプに基づいて特定の単位で使用量データを返します:

• ストレージメトリクス（storageSize）：**メガバイト（MB）**で返却され、**2進法（base-1024）**で計算されます（1 MB = 1024 KB）。
• トラフィックおよび帯域幅メトリクス（outTraffic、innerBandwidthなど）：**メガバイト（MB）およびメガビット毎秒（Mbps）で返却され、それぞれ10進法（base-1000）**で計算されます。
• リクエストおよび操作回数：整数で返却されます。

ヘッダー

リクエストボディパラメータ

統計タイプ（statisticsType）

使用例

例1：要約ストレージ使用状況の照会

このリクエストは、米国およびシンガポールリージョンの標準ストレージに関する一日の合計ピークストレージサイズを照会します。

リクエスト：

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の値は、1日あたりのピーク値（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)