Mehrere ClientKeys: Limit, IP-Whitelist und Ablaufdatum

Ein YesCaptcha-Konto kann bis zu 20 clientKey haben (einschließlich des ursprünglichen). Sie verwalten sie im yescaptcha.com-Dashboard auf der Seite „Schlüssel & Sicherheit“. Jeder clientKey kann Aufgaben erstellen und das Guthaben abfragen, und alle buchen vom selben Konto-Guthaben ab. Jeder kann ein eigenes Limit, eine eigene IP-Whitelist und ein eigenes Ablaufdatum haben; Änderungen wirken innerhalb weniger Sekunden.

Typische Einsatzfälle: getrennte Keys für Test- und Produktivumgebung oder für verschiedene Projekte; Keys an eigene Kunden oder Partner weitergeben, jeweils mit eigenem Limit; und wenn ein clientKey offengelegt wird, löschen Sie nur diesen, ohne andere Programme zu beeinträchtigen.

Haupt-Key und Sub-Keys

	Haupt-Key	Sub-Key
Was es ist	Der ursprüngliche clientKey, einer pro Konto	Zusätzlich zum Haupt-Key angelegt, bis zu 19
Limit, IP-Whitelist, Ablaufdatum	Können gesetzt werden	Können gesetzt werden
Zurücksetzen	Ja: der alte wird sofort ungültig, das Guthaben wechselt zum neuen	Nein; löschen und einen neuen anlegen
Löschen	Nein	Ja: wird innerhalb weniger Sekunden ungültig und lässt sich nicht wiederherstellen

• Alle haben dasselbe Format: Die ersten 40 Zeichen sind der geheime Schlüssel, danach folgt Ihre Benutzer-ID.
• Das Zurücksetzen des Haupt-Keys betrifft die Sub-Keys nicht.
• Mit welchem clientKey Sie Aufgaben erstellen oder das Guthaben abfragen, die API und die Antworten sind gleich; es kommen nur die Prüfungen von Limit, IP-Whitelist und Ablaufdatum hinzu.

ClientKey anlegen

1. Melden Sie sich bei yescaptcha.com an und öffnen Sie die Seite „Schlüssel & Sicherheit“ (yescaptcha.com/security).
2. Klicken Sie unter „Alle Keys“ auf „Neuer Sub-Key“. Name (bis zu 40 Zeichen), Limit, IP-Whitelist und Ablaufdatum sind optional und können später geändert werden.
3. Bestätigen Sie Ihre Identität erneut, wenn Sie dazu aufgefordert werden. Anlegen, Ändern und Löschen erfordern dies jeweils.
4. Kopieren Sie den vollständigen clientKey und tragen Sie ihn in Ihr Programm ein. Sie können ihn später über das Augen-Symbol in der Liste erneut anzeigen.

Hinweis

Anlegen, Ändern und Löschen wirken innerhalb weniger Sekunden. Ein Aufruf direkt nach dem Anlegen kann ERROR_KEY_DOES_NOT_EXIST zurückgeben; warten Sie einige Sekunden und versuchen Sie es erneut. In den ersten Sekunden nach dem Löschen oder Verschärfen von Einstellungen können bereits gesendete Anfragen noch mit den alten Einstellungen verarbeitet werden.

Limit

Ein Limit begrenzt, wie viele Punkte ein clientKey pro Zeitraum höchstens ausgeben darf (1,000 Punkte = ¥1). Es kann zwischen 1 und 10,000,000,000 Punkten liegen. Es gibt vier Zeiträume, die nach Pekinger Zeit (UTC+8) zurückgesetzt werden:

Zeitraum	Zurücksetzung
Pro Tag	Jeden Tag um 00:00 Uhr
Pro Woche	Jeden Montag um 00:00 Uhr
Pro Monat	Am 1. jedes Monats um 00:00 Uhr
Einmaliger Gesamtbetrag	Nie. Ist er aufgebraucht, kann dieser clientKey keine Aufgaben mehr erstellen; erhöhen Sie das Limit, um ihn weiter zu nutzen

• Gezählt werden die tatsächlich abgezogenen Punkte: Punkte, die bei fehlgeschlagenen Aufgaben oder Zeitüberschreitung erstattet werden, werden auch dem Limit wieder gutgeschrieben.
• Reicht der Rest des Limits im aktuellen Zeitraum für den Punkteabzug einer Aufgabe nicht aus, gibt createTask ERROR_KEY_QUOTA_EXCEEDED zurück. Es werden keine Punkte abgezogen, und es zählt nicht für die automatische Pausierung.
• In der Liste im Dashboard sehen Sie, wie viel jeder clientKey im aktuellen Zeitraum verbraucht hat und wann er das nächste Mal zurückgesetzt wird.
• Ein Limit ist kein eigenes Guthaben: Alle clientKey buchen vom selben Konto-Guthaben ab, und ist das Konto-Guthaben aufgebraucht, erhalten Sie wie gewohnt ERROR_ZERO_BALANCE.

Wenn Sie getBalance mit einem clientKey aufrufen, für den ein Limit gesetzt ist, ist balance der kleinere Wert aus Konto-Guthaben und Rest-Limit des aktuellen Zeitraums, und es gibt zusätzlich das Feld keyQuotaRemaining (verbleibendes Limit, in Punkten). Ein clientKey ohne Limit enthält dieses Feld nicht, die Antwort bleibt wie bisher.

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

IP-Whitelist

Ein clientKey mit IP-Whitelist funktioniert nur für Anfragen, die von den IPs in der Liste gesendet werden. Leer bedeutet keine Einschränkung.

• Tragen Sie die öffentliche IP des Rechners ein, der die YesCaptcha-API aufruft (die ausgehende IP), nicht den Proxy aus den Aufgabenparametern. Wenn mehrere Rechner die API aufrufen, tragen Sie die öffentliche IP jedes einzelnen ein.
• Eine IPv4- oder IPv6-Adresse oder ein CIDR-Bereich pro Zeile, bis zu 50 Einträge. Eine einzelne Adresse erlaubt nur diese eine IP.
• Schreiben Sie Bereiche als Netzwerkadresse: 203.0.113.0/24 ist zulässig, 203.0.113.5/24 nicht (die Host-Bits sind nicht 0).

203.0.113.10
198.51.100.0/24
2001:db8::/32

• Liegt die IP der Anfrage nicht in der Liste, geben createTask und getBalance ERROR_KEY_IP_NOT_ALLOWED zurück. Es werden keine Punkte abgezogen, und es zählt nicht für die automatische Pausierung.
• Wenn sich Ihre ausgehende IP ändert (Heim-Breitband, Cloud-Funktionen, rotierende Ausgangs-IPs), setzen Sie keine Whitelist oder tragen Sie den gesamten Bereich ein.

Ablaufdatum

• Jeder clientKey (auch der Haupt-Key) kann ein Ablaufdatum haben, das innerhalb der nächsten zehn Jahre liegen muss. Sie können es jederzeit ändern oder entfernen.
• Nach dem Ablauf geben createTask und getBalance mit diesem Key ERROR_KEY_EXPIRED zurück; es werden keine Punkte abgezogen. Bereits erstellte Aufgaben können weiterhin mit getTaskResult abgeholt werden.
• Wird ein clientKey lange nicht verwendet, setzt das System zum Schutz Ihres Kontos ein Ablaufdatum und erinnert Sie vor Ablauf per E-Mail. Dieses Ablaufdatum lässt sich nicht ändern: Erzeugen Sie einen neuen Haupt-Key (das Guthaben wechselt automatisch zum neuen) oder legen Sie einen neuen clientKey an und aktualisieren Sie dann Ihr Programm.

Guthaben, Limit gleichzeitiger Aufgaben und automatische Pausierung

• Guthaben: Alle clientKey buchen vom selben Konto-Guthaben ab. Aufladungen, VIP-Bonus, Empfehlungsprämien und Entwicklerbeteiligung gehören zum Konto, unabhängig davon, welchen clientKey Sie verwenden.
• Limit gleichzeitiger Aufgaben: gilt pro Konto; alle clientKey teilen sich dasselbe Limit. Siehe Limit gleichzeitiger Aufgaben und automatische Pausierung.
• Automatische Pausierung: gilt pro clientKey. Wird ein clientKey wegen zu vieler Fehler pausiert, sind die anderen nicht betroffen.

Zugehörige Fehlercodes

Fehlercode	Wann er zurückgegeben wird
ERROR_KEY_QUOTA_EXCEEDED	Der Rest des Limits im aktuellen Zeitraum reicht für diese Aufgabe nicht aus (createTask)
ERROR_KEY_IP_NOT_ALLOWED	Die IP der Anfrage steht nicht in der IP-Whitelist dieses clientKey (createTask, getBalance)
ERROR_KEY_EXPIRED	Der clientKey ist abgelaufen (createTask, getBalance)

Bei keinem von diesen werden Punkte abgezogen. Was zu tun ist, steht unter Fehlercodes.