Anotar avaliações

Esta página explica como pode fornecer feedback sobre a precisão das avaliações criadas pelo reCAPTCHA. Com estas informações, o reCAPTCHA pode ajustar o seu modelo específico do site e oferecer um desempenho melhorado para o seu site ao longo do tempo.

Quando anotar avaliações

O reCAPTCHA fornece uma pontuação quando cria uma avaliação que ajuda a compreender o nível de risco que as interações dos utilizadores representam. Posteriormente, quando o seu site tiver mais informações sobre as interações dos utilizadores para determinar se a interação foi legítima ou fraudulenta, pode confirmar ou corrigir a avaliação do reCAPTCHA. Para o fazer, envia os IDs de avaliação do reCAPTCHA de volta para a Google etiquetados como LEGITIMATE ou FRAUDULENT. Confirmar ou corrigir a avaliação do reCAPTCHA melhora o desempenho do reCAPTCHA para o seu site.

Para melhorar o desempenho do reCAPTCHA, pode confirmar as anotações para verdadeiros positivos e verdadeiros negativos, além das anotações para potenciais erros de avaliação. Por exemplo, para um utilizador que foi autenticado com êxito através de um método de autenticação de dois fatores e recebeu uma pontuação elevada do reCAPTCHA, pode anotar a avaliação como LEGITIMATE. Em alternativa, se a pontuação do reCAPTCHA for baixa e o seu site determinar que a interação foi fraudulenta ou abusiva, pode anotar a avaliação como FRAUDULENT.

A lista seguinte mostra informações adicionais sobre algumas interações do utilizador de exemplo que indicam se uma interação do utilizador é legítima ou fraudulenta:

  • Os estornos de cartões de crédito ou outras provas concretas de fraude indicam que uma transação financeira anterior foi fraudulenta.
  • Uma nova conta que envia mensagens denunciadas como spam por outros utilizadores pode indicar que a criação da conta foi fraudulenta.
  • Um registo de apoio técnico apresentado se um utilizador tiver dificuldades em iniciar sessão na respetiva conta pode indicar que a tentativa de início de sessão é legítima.
  • Uma compra ou uma reserva num site que usa o reCAPTCHA para se defender contra a extração de dados pode indicar que o utilizador é legítimo.

Antes de começar

Recupere o ID da avaliação

Para anotar uma avaliação, obtenha o ID exclusivo da avaliação das seguintes formas:

  • Para integrações Web e para dispositivos móveis, pode obter o ID de avaliação exclusivo da resposta da avaliação.

    Depois de criar uma avaliação, recebe uma resposta JSON, conforme mostrado no exemplo seguinte.

    Obtenha 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, pode obter o ID de avaliação exclusivo do token do reCAPTCHA. O ID de avaliação exclusivo é a string alfanumérica exclusiva de 16 carateres 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 é 6ZZZZe73fZZZZZZ0.

Anote uma avaliação

  1. Determine as informações e as etiquetas a adicionar no corpo JSON do pedido consoante o seu exemplo de utilização.

    A tabela seguinte lista as etiquetas e os valores que pode usar para anotar eventos:

    Etiqueta Descrição Exemplo de pedido
    reasons Opcional. Uma etiqueta para apoiar as suas avaliações.

    Forneça detalhes de eventos em tempo real na etiqueta reasons em poucos segundos ou minutos após o evento, porque influenciam a deteção em tempo real.

    Para ver a lista de valores possíveis, consulte os valores de motivos.

    Exemplo: para detetar roubos de contas, anote se a palavra-passe introduzida estava correta com os valores CORRECT_PASSWORD ou INCORRECT_PASSWORD. Se implementou a sua própria MFA, pode adicionar os seguintes valores: INITIATED_TWO_FACTOR e PASSED_TWO_FACTOR ou FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Opcional. Uma etiqueta para indicar a legitimidade das avaliações.

    Forneça factos sobre eventos de início de sessão e registo para validar ou corrigir as suas avaliações de risco na etiqueta annotation.

    Valores possíveis: LEGITIMATE ou FRAUDULENT.

    Pode enviar estas informações em qualquer altura ou como parte de um trabalho em lote. No entanto, recomendamos que envie estas informações alguns segundos ou minutos após o evento, uma vez que influenciam a deteção em tempo real.

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. Anote uma avaliação através do método projects.assessments.annotate com a CLI gcloud ou uma chave da API.

    CLI gcloud

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • ASSESSMENT_ID: valor do campo name devolvido pela chamada projects.assessments.create.
    • ANNOTATION_LABEL: a etiqueta 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 os motivos para anotar uma avaliação.

    Método HTTP e URL: 

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

    Corpo JSON do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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/ASSESSMENT_ID:annotate"

    PowerShell

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

    Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

    Chave da API

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • ASSESSMENT_ID: valor do campo name devolvido pela chamada projects.assessments.create
    • ANNOTATION_LABEL: a etiqueta 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 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 do pedido: 

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

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte 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

    Deve receber um código de estado de êxito (2xx) e uma resposta vazia.

O que se segue?