Anotar as avaliações

Nesta página, explicamos como enviar feedback sobre a precisão das avaliações criadas 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 que as interações do usuário representam. Mais tarde, 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. Ao confirmar ou corrigir a avaliação do reCAPTCHA, você melhora o desempenho dele 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 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 para se proteger contra a raspagem pode indicar que o usuário é legítimo.

Antes de começar

Extrair o ID da avaliação

Para anotar uma avaliação, extraia o ID exclusivo da avaliação da seguinte maneira:

  • Para integrações da Web e de 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 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 com WAF, é possível extrair o ID de avaliação exclusivo do token do reCAPTCHA. O ID de avaliação exclusivo é a string alfanumérica única de 16 caracteres que aparece no final do token reCAPTCHA após :U=. Por exemplo, se o token reCAPTCHA for .................U=6ZZZZe73fZZZZZZ0, o ID de 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 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 apoiar suas avaliações.

    Forneça detalhes do evento em tempo real no rótulo reasons 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ê tiver implantado 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 rótulo annotation.

    Valores possíveis: LEGITIMATE ou FRAUDULENT.

    Você pode enviar essas informações a qualquer momento ou como parte de um job em lote. No entanto, recomendamos enviar essas informações 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.

    CLI da 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 esta 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 esta 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