Anotar evaluaciones

En esta página se explica cómo puede enviar comentarios sobre la precisión de las evaluaciones creadas por reCAPTCHA. Con esta información, reCAPTCHA puede ajustar el modelo específico de tu sitio y mejorar su rendimiento con el tiempo.

Cuándo anotar evaluaciones

reCAPTCHA proporciona una puntuación al crear una evaluación que te ayuda a comprender el nivel de riesgo que suponen las interacciones de los usuarios. Más adelante, cuando tu sitio tenga más información sobre las interacciones de los usuarios para determinar si la interacción fue legítima o fraudulenta, podrás confirmar o corregir la evaluación de reCAPTCHA. Para ello, reenvía los IDs de evaluación de reCAPTCHA a Google y etiquétalos como LEGITIMATE o FRAUDULENT. Confirmar o corregir la evaluación de reCAPTCHA mejora el rendimiento de reCAPTCHA en tu sitio.

Para mejorar el rendimiento de reCAPTCHA, puede confirmar las anotaciones de verdaderos positivos y verdaderos negativos, además de las anotaciones de posibles errores de evaluación. Por ejemplo, en el caso de un usuario que se haya autenticado correctamente con un método de autenticación de dos factores y haya recibido una puntuación alta de reCAPTCHA, puedes anotar la evaluación como LEGITIMATE. Por otro lado, si la puntuación de reCAPTCHA era baja y tu sitio ha determinado que la interacción era fraudulenta o abusiva, puedes anotar la evaluación como FRAUDULENT.

En la siguiente lista se muestra información adicional sobre algunas interacciones de usuario de ejemplo que indican si una interacción de usuario es legítima o fraudulenta:

  • Las devoluciones de cargos de tarjetas de crédito u otras pruebas concretas de fraude indican que una transacción financiera anterior fue fraudulenta.
  • Una cuenta nueva que envía mensajes que otros usuarios marcan como spam podría indicar que la creación de la cuenta ha sido fraudulenta.
  • Si se registra un caso de asistencia porque un usuario tiene dificultades para iniciar sesión en su cuenta, puede indicar que el intento de inicio de sesión es legítimo.
  • Una compra o reserva en un sitio que usa reCAPTCHA para protegerse contra el scraping puede indicar que el usuario es legítimo.

Antes de empezar

Recuperar el ID de la evaluación

Para anotar una evaluación, obtén el ID único de la evaluación de las siguientes formas:

  • En el caso de las integraciones web y móviles, puede obtener el ID de evaluación único de la respuesta de la evaluación.

    Después de crear una evaluación, recibirás una respuesta JSON como la que se muestra en el siguiente ejemplo.

    Recupera el ID de evaluación único del campo name de la respuesta 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'
}

  • En las integraciones de WAF, puedes obtener el ID de evaluación único del token de reCAPTCHA. El ID de evaluación único es la cadena alfanumérica única de 16 caracteres que aparece al final del token de reCAPTCHA después de :U=. Por ejemplo, si el token de reCAPTCHA es .................U=6ZZZZe73fZZZZZZ0, el ID de evaluación es 6ZZZZe73fZZZZZZ0.

Anotar una evaluación

  1. Determina la información y las etiquetas que se deben añadir al cuerpo JSON de la solicitud en función de tu caso práctico.

    En la siguiente tabla se enumeran las etiquetas y los valores que puede usar para anotar eventos:

    Etiqueta Descripción Ejemplo de solicitud
    reasons Opcional. Una etiqueta para ayudarte con tus evaluaciones.

    Proporcione los detalles de los eventos en tiempo real en la etiqueta reasons unos segundos o minutos después de que se produzcan, ya que influyen en la detección en tiempo real.

    Para ver la lista de posibles valores, consulta los valores de los motivos.

    Ejemplo: Para detectar la apropiación de cuentas, anota si la contraseña introducida era correcta con los valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si has implementado tu propia MFA, puedes añadir los siguientes valores: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Opcional. Una etiqueta que indica la legitimidad de las evaluaciones.

    Proporciona datos sobre los eventos de inicio de sesión y registro para validar o corregir tus evaluaciones de riesgos en la etiqueta annotation.

    Valores posibles: LEGITIMATE o FRAUDULENT.

    Puede enviar esta información en cualquier momento o como parte de un trabajo por lotes. Sin embargo, le recomendamos que envíe esta información unos segundos o minutos después del evento, ya que influye en la detección en tiempo real.

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. Anota una evaluación con el método projects.assessments.annotate mediante gcloud CLI o una clave de API.

    CLI de gcloud

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • ASSESSMENT_ID: valor del campo name devuelto por la llamada projects.assessments.create.
    • ANNOTATION_LABEL: etiqueta que indica si la evaluación es legítima o fraudulenta. Los valores posibles son LEGITIMATE o FRAUDULENT.
    • ANNOTATION_REASON: describe el contexto de la anotación que se ha elegido para esta evaluación. Para obtener información sobre los posibles valores, consulta Motivos para anotar una evaluación.

    Método HTTP y URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

    Cuerpo JSON de la solicitud: 

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

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

    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/ASSESSMENT_ID:annotate"

    PowerShell

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

    $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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    Deberías recibir un código de estado que indique que la operación se ha realizado correctamente (2xx) y una respuesta vacía.

    Clave de API

    Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

    • ASSESSMENT_ID: valor del campo name devuelto por la llamada projects.assessments.create
    • ANNOTATION_LABEL: etiqueta que indica si la evaluación es legítima o fraudulenta. Los valores posibles son LEGITIMATE o FRAUDULENT.
    • ANNOTATION_REASON: describe el contexto de la anotación que se ha elegido para esta evaluación. Para obtener información sobre los posibles valores, consulta Motivos para anotar una evaluación.

    Método HTTP y URL: 

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

    Cuerpo JSON de la solicitud: 

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

    Para enviar tu solicitud, elige una de estas opciones:

    curl

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

    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

    Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

    $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

    Deberías recibir un código de estado que indique que la operación se ha realizado correctamente (2xx) y una respuesta vacía.

Siguientes pasos