Bewertungen annotieren

Auf dieser Seite wird erläutert, wie Sie Feedback zur Genauigkeit der von reCAPTCHA Enterprise erstellten Bewertungen geben können. Anhand dieser Informationen kann reCAPTCHA Enterprise Ihr Website-spezifisches Modell optimieren und im Laufe der Zeit die Leistung Ihrer Website verbessern.

Wann sollten Bewertungen annotiert werden?

reCAPTCHA Enterprise gibt beim Erstellen einer Bewertung eine Punktzahl an, mit der Sie das Risiko von Nutzerinteraktionen einschätzen können. Wenn Ihre Website später weitere Informationen zu Nutzerinteraktionen enthält, um festzustellen, ob die Interaktion legitim oder betrügerisch war, können Sie die Bewertung von reCAPTCHA Enterprise bestätigen oder korrigieren. Dazu senden Sie die reCAPTCHA-Bewertungs-IDs als LEGITIMATE oder FRAUDULENT zurück an Google. Durch Bestätigen oder Korrigieren der Bewertung von reCAPTCHA Enterprise wird die Leistung von reCAPTCHA Enterprise für Ihre Website verbessert.

Um die Leistung von reCAPTCHA Enterprise zu verbessern, können Sie die Annotationen für richtig positive und richtig negative Bewertungen zusätzlich zu den Annotationen für potenzielle Bewertungsfehler bestätigen. Beispiel: Sie können die Bewertung für einen Nutzer, der sich erfolgreich mit einer 2-Faktor-Authentifizierung authentifiziert und eine hohe reCAPTCHA-Punktzahl erhalten hat, als LEGITIMATE annotieren. Wenn die reCAPTCHA-Punktzahl niedrig war und Ihre Website feststellte, dass die Interaktion betrügerisch oder missbräuchlich war, können Sie die Bewertung als FRAUDULENT annotieren.

Folgende Liste enthält zusätzliche Informationen zu einigen beispielhaften Nutzerinteraktionen, bei denen angeben wird, ob eine Nutzerinteraktion legitim oder betrügerisch war:

  • Kreditkartenrückbuchungen oder andere konkrete Anzeichen für Betrug weisen darauf hin, dass eine frühere Finanztransaktion betrügerisch war.
  • Ein neues Konto, das Nachrichten sendet, die von anderen Nutzern als Spam markiert wurden, weist möglicherweise darauf hin, dass die Kontoerstellung betrügerisch war.
  • Ein Support-Fall, der eingereicht wird, wenn ein Nutzer Schwierigkeiten beim Einloggen in sein Konto hat, könnte darauf hinweisen, dass der Login-Versuch legitim ist.
  • Ein Kauf oder eine Buchung auf einer Website, die reCAPTCHA Enterprise zum Schutz vor Scraping verwendet, kann darauf hindeuten, dass der Nutzer legitim ist.

Hinweise

Prüfungs-ID abrufen

Rufen Sie die eindeutige Bewertungs-ID so ab, dass Sie eine Bewertung annotieren möchten:

  • Bei Web- und mobilen Integrationen können Sie die eindeutige Bewertungs-ID aus der Bewertungsantwort abrufen.

    Nachdem Sie eine Bewertung erstellt haben, erhalten Sie eine JSON-Antwort, wie im folgenden Beispiel gezeigt.

    Rufen Sie die eindeutige Bewertungs-ID aus dem Feld name in der JSON-Antwort ab.

    {
'tokenProperties': {
  'valid': True,
  'hostname': 'www.google.com',
  'action': 'homepage',
  'createTime': u'2019-03-28T12:24:17.894Z'
},
'riskAnalysis': {
  'score': 0.1,
  'reasons': ['AUTOMATION']
},
'event': {
  'token': 'RESPONSE_TOKEN',
  'siteKey': 'KEY_ID'
},
'name': 'ASSESSMENT_ID'
}

  • Für WAF-Integrationen können Sie die eindeutige Bewertungs-ID aus dem reCAPTCHA-Token abrufen. Die eindeutige Bewertungs-ID ist der eindeutige alphanumerische String mit 16 Zeichen, der am Ende des reCAPTCHA-Tokens nach :U= angezeigt wird. Wenn das reCAPTFHA-Token beispielsweise .................U=6ZZZZe73fZZZZZZ0 ist, lautet die Bewertungs-ID 6ZZZZe73fZZZZZZ0.

Bewertung annotieren

  1. Bestimmen Sie die Informationen und Labels, die je nach Anwendungsfall in den JSON-Text der Anfrage eingefügt werden sollen.

    In der folgenden Tabelle sind die Labels und Werte aufgeführt, mit denen Sie Ereignisse annotieren können:

    Label Beschreibung Beispiel für Anfrage
    reasons Optional. Ein Label für Ihre Bewertungen.

    Geben Sie einige Sekunden oder Minuten nach dem Ereignis Echtzeit-Ereignisdetails im Label reasons an, da sie die Echtzeiterkennung beeinflussen.

    Eine Liste der möglichen Werte finden Sie unter Werte für Gründe.

    Beispiel: Um Kontoübernahmen zu erkennen, vermerken Sie mit CORRECT_PASSWORD- oder INCORRECT_PASSWORD-Werten, ob das eingegebene Passwort korrekt ist. Wenn Sie Ihre eigene MFA bereitgestellt haben, können Sie die folgenden Werte hinzufügen: INITIATED_TWO_FACTOR und PASSED_TWO_FACTOR oder FAILED_TWO_FACTOR. 

    
      {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Optional. Ein Label zur Angabe der Legitimität von Bewertungen.

    Geben Sie im Label annotation Informationen zu Anmelde- und Registrierungsereignissen an, um Ihre Risikobewertungen zu validieren oder zu korrigieren.

    Mögliche Werte: LEGITIMATE oder FRAUDULENT.

    Sie können diese Informationen jederzeit oder als Teil eines Batchjobs senden. Wir empfehlen jedoch, diese Informationen einige Sekunden oder Minuten nach dem Ereignis zu senden, da sie die Echtzeiterkennung beeinflussen.

    		 
    
      {
       "annotation": "LEGITIMATE"
      }

  2. Annotieren Sie eine Bewertung mithilfe der Methode projects.assessments.annotate mit der gcloud CLI oder einem API-Schlüssel.

    gcloud-CLI

    Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

    • ASSESSMENT_ID: Wert des name-Felds, der vom projects.assessments.create-Aufruf zurückgegeben wurde
    • ANNOTATION_LABEL: Das Label, das angibt, ob die Bewertung legitim oder betrügerisch ist. Mögliche Werte sind LEGITIMATE und FRAUDULENT.
    • ANNOTATION_REASON: Beschreibt den Kontext für die Anmerkung, die für diese Bewertung ausgewählt wurde. Weitere Informationen zu möglichen Werten finden Sie unter Gründe für das Kommentieren einer Bewertung.

    HTTP-Methode und URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate

    JSON-Text der Anfrage: 

    {
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    curl -X POST \
        -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate"

    PowerShell

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

    API-Schlüssel

    Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:

    • ASSESSMENT_ID: Wert des name-Felds, der vom projects.assessments.create-Aufruf zurückgegeben wurde
    • ANNOTATION_LABEL: Das Label, das angibt, ob die Bewertung legitim oder betrügerisch ist. Mögliche Werte sind LEGITIMATE und FRAUDULENT.
    • ANNOTATION_REASON: Beschreibt den Kontext für die Anmerkung, die für diese Bewertung ausgewählt wurde. Weitere Informationen zu möglichen Werten finden Sie unter Gründe für das Kommentieren einer Bewertung.

    HTTP-Methode und URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

    JSON-Text der Anfrage: 

    {
"annotation": "ANNOTATION_LABEL"
"reasons": "ANNOTATION_REASON"
}

    Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:

    curl

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    curl -X POST \
        -H "Content-Type: application/json; charset=utf-8" \
        -d @request.json \
        "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY"

    PowerShell

    Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json und führen Sie den folgenden Befehl aus: 

    $headers = @{  }

    Invoke-WebRequest `
        -Method POST `
        -Headers $headers `
        -ContentType: "application/json; charset=utf-8" `
        -InFile request.json `
        -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content

    Sie sollten einen erfolgreichen Statuscode (2xx) und eine leere Antwort als Ausgabe erhalten.

Nächste Schritte