Como anotar uma avaliação

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.

Antes de começar

Crie uma avaliação.

Noções básicas sobre 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 confirmar ou corrigir a avaliação do reCAPTCHA Enterprise, é possível enviar os IDs de avaliação do 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.

Como recuperar o ID da avaliação

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

Para anotar uma avaliação, 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': 'SITE_KEY'
   },
  'name': u'ASSESSMENT_ID'
}

Como anotar a avaliação

Anote uma avaliação usando o método projects.assessments.annotate.

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

Antes de usar qualquer um dos dados da solicitação, faça as seguintes substituições:

• 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.

Método HTTP e URL:

POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

Corpo JSON da solicitação:

{
"annotation": "ANNOTATION_LABEL"
}

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

curl

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"

PowerShell

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo da chave privada da conta de serviço.

Salve o corpo da solicitação em um arquivo chamado request.json e execute o seguinte comando:

$cred = gcloud auth application-default 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.