Anotar as avaliações

Nesta página, explicamos como fornecer feedback sobre a precisão das avaliações criadas pelo reCAPTCHA Enterprise. Com essas informações, o reCAPTCHA Enterprise pode ajustar o modelo específico do site e fornecer um melhor desempenho para o site ao longo do tempo.

Quando anotar avaliações

Ao criar uma avaliação, o reCAPTCHA Enterprise fornece uma pontuação que ajuda a entender o nível de risco das interações do usuário. Posteriormente, quando o site tiver mais informações sobre as interações do usuário para determinar se ela foi legítima ou fraudulenta, será possível confirmar ou corrigir a avaliação do reCAPTCHA Enterprise. Para fazer isso, envie os IDs teste reCAPTCHA de volta ao Google rotulados como LEGITIMATE ou FRAUDULENT. Ao confirmar ou corrigir a avaliação do reCAPTCHA Enterprise, você melhora o desempenho dele no seu site.

Para melhorar o desempenho do reCAPTCHA Enterprise, é possível confirmar as anotações como verdadeiros positivos e verdadeiros negativos, além das anotações referentes a possíveis erros de avaliação. Por exemplo, para um usuário que autenticou usando o método de autenticação de dois fatores e recebeu uma pontuação alta de reCAPTCHA, a avaliação pode ser anotada como LEGITIMATE. Como alternativa, se a pontuação do reCAPTCHA era baixa e o site determinou que a interação foi fraudulenta ou abusiva, a avaliação pode ser anotada como FRAUDULENT.

A lista a seguir mostra mais informações sobre alguns exemplos de interações de usuário que indicam se ela é legítima ou fraudulenta:

• Estornos de cartão de crédito e outras evidências concretas de fraude indicam que uma transação financeira anterior foi fraudulenta.
• Uma conta nova que envia mensagens sinalizadas como spam por outros usuários pode indicar que a criação da conta foi fraudulenta.
• Um caso de suporte registrado se um usuário tiver dificuldade para fazer login na conta pode indicar que a tentativa de login é legítima.
• Uma compra ou reserva em um site que usa o reCAPTCHA Enterprise para se proteger contra a raspagem pode indicar que o usuário é legítimo.

Antes de começar

• Verifique se você tem o seguinte papel no Identity and Access Management: Agente do reCAPTCHA Enterprise (roles/recaptchaenterprise.agent).

• Dependendo de onde você configurou o reCAPTCHA Enterprise, conclua a etapa apropriada:

• Crie uma avaliação para seu site.

• Crie uma avaliação para seu aplicativo para dispositivos móveis.

• Configure sua integração do WAF.

Recuperar o ID da avaliação

Para anotar uma avaliação, recupere o ID exclusivo da avaliação das seguintes maneiras:

• Para integrações com Web e dispositivos móveis, é possível recuperar o ID exclusivo da avaliação da resposta da avaliação.

  Depois de criar uma avaliação, você receberá uma resposta JSON, conforme mostrado no exemplo a seguir.

  Extraia o ID de avaliação exclusivo do campo name na resposta 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 integrações de WAF, é possível recuperar o ID de avaliação exclusivo do token de reCAPTCHA. O ID exclusivo da avaliação é a string alfanumérica exclusiva de 16 caracteres que aparece no final do token de reCAPTCHA, após :U=. Por exemplo, se o token reCAPTFHA for .................U=6ZZZZe73fZZZZZZ0, o ID da avaliação será 6ZZZZe73fZZZZZZ0.

Anotar uma avaliação

1. Determine as informações e os rótulos a serem adicionados no corpo JSON da solicitação, dependendo do caso de uso.

   A tabela a seguir lista os rótulos e valores que podem ser usados para anotar eventos:

   Rótulo	Descrição	Exemplo de solicitação
   reasons	Opcional. Um rótulo para apoiar suas avaliações. Forneça detalhes do evento em tempo real no rótulo reasons em alguns segundos ou minutos após o evento, porque eles influenciam a detecção em tempo real. Para ver a lista de valores possíveis, consulte valores de motivos. Exemplo: para detectar invasões de conta, anote se a senha inserida estava correta com os valores CORRECT_PASSWORD ou INCORRECT_PASSWORD. Se você implantou sua própria MFA, poderá adicionar os seguintes valores: INITIATED_TWO_FACTOR e PASSED_TWO_FACTOR ou FAILED_TWO_FACTOR.	{ "reasons": ["INCORRECT_PASSWORD"] }
   annotation	Opcional. Um rótulo para indicar a legitimidade das avaliações. Forneça fatos sobre eventos de login e registro para validar ou corrigir suas avaliações de risco no rótulo annotation. Valores possíveis: LEGITIMATE ou FRAUDULENT. Envie essas informações a qualquer momento ou como parte de um job em lote. No entanto, recomendamos que essas informações sejam enviadas alguns segundos ou minutos após o evento, porque elas influenciam a detecção em tempo real.	{ "annotation": "LEGITIMATE" }

2. Anote uma avaliação usando o método projects.assessments.annotate com a CLI gcloud ou uma chave de API.

   Observação :se você estiver usando a versão v1beta1 da API, recomendamos usar a versão v1 porque os novos recursos, como a defesa de conta do reCAPTCHA Enterprise estão disponíveis apenas na versão v1. Para migrar da API v1beta1 para a v1, consulte Migrar da API v1beta para a API v1 .

   CLI da gcloud

   Antes de usar os dados da solicitação, faça as substituições a seguir:

   • ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create
   • ANNOTATION_LABEL: o rótulo que indica se a avaliação é legítima ou fraudulenta. Os valores possíveis são LEGITIMATE ou FRAUDULENT.
   • ANNOTATION_REASON: descreve o contexto da anotação escolhida para a avaliação. Para saber mais sobre os valores possíveis, consulte os motivos para anotar uma avaliação.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

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

   Para enviar a solicitação, escolha uma destas opções:

   curl

   Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

   Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

   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

   Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. É possível verificar a conta ativa atual executando gcloud auth list.

   Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

   $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

   Você receberá um código de status de êxito (2xx) e uma resposta vazia.

   Chave de API

   Antes de usar os dados da solicitação, faça as substituições a seguir:

   • ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create
   • ANNOTATION_LABEL: o rótulo que indica se a avaliação é legítima ou fraudulenta. Os valores possíveis são LEGITIMATE ou FRAUDULENT.
   • ANNOTATION_REASON: descreve o contexto da anotação escolhida para a avaliação. Para saber mais sobre os valores possíveis, consulte os motivos para anotar uma avaliação.

   Método HTTP e URL:

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

   Corpo JSON da solicitação:

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

   Para enviar a solicitação, escolha uma destas opções:

   curl

   Observação:crie uma chave de API para autenticar com a API.

   Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

   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

   Observação:crie uma chave de API para autenticar com a API.

   Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

   $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

   Você receberá um código de status de êxito (2xx) e uma resposta vazia.

A seguir

• Saiba mais sobre os recursos de proteção de contas de usuário do reCAPTCHA Enterprise.