アカウント

複数の clientKey：上限、IP 許可リスト、有効期限

このページは中国語版から機械翻訳されたもので、不正確な箇所がある可能性があります。中国語版を正としてください。

1 つの YesCaptcha アカウントには、最大 20 個の clientKey（元からある 1 つを含む）を持てます。yescaptcha.com ダッシュボードの「キーとセキュリティ」ページで管理します。どの clientKey でもタスクの作成と残高の確認ができ、課金されるのはすべて同じアカウント残高です。それぞれに利用上限、IP 許可リスト、有効期限を個別に設定でき、数秒で反映されます。

次のような場合に便利です。テスト環境と本番環境、プロジェクトごとにキーを分ける。下流の顧客やパートナーにキーを渡し、それぞれに上限を設ける。ある clientKey が漏えいしても、そのキーだけを削除すれば、ほかのプログラムには影響しません。

メイン Key とサブ Key

	メイン Key	サブ Key
内容	元からある `clientKey`。アカウントに 1 つ	メイン Key とは別に作成したキー。最大 19 個
上限、IP 許可リスト、有効期限	設定できる	設定できる
リセット	できる：古いキーはすぐ無効になり、残高は新しいキーに移る	できない。削除して作り直す
削除	できない	できる：数秒で無効になり、元に戻せない

形式はどれも同じです。先頭 40 文字がシークレットで、その後ろにユーザー ID が続きます。
メイン Key をリセットしても、サブ Key には影響しません。
タスクの作成や残高の確認にどの clientKey を使っても、API とレスポンスは同じです。違いは、上限・許可リスト・有効期限のチェックが加わる点だけです。

clientKey を作成する

yescaptcha.com にログインし、「キーとセキュリティ」ページ（yescaptcha.com/security）を開きます。
「すべての Key」で「サブ Key を作成」をクリックします。名前（最大 40 文字）、上限、IP 許可リスト、有効期限はいずれも省略でき、後から変更もできます。
案内に従って、もう一度本人確認を行います。作成・変更・削除のいずれにも本人確認が必要です。
作成後、完全な clientKey をコピーしてプログラムに設定します。後から、一覧の目のアイコンをクリックして再表示することもできます。

利用上限

上限は、1 つの clientKey が 1 つの期間内に使えるポイントの最大値です（1,000 ポイント = ¥1）。1 から 10,000,000,000 ポイントまで設定できます。期間は 4 種類で、北京時間（UTC+8）でリセットされます。

期間	リセットのタイミング
毎日	毎日 0 時
毎週	毎週月曜 0 時
毎月	毎月 1 日 0 時
一括の合計	リセットされません。使い切ると、この `clientKey` ではタスクを作成できなくなります。引き続き使うには上限を引き上げてください

実際に課金されたポイントで計算します。認識の失敗やタイムアウトで返金されたポイントは、上限にも戻ります。
今の期間の残り上限がタスクの課金額に足りない場合、createTask は ERROR_KEY_QUOTA_EXCEEDED を返します。課金されず、自動一時停止にもカウントされません。
ダッシュボードの一覧で、各 clientKey が今の期間にどれだけ使ったか、次にいつリセットされるかを確認できます。
上限は独立した残高ではありません。すべての clientKey が同じアカウント残高から課金され、アカウント残高が足りないときは通常どおり ERROR_ZERO_BALANCE が返ります。

上限を設定した clientKey で getBalance を呼ぶと、balance にはアカウント残高と今の期間の残り上限のうち小さいほうが入り、さらに keyQuotaRemaining（残りの上限、ポイント）が加わります。上限を設定していない clientKey にはこのフィールドは付かず、レスポンスは従来と同じです。

{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}

IP 許可リスト

IP 許可リストを設定した clientKey は、リストにある IP から送信されたリクエストだけが使えます。空欄にすると制限しません。

登録するのは YesCaptcha の API を呼び出すマシンのパブリック IP（送信元 IP）です。タスクのパラメータにあるプロキシではありません。複数のマシンから呼び出す場合は、すべてのパブリック IP を追加してください。
1 行に 1 つ、IPv4 または IPv6 アドレス、もしくは CIDR 範囲を書きます。最大 50 件です。アドレス 1 つだけの場合は、その IP のみを許可します。
範囲はネットワークアドレスで書きます。203.0.113.0/24 は使えますが、203.0.113.5/24 は使えません（ホスト部が 0 ではないため）。

203.0.113.10
198.51.100.0/24
2001:db8::/32

リクエストの IP がリストにない場合、createTask と getBalance は ERROR_KEY_IP_NOT_ALLOWED を返します。課金されず、自動一時停止にもカウントされません。
送信元 IP が変わる環境（家庭用ブロードバンド、クラウド関数、ローテーションする送信元など）では設定しないか、範囲全体を許可してください。

有効期限

どの clientKey（メイン Key を含む）にも有効期限を設定できます。10 年以内の日時を指定します。その後はいつでも変更したり、削除したりできます。
期限が切れると、そのキーでの createTask と getBalance は ERROR_KEY_EXPIRED を返し、課金されません。すでに作成済みのタスクは、これまでどおり getTaskResult で結果を取得できます。
長期間使われていない clientKey には、アカウントの安全を守るため、システムが有効期限を設定し、期限の前にメールでお知らせします。この有効期限は変更できません。メイン Key を再生成する（残高は自動的に新しいキーに移ります）か、新しい clientKey を作成して、プログラムを更新してください。

残高、同時実行数の上限、自動一時停止

残高：すべての clientKey が同じアカウント残高から課金されます。チャージ、VIP のチャージボーナス、紹介報酬、開発者収益分配はすべてアカウント単位で、どの clientKey を使うかは関係ありません。
同時実行数の上限：アカウント単位で計算され、すべての clientKey が同じ上限を共有します。詳しくは同時実行数の上限と自動一時停止を参照してください。
自動一時停止：clientKey ごとに計算されます。ある clientKey がエラーの多さで一時停止されても、ほかのキーには影響しません。

エラーコード	返されるタイミング
`ERROR_KEY_QUOTA_EXCEEDED`	今の期間の残り上限がこのタスクの課金額に足りない（`createTask`）
`ERROR_KEY_IP_NOT_ALLOWED`	リクエストの IP がこの `clientKey` の IP 許可リストにない（`createTask`、`getBalance`）
`ERROR_KEY_EXPIRED`	`clientKey` の有効期限が切れている（`createTask`、`getBalance`）