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 形式のプロバイダーに適しています：

({
  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 タイプの中継サービス専用に設計されています：

({
  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）はローカルに安全に保存されます