Anota las evaluaciones

En esta página, se explica cómo puedes enviar comentarios sobre la exactitud de las evaluaciones que crea reCAPTCHA. Con esta información, reCAPTCHA puede ajustar el modelo específico de tu sitio y proporcionar un rendimiento mejorado con el tiempo.

Cuándo anotar las evaluaciones

reCAPTCHA proporciona una puntuación cuando crea una evaluación que ayuda a comprender el nivel de riesgo que representan las interacciones del usuario. Más adelante, cuando tu sitio tenga más información sobre las interacciones del usuario para determinar si la interacción fue legítima o fraudulenta, puede confirmar o una evaluación correcta de reCAPTCHA. Para ello, envía los IDs de evaluación de reCAPTCHA a Google etiquetados como LEGITIMATE o FRAUDULENT. Confirmación o corrección La evaluación de reCAPTCHA mejora el rendimiento de reCAPTCHA para tu sitio.

Para mejorar el rendimiento de reCAPTCHA, puedes confirmar el anotaciones para verdaderos positivos y verdaderos negativos, además del y anotaciones para detectar posibles errores de evaluación. Por ejemplo, para un usuario que se autenticó correctamente con un método de autenticación de 2 factores y recibió una puntuación alta de reCAPTCHA, puedes anotar la evaluación como LEGITIMATE. Como alternativa, si la puntuación de reCAPTCHA fue baja y tu sitio determinó que la interacción fue fraudulenta o abusiva, puedes anotar la evaluación como FRAUDULENT.

La siguiente lista muestra información adicional sobre algunos ejemplos Interacciones que indican si una interacción del usuario es legítima o fraudulento:

  • Las devoluciones de cargos de tarjetas de crédito o cualquier otra evidencia concreta de fraude indican que una transacción financiera anterior fue fraudulenta.
  • Una cuenta nueva que envía mensajes marcados como spam por otros usuarios podría indicar que la creación de la cuenta fue fraudulenta.
  • Un caso de asistencia presentado si un usuario tiene dificultades para acceder a su cuenta puede indicar que el intento de acceso es legítimo.
  • Una compra o reserva en un sitio que usa reCAPTCHA para realizar las siguientes acciones: defenderse contra el scraping podría indicar que el usuario es legítimo.

Antes de comenzar

Recupera el ID de evaluación

Para anotar una evaluación, recupera el ID de evaluación único en la de la siguiente manera:

  • En el caso de las integraciones web y para dispositivos móviles, puedes recuperar 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 se muestra en el siguiente ejemplo.

    Recupera el ID de evaluación único del campo name en 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 el caso de las integraciones de WAF, puedes recuperar 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 se .................U=6ZZZZe73fZZZZZZ0 y, luego, el ID de evaluación es 6ZZZZe73fZZZZZZ0.

Cómo anotar una evaluación

  1. Determina la información y las etiquetas que debes agregar en el cuerpo JSON de la solicitud según tu caso de uso.

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

    Etiqueta Descripción Ejemplo de solicitud
    reasons Opcional. Una etiqueta para respaldar tu y evaluaciones.

    Proporciona detalles del evento en tiempo real en la etiqueta reasons en unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.

    Para obtener la lista de valores posibles, consulta valores de motivos.

    Ejemplo: Para detectar apropiaciones de cuentas, anota si la contraseña ingresada era correcta con valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si implementaste tu propia MFA, puedes agregar los siguientes valores: INITIATED_TWO_FACTOR, PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

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

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

    Valores posibles: LEGITIMATE o FRAUDULENT.

    Puedes enviar esta información en cualquier momento o como parte de un trabajo por lotes. Sin embargo, te recomendamos que envíes esta información en unos segundos o minutos. después del evento porque influyen en la detección en tiempo real.

    		 
          {
       "annotation": "LEGITIMATE"
      }

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

    gcloud CLI

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • ASSESSMENT_ID: Es el valor del campo name que muestra la llamada a projects.assessments.create.
    • ANNOTATION_LABEL: Es la 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 eligió para esta evaluación. Para obtener información sobre los valores posibles, consulta los 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 exitoso (2xx) y una respuesta vacía.

    Clave de API

    Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

    • ASSESSMENT_ID: Es el valor del campo name que muestra la llamada a projects.assessments.create.
    • ANNOTATION_LABEL: Es la 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 eligió para esta evaluación. Si deseas obtener más información sobre los valores posibles, consulta los 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 exitoso (2xx) y una respuesta vacía.

¿Qué sigue?