Anota las evaluaciones

En esta página, se explica cómo puedes proporcionar comentarios sobre la precisión de las evaluaciones creadas por reCAPTCHA Enterprise. Con esta información, reCAPTCHA Enterprise puede ajustar el modelo específico para tu sitio y proporcionar un rendimiento mejorado con el paso del tiempo.

Cuándo anotar las evaluaciones

reCAPTCHA Enterprise proporciona una puntuación cuando se crea una evaluación que te 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 fue legítima o fraudulenta, podrás confirmar o corregir la evaluación de reCAPTCHA Enterprise. Para ello, envía los IDs de evaluación de reCAPTCHA a Google y los etiqueta como LEGITIMATE o FRAUDULENT. Confirmar o corregir la evaluación de reCAPTCHA Enterprise mejora el rendimiento de reCAPTCHA Enterprise en tu sitio.

Para mejorar el rendimiento de reCAPTCHA Enterprise, puedes confirmar las anotaciones de los verdaderos positivos y los verdaderos negativos, además de las anotaciones de los posibles errores de evaluación. Por ejemplo, para un usuario que se autenticó correctamente mediante 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 era baja y tu sitio determinó que la interacción fue fraudulenta o abusiva, puedes anotar la evaluación como FRAUDULENT.

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

• 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.
• Es posible que una cuenta nueva que envíe mensajes que otros usuarios marquen como spam indica 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 Enterprise para defenderte del scraping, puede indicar que el usuario es legítimo.

Antes de comenzar

• Asegúrate de tener el siguiente rol de Identity and Access Management: agente de reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).

• Según el lugar en el que hayas configurado reCAPTCHA Enterprise, completa el paso correspondiente:

• Crea una evaluación para tu sitio web.

• Crea una evaluación para tu aplicación para dispositivos móviles.

• Configura tu integración de WAF.

Recupera el ID de evaluación

Para anotar una evaluación, recupera el ID de evaluación único de las siguientes maneras:

• 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'
  }
  

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

Anota una evaluación

1. Determina la información y las etiquetas que quieres 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 tus evaluaciones. Proporciona detalles del evento en tiempo real en la etiqueta reasons 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 los valores de motivos. Ejemplo: Para detectar apropiaciones de cuentas, anota si la contraseña que se ingresó era correcta con los valores CORRECT_PASSWORD o INCORRECT_PASSWORD. Si implementaste tu propia MFA, puedes agregar los siguientes valores: INITIATED_TWO_FACTOR, y 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 riesgo 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, recomendamos enviar esta información en unos segundos o minutos después del evento, ya que influyen en la detección en tiempo real.	{ "annotation": "LEGITIMATE" }

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

   Nota: Si usas la versión v1beta1 de la API, te recomendamos que utilices la versión v1, ya que las funciones nuevas, como la protección de cuentas de reCAPTCHA Enterprise, solo están disponibles en la versión v1. Para migrar de v1beta1 a v1, consulta Cómo migrar de la API v1beta a la API v1 .

   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 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 más información sobre los valores posibles, consulta los motivos para anotar una evaluación.

   HTTP method and URL:

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

   Cuerpo JSON de la solicitud:

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

   Para enviar tu solicitud, elige una de estas opciones:

   curl

   Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

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

   PowerShell

   Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

   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/projects/PROJECT_ID/assessments/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 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 más información sobre los valores posibles, consulta los motivos para anotar una evaluación.

   HTTP method and 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

   Nota: Crea una clave de API para autenticar con la API.

   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

   Nota: Crea una clave de API para autenticar con la API.

   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?

• Obtén más información sobre las funciones de protección de cuentas de usuario de reCAPTCHA Enterprise.