Anotar as avaliações

Nesta página, explicamos como fornecer feedback sobre a precisão dos testes criados pelo reCAPTCHA. Com essas informações, o reCAPTCHA 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 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. Para fazer isso, envie os IDs de teste reCAPTCHA de volta ao Google rotulados como LEGITIMATE ou FRAUDULENT. A confirmação ou correção da avaliação do reCAPTCHA melhora o desempenho do reCAPTCHA no seu site.

Para melhorar o desempenho do reCAPTCHA, é 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 do usuário que indicam se uma interação do usuário é 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 para se proteger contra a raspagem pode indicar que o usuário é legítimo.

Antes de começar

Recuperar o ID da avaliação

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

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

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

    Recupere o ID da avaliação exclusivo no campo name da 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 do WAF, é possível recuperar o ID da avaliação exclusivo no token do reCAPTCHA. O ID da avaliação exclusivo é a string alfanumérica exclusiva de 16 caracteres que aparece no final do token do reCAPTCHA após :U=. Por exemplo, se o token do reCAPTCHA 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 ao corpo JSON da solicitação dependendo do seu 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 oferecer suporte às suas avaliações.

    Forneça detalhes de eventos em tempo real no reasons rótulo em alguns segundos ou minutos após o evento porque eles influenciam a detecção em tempo real.

    Para conferir a lista de valores possíveis, consulte Valores de motivos.

    Exemplo: para detectar aquisições de contas, anote se a senha inserida estava correta com os valores CORRECT_PASSWORD ou INCORRECT_PASSWORD. Se você implantou sua própria MFA, adicione 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 annotation rótulo.

    Valores possíveis: LEGITIMATE ou FRAUDULENT.

    É possível enviar essas informações a qualquer momento ou como parte de um job em lote. No entanto, recomendamos enviar essas informações em 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 projects.assessments.annotate método com a CLI gcloud ou uma chave de API.

    CLI gcloud

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

    • ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create.
    • ANNOTATION_LABEL: o rótulo para indicar 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 essa avaliação. Para saber mais sobre os valores possíveis, consulte Motivos para anotar uma avaliação.

    Método HTTP e URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/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

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

    PowerShell

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

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

    Chave de API

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

    • ASSESSMENT_ID: valor do campo name retornado pela chamada projects.assessments.create
    • ANNOTATION_LABEL: o rótulo para indicar 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 essa avaliação. Para saber mais sobre os valores possíveis, consulte 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

    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

    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 bem-sucedido (2xx) e uma resposta vazia.

A seguir