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

2.5 使用量クエリ

機能説明

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

使用シーン：

• 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. API Key が正しいか
2. Base URL が正しいか
3. ネットワークがアクセス可能か
4. タイムアウト時間が十分か

返却データが空

確認事項：

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

フォーマット失敗

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

注意事項

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