cc-switch/docs/user-manual/ja/2-providers/2.5-usage-query.md

# 2.5 使用量クエリ

CC Switch のクォータ・残高表示は 2 つのカテゴリに分かれます：**自動クエリ**（公式サブスクリプション系、すぐに使える）と **手動有効化**（内蔵テンプレート + カスタムスクリプト、ユーザー設定後に表示）。

| カテゴリ                           | 範囲                                                                              | ユーザー操作必要 |
| ---------------------------------- | --------------------------------------------------------------------------------- | ---------------- |
| **自動クエリ**                     | Claude / Codex / Gemini 公式サブスクリプション、GitHub Copilot、Codex OAuth リバースプロキシ | 不要（デフォルト有効） |
| **手動有効化（内蔵テンプレート）** | Token Plan、第三者残高クエリ                                                      | 必要（下記参照） |
| **手動有効化（カスタムスクリプト）** | 内蔵テンプレート未対応の中継サービス、プライベートデプロイ、特殊 API            | 必要（下記参照） |

## 自動クエリ（公式サブスクリプション系）

v3.13.0 より、以下の 3 カテゴリはプロバイダー有効化後に **自動的** にカード下部にクォータが表示され、追加設定は不要です：

| カテゴリ               | 対象プロバイダー                              | 表示内容                             |
| ---------------------- | --------------------------------------------- | ------------------------------------ |
| 公式サブスクリプション | Claude / Codex / Gemini 公式ログイン          | 公式サブスクリプションクォータ       |
| GitHub Copilot         | Copilot プロバイダーカード                    | Premium interactions 残量            |
| Codex OAuth            | Codex OAuth リバースプロキシカード（Claude プロバイダー） | ChatGPT アカウント Codex クォータ |

これら 3 カテゴリの共通点は、**データソースが唯一かつ意味が明確** であることです（公式サブスクリプションの使用率）。そのため CC Switch は対応する公式または OAuth クエリエンドポイントを直接呼び出します。

### 自動クエリの操作

- **カード下部表示**：使用率 + リセットまでのカウントダウン、使用率に応じて色が変化（< 70% 緑 / 70–89% オレンジ / ≥ 90% 赤）
- **手動更新**：カード上の更新アイコンをクリックして再取得
- **カードの簡略化**：これら 3 カテゴリでは、**ヘルスチェック** と **使用量クエリ設定** ボタンが自動的に非表示となり、内蔵表示への干渉を防ぎます
- **セッション期限切れ通知**：Token の更新に失敗した場合、カードに黄色の「セッション期限切れ」警告が表示されます（Copilot / Codex OAuth）

---

## 手動有効化（内蔵テンプレート + カスタムスクリプト）

上記 3 カテゴリの自動クエリ対応プロバイダー以外、**その他すべてのプロバイダー**（Token Plan、第三者残高クエリ、各種中継サービスを含む）では、プロバイダーカード上で **手動で「使用量クエリ」スイッチをオン** にして初めてクォータが表示されます。

### なぜ手動有効化が必要なのか？

重要な理由の一つは：**同じリクエスト URL（同じベンダー）が複数のクエリモードを提供している場合がある** ことです —— プランごとのクォータクエリと、アカウント残高クエリの両方が存在する可能性があります。CC Switch はどちらをクエリすべきか自動判定できないため、このようなプロバイダーの内蔵クエリは **デフォルトで無効** になっており、適切なテンプレートを選択してから有効化する必要があります。

### 内蔵テンプレートの対象範囲

v3.13.0 では以下のカテゴリに **すぐに使える内蔵テンプレート** を提供しており、有効化後にスクリプトを書く必要はありません：

| カテゴリ        | 対象プロバイダー                                          | テンプレートタイプ        |
| --------------- | --------------------------------------------------------- | ------------------------- |
| Token Plan      | Kimi / Zhipu GLM / MiniMax                                | プランクォータ（使用進捗付き） |
| 第三者残高      | DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita AI | 公式残高クエリ            |

> **ヒント**：上記の内蔵テンプレート以外で対象外のプロバイダーには、**カスタムスクリプト** 方式（下記参照）で独自のクエリロジックを記述できます。

### 有効化手順

1. プロバイダーカードにマウスをホバーして操作ボタンを表示
2. **使用量クエリ** ボタン（📊 アイコン）をクリック
3. 設定パネル上部の **使用量クエリを有効にする** スイッチをオンにする
4. 適切な内蔵テンプレート（Token Plan、第三者残高など）または「カスタム」を選択
5. 必要に応じて API Key / Base URL / Access Token などのパラメータを入力（多くの場合は空欄のままプロバイダー自身の認証情報を使用可能）
6. 「スクリプトをテスト」をクリックして正常に応答するか確認
7. 設定を保存 —— 次回プロバイダーを有効化すると、カード下部にクォータが表示されます

> ⚠️ **注意**：有効化後の自動更新間隔は「自動クエリ間隔」フィールドで制御します（`0` に設定すると自動更新を無効化）。プロバイダーが「現在有効」状態のときのみバックグラウンドクエリがトリガーされます。

---

## カスタムスクリプトクエリ（高度）

### 機能説明

プロバイダーが **内蔵テンプレートの対象範囲外** の場合、JavaScript でカスタムクエリスクリプトを記述できます。中継サービス、プライベートデプロイ、特殊な API 形式などに適しています。

**使用シーン**：
- 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. プロバイダーが公式サブスクリプション系であることを確認 —— Claude / Codex / Gemini 公式ログイン、GitHub Copilot、Codex OAuth リバースプロキシ
2. プロバイダーが「現在有効」状態か（非アクティブ時はクエリがトリガーされません）
3. OAuth タイプ（Copilot / Codex OAuth）の場合、Token がまだ有効期限内か確認。カードに「セッション期限切れ」と表示される場合は **OAuth 認証センター** で再ログインしてください
4. 公式クォータエンドポイントへのネットワークアクセス可否

### 手動有効化後もクォータが表示されない

**確認事項**：
1. プロバイダーカードの「使用量クエリ」パネル上部にある **使用量クエリを有効にする** スイッチがオンか
2. 適切な内蔵テンプレート（Token Plan / 第三者残高 / カスタム）が選択されているか
3. 「スクリプトをテスト」をクリックして具体的なエラー情報を確認
4. API Key / Base URL などの必須フィールドが正しく入力されているか
5. プロバイダーのクォータエンドポイントへのネットワークアクセス可否
6. プロバイダーが「現在有効」状態のときのみ、バックグラウンドの自動更新がトリガーされます

### クエリ失敗

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

### 返却データが空

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

### フォーマット失敗

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

## 注意事項

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