Annota le valutazioni

Questa pagina spiega come puoi fornire un feedback sull'accuratezza delle valutazioni create da reCAPTCHA. Con queste informazioni, reCAPTCHA può ottimizzare il modello specifico per il tuo sito e migliorare il rendimento del tuo sito nel tempo.

Quando annotare le valutazioni

reCAPTCHA dà un punteggio durante la creazione di una valutazione ti aiuta a capire il livello di rischio delle interazioni degli utenti. In un secondo momento, quando il tuo sito avrà più informazioni sulle interazioni degli utenti per determinare se l'interazione è stata legittima o fraudolenta, potrai confermare o correggere la valutazione di reCAPTCHA. A tal fine, invia gli ID di valutazione reCAPTCHA a Google etichettati come LEGITIMATE o FRAUDULENT. La conferma o la correzione della valutazione di reCAPTCHA migliora il rendimento di reCAPTCHA per il tuo sito.

Per migliorare le prestazioni di reCAPTCHA, puoi confermare il per veri positivi e veri negativi, oltre ai annotazioni per potenziali errori di valutazione. Ad esempio, nel caso di un utente che ha eseguito l'autenticazione correttamente un metodo di autenticazione a due fattori e ha ricevuto un punteggio reCAPTCHA elevato, puoi annota il test come LEGITIMATE. In alternativa, se reCAPTCHA basso e il tuo sito ha stabilito che l'interazione era fraudolenta o offensivi, puoi annotare il test come FRAUDULENT.

Il seguente elenco mostra informazioni aggiuntive su alcuni utenti di esempio Interazioni che indicano se un'interazione dell'utente è legittima o fraudolento:

  • I riaccreditamenti della carta di credito o altre prove concrete di attività fraudolenta indicano che una transazione finanziaria precedente è stata fraudolenta.
  • Un nuovo account che invia messaggi segnalati come spam da altri utenti potrebbe indicare che la creazione dell'account è stata fraudolenta.
  • Una richiesta di assistenza inviata da un utente che ha difficoltà ad accedere al proprio account potrebbe indicare che il tentativo di accesso è legittimo.
  • Un acquisto o una prenotazione su un sito che utilizza reCAPTCHA per difendersi dallo scraping potrebbe indicare che l'utente è legittimo.

Prima di iniziare

Recupera l'ID valutazione

Per annotare una valutazione, recupera l'ID di valutazione univoco nella nei seguenti modi:

  • Per le integrazioni web e mobile, puoi recuperare l'ID test univoco dalla risposta della valutazione.

    Dopo aver creato una valutazione, ricevi una risposta JSON come mostrato in dall'esempio seguente.

    Recupera l'ID valutazione univoco dal campo name nella risposta 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'
}

  • Per le integrazioni WAF, puoi recuperare l'ID valutazione univoco dal token reCAPTCHA. L'ID valutazione univoco è la stringa alfanumerica univoca di 16 caratteri visualizzata alla fine del token reCAPTCHA dopo :U=. Ad esempio, se il token reCAPTCHA è .................U=6ZZZZe73fZZZZZZ0, l'ID valutazione è 6ZZZZe73fZZZZZZ0.

Annota una valutazione

  1. Determina le informazioni e le etichette da aggiungere nel corpo JSON della richiesta a seconda del caso d'uso.

    La tabella seguente elenca le etichette e i valori che puoi utilizzare per annotare gli eventi:

    Etichetta Descrizione Esempio di richiesta
    reasons Facoltativo. Un'etichetta a supporto delle tue valutazioni.

    Fornisci i dettagli degli eventi in tempo reale nell'etichetta reasons entro pochi secondi o minuti dall'evento, in quanto influiscono sul rilevamento in tempo reale.

    Per l'elenco valori possibili, consulta i valori dei motivi.

    Esempio: per rilevare le acquisizioni di account, annota se la password inserita era corretta con i valori CORRECT_PASSWORD o INCORRECT_PASSWORD. Se hai implementato la tua MFA, puoi aggiungere i seguenti valori: INITIATED_TWO_FACTOR e PASSED_TWO_FACTOR o FAILED_TWO_FACTOR. 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation Facoltativo. Un'etichetta per indicare legittimità delle valutazioni.

    Fornisci informazioni sugli eventi di accesso e registrazione per convalidare o correggere le valutazioni del rischio nell'etichetta annotation.

    Valori possibili: LEGITIMATE o FRAUDULENT.

    Puoi inviare queste informazioni in qualsiasi momento o nell'ambito di un job batch. Tuttavia, ti consigliamo di inviare queste informazioni entro pochi secondi o minuti dopo l'evento perché influiscono sul rilevamento in tempo reale.

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. Aggiungi annotazioni a una valutazione utilizzando il metodo projects.assessments.annotate con l'interfaccia a riga di comando gcloud o una chiave API.

    Interfaccia a riga di comando gcloud

    Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

    • ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create.
    • ANNOTATION_LABEL: l'etichetta che indica se la valutazione è legittima o fraudolenta. I valori possibili sono LEGITIMATE o FRAUDULENT.
    • ANNOTATION_REASON: descrive il contesto dell'annotazione scelta per questa valutazione. Per conoscere i valori possibili, consulta i motivi per annotare una valutazione.

    Metodo HTTP e URL: 

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

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

    Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

    Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.

    Chiave API

    Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:

    • ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create
    • ANNOTATION_LABEL: l'etichetta che indica se la valutazione è legittima o fraudolenta. I valori possibili sono LEGITIMATE o FRAUDULENT.
    • ANNOTATION_REASON: descrive il contesto dell'annotazione scelta per questa valutazione. Per informazioni sui possibili valori, consulta i motivi per annotare una valutazione.

    Metodo HTTP e URL: 

    POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

    Corpo JSON della richiesta: 

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

    Per inviare la richiesta, scegli una delle seguenti opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

    Salva il corpo della richiesta in un file denominato request.json. ed esegui questo 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

    Dovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.

Passaggi successivi