Anotar as avaliações

No Google Cloud Fraud Defense, você anota as avaliações para fornecer feedback de informações empíricas sobre a precisão da avaliação e a legitimidade do usuário. Ao enviar resultados de interação e detalhes de verificação de volta para o Fraud Defense, você ajuda a ajustar o modelo específico do site e melhorar o desempenho de detecção ao longo do tempo.

Quando anotar as avaliações

O Fraud Defense fornece uma pontuação ao criar uma avaliação que ajuda a entender o nível de risco das interações do usuário. Depois, quando seu site tiver mais informações sobre as interações do usuário para determinar se elas foram legítimas ou fraudulentas, você poderá 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. Confirmar ou corrigir a avaliação do reCAPTCHA melhora o desempenho do Fraud Defense no seu site.

Para melhorar o desempenho do Fraud Defense, confirme as anotações de verdadeiros positivos e verdadeiros negativos, além das anotações de 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 Google Cloud Fraud Defense for baixa e seu site determinar que a interação foi fraudulenta ou abusiva, você poderá anotar a avaliação 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 Fraud Defense para se defender contra raspagem de dados 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 exclusivo dela das seguintes maneiras:

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

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

    Recupere o ID de avaliação exclusivo do campo name na resposta JSON.

    {
"tokenProperties": {
  "valid": true,
  "hostname": "www.google.com",
  "action": "homepage",
  "createTime": "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 do reCAPTCHA. O ID de avaliação exclusivo é a string alfanumérica exclusiva de 16 caracteres que aparece no final do token reCAPTCHA após :U=. Por exemplo, se o token 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 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 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 sequestros de conta, anote se a senha inserida estava correta com os valores CORRECT_PASSWORD ou INCORRECT_PASSWORD. Se você implantou 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. 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.

    É 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 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 da 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 abaixo: 

    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 abaixo: 

    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 abaixo: 

    $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