Cette page explique comment envoyer des commentaires sur la précision des évaluations créées par reCAPTCHA Enterprise. Grâce à ces informations, reCAPTCHA Enterprise peut ajuster le modèle spécifique à votre site et l'améliorer au fil du temps.
Quand annoter les évaluations
reCAPTCHA Enterprise fournit un score lors de la création d'une évaluation qui vous aide à comprendre le niveau de risque des interactions utilisateur.
Plus tard, lorsque votre site aura plus d'informations sur les interactions des utilisateurs pour déterminer si l'interaction était légitime ou frauduleuse, vous pourrez confirmer ou corriger l'évaluation de reCAPTCHA Enterprise. Pour ce faire, vous devez renvoyer à Google les ID d'évaluation reCAPTCHA associés à l'étiquette LEGITIMATE
ou FRAUDULENT
.
Le fait de confirmer ou de corriger l'évaluation reCAPTCHA Enterprise améliore les performances de reCAPTCHA Enterprise pour votre site.
Pour améliorer les performances de reCAPTCHA Enterprise, vous pouvez confirmer les annotations de vrais positifs et de vrais négatifs en plus des annotations d'erreurs d'évaluation potentielles.
Par exemple, dans le cas d'un utilisateur qui s'est authentifié à l'aide d'une méthode d'authentification à deux facteurs et qui a reçu un score reCAPTCHA élevé, vous pouvez annoter l'évaluation comme LEGITIMATE
. Si le score reCAPTCHA est faible et que votre site détermine que l'interaction est frauduleuse ou abusive, vous pouvez annoter l'évaluation comme FRAUDULENT
.
La liste suivante contient des informations supplémentaires sur des exemples d'interactions utilisateur qui indiquent si une interaction est légitime ou frauduleuse :
- Les rejets de débit de carte de crédit ou d'autres preuves concrètes de fraude indiquent qu'une transaction financière antérieure était frauduleuse.
- Un nouveau compte qui envoie des messages signalés comme spam par d'autres utilisateurs peut indiquer que la création du compte est frauduleuse.
- Une demande d'assistance envoyée si un utilisateur rencontre des difficultés pour se connecter à son compte peut indiquer que la tentative de connexion est légitime.
- Un achat ou une réservation sur un site qui utilise reCAPTCHA Enterprise pour se protéger contre le scraping peut indiquer que l'utilisateur est légitime.
Avant de commencer
Assurez-vous de disposer du rôle Identity and Access Management suivant : agent reCAPTCHA Enterprise (
roles/recaptchaenterprise.agent
).Selon l'endroit où vous avez configuré reCAPTCHA Enterprise, procédez comme suit:
Récupérer l'ID d'évaluation
Pour annoter une évaluation, récupérez l'ID d'évaluation unique comme suit:
Pour les intégrations Web et mobiles, vous pouvez récupérer l'ID d'évaluation unique à partir de la réponse d'évaluation.
Après avoir créé une évaluation, vous recevez une réponse JSON comme illustré dans l'exemple suivant.
Récupérez l'ID d'évaluation unique à partir du champ
name
de la réponse JSON.{ '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' }
Pour les intégrations WAF, vous pouvez récupérer l'ID d'évaluation unique à partir du jeton reCAPTCHA. L'ID d'évaluation unique est la chaîne alphanumérique unique de 16 caractères qui apparaît à la fin du jeton reCAPTCHA après
:U=
. Par exemple, si le jeton reCAPTFHA est.................U=6ZZZZe73fZZZZZZ0
, l'ID d'évaluation est6ZZZZe73fZZZZZZ0
.
Annoter une évaluation
Déterminez les informations et les étiquettes à ajouter dans le corps JSON de la requête en fonction de votre cas d'utilisation.
Le tableau suivant répertorie les libellés et les valeurs que vous pouvez utiliser pour annoter des événements:
Libellé Description Exemple de requête reasons
Facultatif. Une étiquette pour étayer vos évaluations. Fournissez des détails sur les événements en temps réel dans le libellé
reasons
quelques secondes ou minutes après l'événement, car ils influencent la détection en temps réel.Pour obtenir la liste des valeurs possibles, consultez la section Valeurs des motifs.
Exemple: Pour détecter les piratages de compte, annotez si le mot de passe saisi était correct avec des valeurs
CORRECT_PASSWORD
ouINCORRECT_PASSWORD
. Si vous avez déployé votre propre MFA, vous pouvez ajouter les valeurs suivantes:INITIATED_TWO_FACTOR
,PASSED_TWO_FACTOR
ouFAILED_TWO_FACTOR
.{ "reasons": ["INCORRECT_PASSWORD"] }
annotation
Facultatif. Libellé indiquant la légitimité des évaluations. Le libellé
annotation
fournit des informations sur les événements de connexion et d'enregistrement pour valider ou corriger vos évaluations des risques.Valeurs possibles:
LEGITIMATE
ouFRAUDULENT
.Vous pouvez envoyer ces informations à tout moment ou dans le cadre d'un job par lot. Toutefois, nous vous recommandons d'envoyer ces informations dans les quelques secondes ou minutes suivant l'événement, car elles influent sur la détection en temps réel.
{ "annotation": "LEGITIMATE" }
Annotez une évaluation à l'aide de la méthode
projects.assessments.annotate
avec gcloud CLI ou une clé API.gcloud CLI
Avant d'utiliser les données de la requête, effectuez les remplacements suivants:
- ASSESSMENT_ID : valeur du champ
name
renvoyée par l'appelprojects.assessments.create
- ANNOTATION_LABEL: libellé indiquant si l'évaluation est légitime ou frauduleuse.
Les valeurs possibles sont
LEGITIMATE
ouFRAUDULENT
. - ANNOTATION_REASON: décrit le contexte de l'annotation choisie pour cette évaluation. Pour en savoir plus sur les valeurs possibles, consultez les raisons pour l'annotation d'une évaluation.
Méthode HTTP et URL :
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate
Corps JSON de la requête :
{ "annotation": "ANNOTATION_LABEL" "reasons": "ANNOTATION_REASON" }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé
request.json
, puis exécutez la commande suivante: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
Enregistrez le corps de la requête dans un fichier nommé
request.json
, puis exécutez la commande suivante:$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 ContentVous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.
Clé API
Avant d'utiliser les données de la requête, effectuez les remplacements suivants:
- ASSESSMENT_ID : valeur du champ
name
renvoyée par l'appelprojects.assessments.create
- ANNOTATION_LABEL: libellé indiquant si l'évaluation est légitime ou frauduleuse.
Les valeurs possibles sont
LEGITIMATE
ouFRAUDULENT
. - ANNOTATION_REASON: décrit le contexte de l'annotation choisie pour cette évaluation. Pour en savoir plus sur les valeurs possibles, consultez les raisons pour l'annotation d'une évaluation.
Méthode HTTP et URL :
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY
Corps JSON de la requête :
{ "annotation": "ANNOTATION_LABEL" "reasons": "ANNOTATION_REASON" }
Pour envoyer votre requête, choisissez l'une des options suivantes :
curl
Enregistrez le corps de la requête dans un fichier nommé
request.json
, puis exécutez la commande suivante: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
Enregistrez le corps de la requête dans un fichier nommé
request.json
, puis exécutez la commande suivante:$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 ContentVous devriez recevoir un code d'état indiquant le succès de l'opération (2xx), ainsi qu'une réponse vide.
- ASSESSMENT_ID : valeur du champ