# 2.5 使用量クエリ

## 機能説明

使用量クエリ機能により、カスタムスクリプトを設定して、プロバイダーの残額や使用量などの情報をリアルタイムでクエリできます。

**使用シーン**：
- API アカウントの残額確認
- プランの使用状況の監視
- 複数プランの残額を集約表示

## 設定を開く

1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. 「使用量クエリ」ボタンをクリック
3. 使用量クエリ設定パネルが開く

## 使用量クエリの有効化

設定パネル上部の「使用量クエリを有効にする」スイッチをオンにします。

## プリセットテンプレート

CC Switch は 3 種類のプリセットテンプレートを提供しています：

### カスタムテンプレート

リクエストと抽出ロジックを完全にカスタマイズします。特殊な API 形式に対応します。

### 汎用テンプレート

ほとんどの標準的な API 形式のプロバイダーに適しています：

```javascript
({
  request: {
    url: "{{baseUrl}}/user/balance",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "User-Agent": "cc-switch/1.0"
    }
  },
  extractor: function(response) {
    return {
      isValid: response.is_active || true,
      remaining: response.balance,
      unit: "USD"
    };
  }
})
```

**設定パラメータ**：
| パラメータ | 説明 |
|------|------|
| API Key | 認証用のキー（任意、空欄の場合はプロバイダーに設定されたキーを使用） |
| Base URL | API ベースアドレス（任意、空欄の場合はプロバイダーのエンドポイントを使用） |

### New API テンプレート

New API タイプの中継サービス専用に設計されています：

```javascript
({
  request: {
    url: "{{baseUrl}}/api/user/self",
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "New-Api-User": "{{userId}}"
    },
  },
  extractor: function (response) {
    if (response.success && response.data) {
      return {
        planName: response.data.group || "デフォルトプラン",
        remaining: response.data.quota / 500000,
        used: response.data.used_quota / 500000,
        total: (response.data.quota + response.data.used_quota) / 500000,
        unit: "USD",
      };
    }
    return {
      isValid: false,
      invalidMessage: response.message || "クエリ失敗"
    };
  },
})
```

**設定パラメータ**：
| パラメータ | 説明 |
|------|------|
| Base URL | New API サービスアドレス |
| Access Token | アクセストークン |
| User ID | ユーザー ID |

## 共通設定

### タイムアウト時間

リクエストのタイムアウト時間（秒）、デフォルトは 10 秒。

### 自動クエリ間隔

使用量データの自動更新間隔（分）：
- `0` に設定すると自動クエリを無効化
- 範囲：0-1440 分（最長 24 時間）
- プロバイダーが「現在有効」のときのみ動作

## エクストラクターの戻り値形式

エクストラクター関数は以下のフィールドを含むオブジェクトを返す必要があります：

| フィールド | 型 | 必須 | 説明 |
|------|------|------|------|
| `isValid` | boolean | いいえ | アカウントが有効かどうか、デフォルト true |
| `invalidMessage` | string | いいえ | 無効時の通知メッセージ |
| `remaining` | number | はい | 残額 |
| `unit` | string | はい | 単位（例：USD、CNY、回） |
| `planName` | string | いいえ | プラン名（複数プラン対応） |
| `total` | number | いいえ | 総額 |
| `used` | number | いいえ | 使用済み額 |
| `extra` | object | いいえ | 追加情報 |

## スクリプトのテスト

設定完了後、「スクリプトをテスト」ボタンをクリックして確認します：

1. 設定された URL にリクエストを送信
2. エクストラクター関数を実行
3. 結果またはエラー情報を表示

## 表示効果

設定が成功すると、プロバイダーカードに以下が表示されます：

- **単一プラン**：残額を直接表示
- **複数プラン**：プラン数を表示、クリックで詳細を展開

## 変数プレースホルダー

スクリプト内で以下のプレースホルダーを使用でき、実行時に自動的に置換されます：

| プレースホルダー | 説明 |
|--------|------|
| `{{apiKey}}` | 設定された API Key |
| `{{baseUrl}}` | 設定された Base URL |
| `{{accessToken}}` | 設定された Access Token（New API） |
| `{{userId}}` | 設定された User ID（New API） |

## 一般的なプロバイダーの設定例

### トラブルシューティング

### クエリ失敗

**確認事項**：
1. API Key が正しいか
2. Base URL が正しいか
3. ネットワークがアクセス可能か
4. タイムアウト時間が十分か

### 返却データが空

**確認事項**：
1. エクストラクター関数に `return` 文があるか
2. レスポンスのデータ構造がエクストラクターと一致しているか
3. 「スクリプトをテスト」で生のレスポンスを確認

### フォーマット失敗

スクリプトに構文エラーがある場合、「フォーマット」ボタンをクリックするとエラー箇所が表示されます。

## 注意事項

- 使用量クエリは少量の API リクエスト枠を消費します
- 頻繁なリクエストを避けるため、適切な自動クエリ間隔を設定してください
- 機密情報（API Key、Token）はローカルに安全に保存されます