Annota le valutazioni

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

Quando annotare le valutazioni

Quando crei una valutazione, reCAPTCHA fornisce un punteggio che ti aiuta a comprendere il livello di rischio delle interazioni utente. In un secondo momento, quando il tuo sito avrà più informazioni sulle interazioni utente per determinare se l'interazione è legittima o fraudolenta, potrai confermare o correggere la valutazione di reCAPTCHA. Per farlo, invia gli ID dei test reCAPTCHA a Google etichettati come LEGITIMATE o FRAUDULENT. La conferma o la correzione della valutazione di reCAPTCHA migliora le prestazioni di reCAPTCHA per il tuo sito.

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

Il seguente elenco mostra ulteriori informazioni su alcuni esempi di interazioni utente che indicano se un'interazione utente è legittima o fraudolenta:

  • I chargeback delle carte di credito o altre prove concrete di frode indicano che una transazione finanziaria precedente era fraudolenta.
  • Un nuovo account che invia messaggi contrassegnati come spam da altri utenti potrebbe indicare che la creazione dell'account era fraudolenta.
  • Una richiesta di assistenza presentata se un utente 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 proteggersi dallo scraping potrebbe indicare che l'utente è legittimo.

Prima di iniziare

Recupera l'ID valutazione

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

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

    Dopo aver creato una valutazione, riceverai una risposta JSON come mostrato nell'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 che viene 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 tuo caso d'uso.

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

    Etichetta Descrizione Esempio di richiesta
    reasons Facoltativo. Un'etichetta per supportare le tue valutazioni.

    Fornisci i dettagli degli eventi in tempo reale nell' reasons etichetta in pochi secondi o minuti dopo l'evento perché influenzano il rilevamento in tempo reale.

    Per l'elenco dei valori possibili, vedi Valori dei motivi.

    Esempio: per rilevare i furti di account, annota se la password inserita era corretta con i valori CORRECT_PASSWORD o INCORRECT_PASSWORD. Se hai implementato la tua autenticazione a più fattori, 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 la legittimità delle valutazioni.

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

    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 in pochi secondi o minuti dopo l'evento, perché influenzano il rilevamento in tempo reale.

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. Annota una valutazione utilizzando il projects.assessments.annotate metodo con gcloud CLI o una chiave API.

    gcloud CLI

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

    • ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create.
    • ANNOTATION_LABEL: l'etichetta per indicare 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 scoprire i valori possibili, vedi 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 di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

    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, e quindi esegui il comando seguente: 

    $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 riuscito (2xx) e una risposta vuota.

    Chiave API

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

    • ASSESSMENT_ID: valore del campo name restituito dalla chiamata projects.assessments.create
    • ANNOTATION_LABEL: l'etichetta per indicare 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 scoprire i valori possibili, vedi 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 di queste opzioni:

    curl

    Salva il corpo della richiesta in un file denominato request.json, e quindi esegui il comando seguente: 

    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, e quindi esegui il comando seguente: 

    $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 riuscito (2xx) e una risposta vuota.

Passaggi successivi