為評估結果加上註解

本頁說明如何針對 reCAPTCHA 建立的評估結果準確度提供意見回饋。有了這項資訊，reCAPTCHA 就能微調網站專用模型，並隨著時間提升網站效能。

為評估結果加上註解的時機

建立評估時，reCAPTCHA 會提供分數，協助您瞭解使用者互動帶來的風險等級。稍後，當網站取得更多使用者互動資訊，可判斷互動是否合法或有詐欺行為時，您就能確認或修正 reCAPTCHA 的評估結果。如要這麼做，請將 reCAPTCHA 評估 ID 傳回 Google，並標示為 LEGITIMATE 或 FRAUDULENT。確認或修正 reCAPTCHA 的評估結果，有助於提升網站的 reCAPTCHA 效能。

如要提升 reCAPTCHA 的效能，除了潛在評估錯誤的註解外，您也可以確認真陽性和真陰性的註解。舉例來說，如果使用者透過雙重驗證方法成功完成驗證，並獲得高 reCAPTCHA 分數，您可以將評估結果標註為 LEGITIMATE。或者，如果 reCAPTCHA 分數偏低，且網站判定互動屬於詐欺或濫用行為，您可以將評估結果標註為 FRAUDULENT。

下表列出一些使用者互動範例的額外資訊，說明使用者互動是否正當或有詐欺嫌疑：

  • 信用卡退款或其他詐欺的具體證據，表示先前的金融交易有詐欺行為。
  • 如果新帳戶傳送的郵件遭其他使用者標示為垃圾郵件，可能表示該帳戶是透過詐欺手法建立。
  • 如果使用者無法登入帳戶而提出支援案件，可能表示登入嘗試是合法的。
  • 如果網站使用 reCAPTCHA 防範網頁內容擷取，使用者在該網站上進行購買或預訂，可能表示使用者是真人。

事前準備

擷取評估 ID

如要加註評估，請透過下列方式擷取專屬評估 ID：

  • 如果是網站和行動裝置整合，您可以從評估回應中擷取專屬評估 ID。

    建立評估後，您會收到 JSON 回應，如下列範例所示。

    從 JSON 回應的 name 欄位中擷取專屬評估 ID。

    {
'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'
}

  • 如果是 WAF 整合，您可以從 reCAPTCHA 權杖擷取專屬的評估 ID。專屬評估 ID 是 16 個字元的專屬英數字串，會顯示在 :U= 後方的 reCAPTCHA 權杖結尾。舉例來說，如果 reCAPTCHA 權杖是 .................U=6ZZZZe73fZZZZZZ0，評估 ID 就是 6ZZZZe73fZZZZZZ0。

為評估結果加上註解

  1. 根據您的用途，決定要在要求 JSON 主體中新增的資訊和標籤。

    下表列出可用於註解事件的標籤和值：

    標籤 說明 要求範例
    reasons (選用步驟) 支援評估作業的標籤。

    在活動發生後幾秒或幾分鐘內，於 reasons 標籤中提供即時活動詳細資料，因為這些資料會影響即時偵測。

    如需可能值的清單，請參閱原因值。

    示例：如要偵測帳戶遭盜用，請使用 CORRECT_PASSWORD 或 INCORRECT_PASSWORD 值，為輸入的密碼是否正確加上註解。如果您部署了自己的 MFA，可以新增下列值：INITIATED_TWO_FACTOR，以及 PASSED_TWO_FACTOR 或 FAILED_TWO_FACTOR。 

          {
      "reasons": ["INCORRECT_PASSWORD"]
      }
    annotation (選用步驟) 用來指出評估作業是否合法。

    提供登入和註冊事件的相關事實，以驗證或修正 annotation 標籤中的風險評估。

    可能的值：LEGITIMATE 或 FRAUDULENT。

    您可以隨時傳送這項資訊，也可以在批次作業中傳送。 不過，建議您在事件發生後幾秒或幾分鐘內傳送這項資訊，因為這會影響即時偵測。

    		 
          {
       "annotation": "LEGITIMATE"
      }

  2. 使用 gcloud CLI 或 API 金鑰，透過 projects.assessments.annotate 方法加註評估。

    gcloud CLI

    使用任何要求資料之前，請先替換以下項目：

    • ASSESSMENT_ID：從 projects.assessments.create 呼叫傳回的 name 欄位值。
    • ANNOTATION_LABEL：標籤，用來指出評估結果是正當或詐欺行為。可能的值為 LEGITIMATE 或 FRAUDULENT。
    • ANNOTATION_REASON：說明為這項評估選擇的註解內容。 如要瞭解可能的值，請參閱為評估加上註解的原因。

    HTTP 方法和網址：

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

    JSON 要求主體：

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

    如要傳送要求，請選擇以下其中一個選項：

    curl

    將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

    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

    將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

    $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

    您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

    API 金鑰

    使用任何要求資料之前，請先替換以下項目：

    • ASSESSMENT_ID：從 projects.assessments.create 呼叫傳回的 name 欄位值
    • ANNOTATION_LABEL：標籤，用來指出評估是否合法或有詐欺行為。可能的值為 LEGITIMATE 或 FRAUDULENT。
    • ANNOTATION_REASON：說明為這項評估選擇的註解內容。 如要瞭解可能的值，請參閱為評估加上註解的原因。

    HTTP 方法和網址：

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

    JSON 要求主體：

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

    如要傳送要求，請選擇以下其中一個選項：

    curl

    將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

    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

    將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

    $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

    您應該會收到執行成功的狀態碼 (2xx) 和空白回應。

後續步驟